RWA Risk (v3) - Webacy Docs

Overview

The v3 RWA Risk endpoints give you a Webacy-native structural risk score for stablecoins and real-world asset tokens. Unlike the Depeg Monitor — which tracks real-time price deviation — v3 RWA Risk evaluates the structural health of a token: collateral quality, smart contract governance, liquidity depth, exploit history, and more. Scores are updated on a 24-hour cadence and computed against a versioned grading scheme you can pin for consistency.

Endpoints

Token Detail

GET /v3/rwa/{address} — Full structural risk decomposition: composite grade, seven weighted categories, criterion-level pass/warn/fail status, and coverage metadata.

Batch Structural Health

POST /v3/rwa/batch/structural-health — Check up to 100 tokens in one call. 24h cadence. Always returns 200 with per-token results.

GET /v3/rwa/{address} requires a chain query parameter (for example eth); grading_scheme is optional and defaults to v2 (the standard scale). The batch endpoint takes { address, chain } pairs in the request body.

Key Concepts

Score Polarity

Higher score = more risk. This is the opposite of yield or performance scores.composite.score and all categories.*.score values are in the range 0–100, where 0 means no structural risk and 100 means maximum structural risk. The letter grade A+ corresponds to a score near 0 (best); F corresponds to a score near 100 (worst).

Composite Grade

Each token receives a composite score derived from seven weighted risk categories. The weights below are shared across both grading schemes (v2 reuses the v1 category weights — only the score-to-letter band mapping differs between schemes):

Category	Weight	Description
`asset_collateral`	30%	Collateral quality, reserve transparency, and backing type
`market_liquidity`	20%	On-chain liquidity depth and DEX/CEX accessibility
`smart_contract`	20%	Audit history, contract ownership model, and timelock presence
`operational_governance`	15%	Multisig controls, admin key practices, and operational hygiene
`hack_exploit_history`	15%	Known exploits or security incidents
`counterparty`	0%	(Reserved — weights may shift in future scheme versions)
`chain_infrastructure`	0%	(Reserved — weights may shift in future scheme versions)

The detail response also returns two composite-level fields, upstream_risk and clamped_by_upstream. When a token’s composite score is raised by risk inherited from an upstream dependency, upstream_risk carries that contributing score and clamped_by_upstream is true; when no upstream adjustment applies — as in the example below — they are null and false.

Letter Grades and Stars

The composite risk score maps to a letter grade on the standard 11-band scale (grading scheme v2). It is a risk rating: lower risk earns a better grade — A+ is the lowest risk, F is the highest. Bands are tighter at the safe end and widen as risk rises.

Grade	Stars	Risk score	Interpretation
A+	★★★★★	0–5	Excellent structural health
A	★★★★★	6–12	Strong — minor concerns only
A-	★★★★★	13–20	Strong — a couple of watchpoints
B+	★★★★☆	21–28	Good — minor structural risk
B	★★★★☆	29–37	Good — a few watchpoints
B-	★★★★☆	38–46	Adequate — review recommended
C+	★★★☆☆	47–56	Moderate risk — review recommended
C	★★★☆☆	57–66	Moderate risk — monitor closely
C-	★★★☆☆	67–77	Elevated risk — close monitoring needed
D	★★☆☆☆	78–88	High risk — close monitoring needed
F	★☆☆☆☆	89–100	Critical structural risk

Criterion Status

Each criterion in a category has one of three statuses:

Status	Meaning
`pass`	Criterion is satisfied — no risk contribution
`warn`	Criterion is partially met or data quality is limited
`fail`	Criterion is not met — contributes to category score

`large_holder_concentration` — Herfindahl Grading

The large_holder_concentration criterion is graded on the Herfindahl Concentration Index (HCI) computed across the top-10 holders:

HCI Range	Status
`hci_10 < 0.20`	`pass` — broadly distributed
`0.20 ≤ hci_10 < 0.40`	`warn` — moderate concentration
`hci_10 ≥ 0.40`	`fail` — highly concentrated
`null` (data unavailable)	`warn`

Data Quality

Every criterion carries a data_quality block:

{
  "confidence": "high",
  "last_observed_at": "2026-05-20T12:00:00Z",
  "source": "webacy"
}

confidence is "high", "medium", or "low". Use last_observed_at to surface data staleness to your users.

Coverage — Live vs. Planned

The v3 framework defines more criteria than are currently live. The coverage block in every detail response tells you exactly which criteria are active today vs. pending producer data.

Criterion	Category	Live?
`audited`	`smart_contract`	Yes
`mint_cap_present`	`smart_contract`	Yes
`owner_is_multisig`	`smart_contract`	Yes
`timelock_present`	`smart_contract`	Yes
`share_price_stable`	`asset_collateral`	Yes
`mint_burn_anomaly`	`market_liquidity`	Yes
`large_holder_concentration`	`market_liquidity`	Yes
`no_exploit_history`	`hack_exploit_history`	Yes
`supply_reserves_reconciliation`	`asset_collateral`	Planned
`large_transaction_alerts`	`market_liquidity`	Planned
`admin_key_changes`	`operational_governance`	Planned
`timelock_changes`	`operational_governance`	Planned

Planned criteria are excluded from scoring until their producer tables are ready. When they go live, scores will shift — pin a grading scheme (see below) if you need stability.

Grading Scheme Versioning

grading_scheme defaults to v2, the standard 11-band scale (lower risk = better grade) shared across every Webacy grade surface. The scheme version is reflected in:

The composite.grading_scheme field in the response body
The Webacy-Grading-Scheme response header

v1 is the frozen legacy scale — it uses an E band and has no C+. Pin ?grading_scheme=v1 to keep v1-computed grades byte-for-byte. v1 is now deprecated with a minimum 9-month sunset window; responses pinned to v1 carry RFC 8594 Deprecation / Sunset headers. Both schemes appear in supported_schemes.

The batch endpoint (POST /v3/rwa/batch/structural-health) emits raw criterion data only — no composite score, no grading scheme parameter. It is always scheme-neutral. Today it evaluates two live criteria — mint_burn_anomaly and large_holder_concentration; additional structural criteria will be added as their producer data goes live.

Authentication

All v3 RWA endpoints require an x-api-key header. Requests without a valid key return 403.

curl -H "x-api-key: $API_KEY" "https://api.webacy.com/v3/rwa/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48?chain=eth"

Response Headers

Every response (including 4xx errors) includes:

Header	Example	Description
`Webacy-Api-Version`	`3.0`	API version
`Webacy-Framework-Version`	`v1`	Scoring framework version
`Webacy-Grading-Scheme`	`v2`	Grading scheme applied

Batch Partial-Success Semantics

The request is validated first. A malformed batch returns 400 Bad Request and no tokens are evaluated:

empty tokens array
more than 100 tokens
unknown or unexpected properties in the body

Once the request is well-formed, the batch endpoint always returns HTTP 200. Check each result’s ok field:

ok: true — criterion data is present
ok: false — token could not be evaluated; read error_code

`error_code`	Meaning
`NOT_FOUND`	Token address/chain not in Webacy universe
`INVALID_ADDRESS`	Address string is not a valid contract address
`UNSUPPORTED_CHAIN`	Chain identifier is not supported

Code Examples

curl -X GET \
  "https://api.webacy.com/v3/rwa/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48?chain=eth&grading_scheme=v2" \
  -H "x-api-key: $API_KEY"

curl -X POST \
  "https://api.webacy.com/v3/rwa/batch/structural-health" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": [
      { "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "chain": "eth" },
      { "address": "0xdac17f958d2ee523a2206206994597c13d831ec7", "chain": "eth" }
    ]
  }'

Example: Token Detail Response

{
  "schema_version": "3.0",
  "metadata": {
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "chain": "eth",
    "symbol": "USDC",
    "name": "USD Coin",
    "asset_type": "stablecoin",
    "market_cap_usd": 43000000000
  },
  "composite": {
    "grading_scheme": "v2",
    "grade": "A+",
    "stars": 5,
    "score": 4,
    "contributors": {
      "asset_collateral":       { "score": 2, "weight": 0.30 },
      "market_liquidity":       { "score": 5, "weight": 0.20 },
      "smart_contract":         { "score": 3, "weight": 0.20 },
      "operational_governance": { "score": 8, "weight": 0.15 },
      "hack_exploit_history":   { "score": 0, "weight": 0.15 },
      "counterparty":           { "score": 0, "weight": 0 },
      "chain_infrastructure":   { "score": 0, "weight": 0 }
    },
    "upstream_risk": null,
    "clamped_by_upstream": false
  },
  "categories": {
    "smart_contract": {
      "score": 3,
      "criteria": {
        "audited": {
          "status": "pass",
          "data_quality": { "confidence": "high", "last_observed_at": "2026-05-01T00:00:00Z", "source": "webacy" }
        },
        "mint_cap_present": {
          "status": "pass",
          "data_quality": { "confidence": "high", "last_observed_at": "2026-05-20T12:00:00Z", "source": "webacy" }
        },
        "owner_is_multisig": {
          "status": "pass",
          "data_quality": { "confidence": "high", "last_observed_at": "2026-05-20T12:00:00Z", "source": "webacy" }
        },
        "timelock_present": {
          "status": "warn",
          "data_quality": { "confidence": "medium", "last_observed_at": "2026-05-20T12:00:00Z", "source": "webacy" }
        }
      }
    },
    "market_liquidity": {
      "score": 5,
      "criteria": {
        "mint_burn_anomaly": {
          "status": "pass",
          "data_quality": { "confidence": "high", "last_observed_at": "2026-05-31T18:00:00Z", "source": "webacy" }
        },
        "large_holder_concentration": {
          "status": "warn",
          "data_quality": { "confidence": "high", "last_observed_at": "2026-05-31T18:00:00Z", "source": "webacy" }
        }
      }
    }
  },
  "coverage": {
    "framework_version": "v1",
    "total_criteria": 12,
    "live_criteria": 8,
    "per_category": {
      "smart_contract":         { "live": 4, "total": 4 },
      "asset_collateral":       { "live": 1, "total": 2 },
      "market_liquidity":       { "live": 2, "total": 3 },
      "operational_governance": { "live": 0, "total": 2 },
      "hack_exploit_history":   { "live": 1, "total": 1 },
      "counterparty":           { "live": 0, "total": 0 },
      "chain_infrastructure":   { "live": 0, "total": 0 }
    }
  }
}

Example: Batch Response (partial success)

{
  "schema_version": "3.0",
  "results": [
    {
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "chain": "eth",
      "ok": true,
      "mint_burn_anomaly": {
        "status": "pass",
        "data_quality": { "confidence": "high", "last_observed_at": "2026-05-31T18:00:00Z", "source": "webacy" }
      },
      "large_holder_concentration": {
        "status": "warn",
        "data_quality": { "confidence": "high", "last_observed_at": "2026-05-31T18:00:00Z", "source": "webacy" }
      }
    },
    {
      "address": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
      "chain": "eth",
      "ok": false,
      "error_code": "NOT_FOUND"
    }
  ]
}

Depeg Monitor

Real-time price-deviation risk for stablecoins — pairs well with v3 structural scores

Holder Concentration Index

Deeper HCI data and historical concentration trends

Scoring Methodology

How Webacy computes risk scores across all product lines

API Authentication

How to obtain and use your x-api-key

​Overview

​Endpoints

Token Detail

Batch Structural Health

​Key Concepts

​Score Polarity

​Composite Grade

​Letter Grades and Stars

​Criterion Status

​large_holder_concentration — Herfindahl Grading

​Data Quality

​Coverage — Live vs. Planned

​Grading Scheme Versioning

​Authentication

​Response Headers

​Batch Partial-Success Semantics

​Code Examples

​Example: Token Detail Response

​Example: Batch Response (partial success)

​Related Resources

Depeg Monitor

Holder Concentration Index

Scoring Methodology

API Authentication

Overview

Endpoints

Key Concepts

Score Polarity

Composite Grade

Letter Grades and Stars

Criterion Status

`large_holder_concentration` — Herfindahl Grading

Data Quality

Coverage — Live vs. Planned

Grading Scheme Versioning

Authentication

Response Headers

Batch Partial-Success Semantics

Code Examples

Example: Token Detail Response

Example: Batch Response (partial success)

Related Resources