> ## 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.
# Vault Risk V3
> Explore the V3 vault risk surface — composite grades, per-category contributors, the full criteria taxonomy, and coverage disclosure for every vault.
## Overview
The V3 vault risk surface (`/v3/*`) is a new, versioned API that builds on top of the v2 risk pipeline. It introduces:
* A **composite letter grade** (`A+`–`F`) plus an underlying 0–100 score.
* **Per-category contributors** with explicit weights, so you can see exactly which categories drove a vault's score.
* A **dense criteria taxonomy** (`pass` / `warn` / `fail` per criterion) across all seven Webacy risk categories.
* **Coverage disclosure** — every response tells you how many criteria are live versus planned.
* A pass-through `risk` envelope identical to v2 for clients that already consume the standard Webacy risk format.
v2 endpoints are unversioned (no path prefix, e.g. `/vaults/{address}`) and frozen but supported. New integrations should target V3; existing integrations have a migration window — see the [v2 → V3 migration guide](/api-reference/migrations/v2-to-v3).
## Endpoints
`GET /v3/vaults/{address}?chain={chain}` — Composite grade, category contributors, criteria taxonomy, coverage disclosure, and the v2 `risk` envelope.
`GET /v3/framework` — Public endpoint returning the full criteria taxonomy and live/planned status. No API key required.
## Supported chains
Vault v3 covers **9 chains**: `eth`, `arb`, `base`, `opt`, `pol`, `bsc`, `avax`, `gnosis`, `sol`.
Chains outside this list return `400 "Invalid chain"`, even if accepted by a shared parameter enum.
***
## Versioning contract
V3 responses carry a stable contract on every request. Pin it and you get reproducible scoring across the deprecation window.
### URL path
`/v3/...` — parallel to the unversioned v2 root paths. The major version lives in the path; minor revisions ship under the same path with additive fields. Never use `/api/` — the prod gateway strips it and returns `403 Missing Authentication Token`.
### Response body
Every V3 response includes a top-level `schema_version` field (currently `"3.0"`).
### Response headers
| Header | Value | Meaning |
| -------------------------- | ----- | ------------------------------------------------------------- |
| `Webacy-Api-Version` | `3.0` | Major.minor version of the response schema |
| `Webacy-Framework-Version` | `v1` | Which criteria taxonomy was used to score this response |
| `Webacy-Grading-Scheme` | `v2` | Which letter-grade mapping was used (echoes the resolved pin) |
### Query parameters for pinning
| Parameter | Default | Behavior on unknown value |
| ----------------------- | ------- | ------------------------------------------------------- |
| `?framework_version=v1` | `v1` | `400` with `{ error, supported_versions: ['v1'] }` |
| `?grading_scheme=v2` | `v2` | `400` with `{ error, supported_schemes: ['v1', 'v2'] }` |
Both default, but **pinning is the contract**. Clients that don't pin will silently re-score when a new framework or scheme version ships. See [Pin from day one](/api-reference/migrations/v2-to-v3#pin-from-day-one) in the migration guide.
***
## Score polarity
**V3 numeric scores follow risk-magnitude polarity: higher = worse.**
`composite.score`, `categories[].score`, and `composite.contributors[].score` are all on a 0–100 scale where **0 represents the lowest risk** and **100 represents the highest risk**. This matches the polarity of `risk.score` and `risk.overallRisk` from v2 on the same response.
Letter grades preserve the conventional mapping: **`A+` is the best (lowest risk)**, **`F` is the worst (highest risk)**. So a vault with a low numeric score earns a high letter grade.
If you're building dashboards, make sure your sort, color, and threshold logic treat higher numbers as *worse*, not better.
### Worked example
A vault that scores `64` lands at **`C`**:
```jsonc theme={null}
{
"schema_version": "3.0",
"composite": {
"grading_scheme": "v2",
"grade": "C", // A+..F, A+ = best (lowest risk)
"score": 64.0, // 0–100, HIGHER = WORSE
"stars": 3,
"contributors": {
"smart_contract": { "score": 10, "weight": 0.20 },
"operational_governance": { "score": 25, "weight": 0.20 },
"asset_collateral": { "score": 0, "weight": 0.15 },
"market_liquidity": { "score": 10, "weight": 0.20 },
"counterparty": { "score": 0, "weight": 0.10 },
"hack_exploit_history": { "score": 25, "weight": 0.15 },
"chain_infrastructure": { "score": 0, "weight": 0.00 }
},
"upstream_risk": 64,
"clamped_by_upstream": true
}
}
```
The framework-weighted composite of the contributors above is below 64, but the response's `composite.score` is `64`. That's not a bug — read the next section.
***
## The upstream floor
**`composite.score = max(framework_composite, upstream_risk)`.**
The composite is *floored from below* by `upstream_risk`, which is a verbatim copy of `risk.overallRisk` from the v2 envelope. When the v2 pipeline detects high upstream risk (active exploits, sanctioned counterparties, severe protocol issues), the V3 composite cannot grade better than that signal allows — even if every framework criterion looks clean.
The boolean `clamped_by_upstream: true` is the visible red flag. When you see it, the contributors below tell you what the framework saw, and `upstream_risk` tells you what the v2 pipeline saw — the worse of the two wins.
### When you'll see this
A vault might show every category contributor near zero and still grade `C-` or worse. That happens when `risk.overallRisk` on the same response is elevated. Surface `clamped_by_upstream` in your UI alongside the contributors so users understand why a clean-looking vault has a high score — the framework wasn't blind, the upstream pipeline just had the louder signal.
***
## Explainability
The grade is the same grade it has always been — V3 now also tells you *why* it landed there. The vault detail response includes a machine-readable breakdown of which subcategory drove the grade down and the real numbers behind each check, so you can answer "why is this vault a `B+` and not an `A`?" straight from the payload instead of inferring it from the contributors table.
### Drivers
On the detail endpoints, `composite.drivers` is a ranked list (descending by `weighted_contribution`) of the subcategories pulling the grade down — worst offender first. Each driver carries its score, weight, and weighted contribution, plus the specific `warn`/`fail` criteria within it:
```jsonc theme={null}
{
"composite": {
"score_source": "framework",
"drivers_complete": true,
"contributors": {
"smart_contract": { "score": 41.5, "weight": 0.20, "weighted_contribution": 8.3 }
// ...other categories
},
"drivers": [
{
"category": "smart_contract",
"category_name": "Smart contract",
"score": 41.5, "weight": 0.20, "weighted_contribution": 8.3,
"criteria": [
{
"key": "audited",
"name": "Has third-party audits",
"status": "warn",
"evidence": { "audit_count": 1, "auditor_tier": "mid" }
}
]
}
]
}
}
```
### Per-criterion evidence
Every criterion in the response now carries two explainability fields:
* `name` — a human-readable label for the check (e.g. `large_holder_concentration` → "Large-holder concentration bounded").
* `evidence` — the actual numbers behind the verdict, such as `{ "hci_10": 0.34 }` for holder concentration or `{ "audit_count": 1, "auditor_tier": "mid" }` for audit coverage. Tag-driven criteria with no underlying number instead carry `{ "triggered_by_tag": "" }`. `evidence` is omitted when no value is available, so treat it as present-when-known rather than guaranteed.
### Composite-level fields
* `composite.contributors[*].weighted_contribution` — `score × weight`, i.e. how much each subcategory moved the grade. It quantifies the contributors table you already render.
* `composite.score_source` — `"framework"` or `"upstream"`. The explicit companion to `clamped_by_upstream`: it names whether the grade came from the V3 weighted model or was floored by overall pipeline risk.
* `composite.drivers_complete` — boolean, detail endpoints only. When `true`, `drivers` fully explains the grade, and an empty `drivers: []` means a genuinely clean grade. When `false`, the grade was floored by upstream pipeline risk, so `drivers` reflects only the framework sub-signal and may be empty even on a bad grade — in that case read `upstream_risk`, not "no risk."
### Where these fields appear
`drivers` and `drivers_complete` are on the **detail endpoints** (`GET /v3/vaults/{address}`, `GET /v3/rwa/{address}`). The batch and list responses stay lean — they don't carry the per-driver breakdown — but the composite-level fields still ride along, so `score_source` and `contributors[].weighted_contribution` are available there too.
These fields are additive: the response includes them when the data is available, and existing integrations that only read `grade` and `score` keep working unchanged. For the full field-by-field schema, see the [Vault Detail (V3) reference](/api-reference/vault-risk-v3/get-vault-risk-detail-v3).
***
## Categories
All V3 responses include scores for **seven** Webacy risk categories. Today **28 of 42** criteria ship live; the rest are present in the taxonomy with `live: false`.
| Key | Name | Weight | What it measures |
| ------------------------ | ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `smart_contract` | Smart contract | 0.20 | Audit history, contract ownership model, timelock presence, and Webacy's real-time contract analysis |
| `operational_governance` | Operational governance | 0.20 | Multisig controls, admin key practices, and operational hygiene |
| `asset_collateral` | Asset & collateral | 0.15 | Collateral quality, asset integrity, reserve transparency, backing type, and share-price (depeg) stability |
| `market_liquidity` | Market & liquidity | 0.20 | On-chain liquidity depth and exit/redemption accessibility |
| `counterparty` | Counterparty | 0.10 | Exposure to external protocols, custodians, and other dependencies |
| `hack_exploit_history` | Hack & exploit history | 0.15 | Known exploits or security incidents |
| `chain_infrastructure` | Chain infrastructure | 0.00 | Underlying-chain risk (reserved — zero weight today) |
`chain_infrastructure` has zero weight today (the category is present so the schema is stable) and may become non-zero in a future scheme version. The category's `criteria` object on the vault detail response is empty (`{}`) until then.
For a per-category breakdown of what each category covers and the representative criteria that feed it, see [What each category measures](/api-reference/vault-risk-v3/framework-methodology#what-each-category-measures) on the framework methodology page.
For the full criteria taxonomy — including which criteria are live today and which are planned for a future release — call the [framework endpoint](/api-reference/vault-risk-v3/get-framework). It's the canonical source; this docs site reflects whatever the framework endpoint returns.
***
## Coverage disclosure
Every V3 vault detail response includes a `coverage` block:
```jsonc theme={null}
{
"coverage": {
"framework_version": "v1",
"total_criteria": 42,
"live_criteria": 28,
"per_category": { /* live + total counts per WebacyCategory */ }
}
}
```
This is a deliberate transparency mechanism: clients can show users exactly how much of the framework was evaluated. A score of `10` in a category where 3 of 6 criteria are live is a different statement than a score of `10` in a category where all criteria are live.
***
## Related resources
How the framework is structured, how scores compose, and why the taxonomy is API-driven.
What changed, what stayed, and how to pin your client for stable scoring.
Full request/response reference for `GET /v3/vaults/{address}`.
Public endpoint returning the live framework taxonomy.
## Related Webacy risk coverage
These complementary Webacy products score adjacent risk surfaces. They are scored independently of the vault composite — use them alongside V3 vault risk for fuller coverage.
Real-time smart contract security analysis and vulnerability detection.
Real-time peg-deviation risk for 600+ stablecoins and pegged assets.
Structural risk scoring for stablecoins and real-world asset tokens.