> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webacy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RWA Risk (v3)

> Use the Webacy V3 RWA endpoints for structural risk on stablecoins and tokenized real-world assets — composite grades, category scores, and coverage.

## 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](../api-reference/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

<CardGroup cols={2}>
  <Card title="Token Detail" icon="magnifying-glass-chart" href="../api-reference/rwa-v3/get-rwa-risk-detail">
    `GET /v3/rwa/{address}` — Full structural risk decomposition: composite grade, seven weighted categories, criterion-level pass/warn/fail status, and coverage metadata.
  </Card>

  <Card title="Batch Structural Health" icon="list-check" href="../api-reference/rwa-v3/post-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.
  </Card>
</CardGroup>

`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

<Warning>
  **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).
</Warning>

### 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                          |
| ------------------------------- | ----- | ---------- | --------------------------------------- |
| <span class="gb gb-a">A+</span> | ★★★★★ | 0–5        | Excellent structural health             |
| <span class="gb gb-a">A</span>  | ★★★★★ | 6–12       | Strong — minor concerns only            |
| <span class="gb gb-a">A-</span> | ★★★★★ | 13–20      | Strong — a couple of watchpoints        |
| <span class="gb gb-b">B+</span> | ★★★★☆ | 21–28      | Good — minor structural risk            |
| <span class="gb gb-b">B</span>  | ★★★★☆ | 29–37      | Good — a few watchpoints                |
| <span class="gb gb-b">B-</span> | ★★★★☆ | 38–46      | Adequate — review recommended           |
| <span class="gb gb-c">C+</span> | ★★★☆☆ | 47–56      | Moderate risk — review recommended      |
| <span class="gb gb-c">C</span>  | ★★★☆☆ | 57–66      | Moderate risk — monitor closely         |
| <span class="gb gb-c">C-</span> | ★★★☆☆ | 67–77      | Elevated risk — close monitoring needed |
| <span class="gb gb-d">D</span>  | ★★☆☆☆ | 78–88      | High risk — close monitoring needed     |
| <span class="gb gb-f">F</span>  | ★☆☆☆☆ | 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:

```json theme={null}
{
  "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`.

<Note>
  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.
</Note>

***

## Authentication

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

```bash theme={null}
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

<CodeGroup>
  ```bash Get token detail theme={null}
  curl -X GET \
    "https://api.webacy.com/v3/rwa/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48?chain=eth&grading_scheme=v2" \
    -H "x-api-key: $API_KEY"
  ```

  ```bash Batch structural health theme={null}
  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" }
      ]
    }'
  ```
</CodeGroup>

### Example: Token Detail Response

```json theme={null}
{
  "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)

```json theme={null}
{
  "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"
    }
  ]
}
```

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Depeg Monitor" icon="chart-line" href="../api-reference/depeg-monitor">
    Real-time price-deviation risk for stablecoins — pairs well with v3 structural scores
  </Card>

  <Card title="Holder Concentration Index" icon="users" href="../api-reference/holder-concentration">
    Deeper HCI data and historical concentration trends
  </Card>

  <Card title="Scoring Methodology" icon="calculator" href="../scoring-methodology">
    How Webacy computes risk scores across all product lines
  </Card>

  <Card title="API Authentication" icon="key" href="../api-reference/authentication">
    How to obtain and use your `x-api-key`
  </Card>
</CardGroup>