Skip to main content

​
Overview

The V3 vault risk surface (/api/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.
  • Honest 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 (/api/v2/*) is frozen but supported. New integrations should target V3; existing integrations have a migration window — see the v2 → V3 migration guide.

​
Endpoints

Vault Detail (V3)

GET /api/v3/vaults/{address}?chain={chain} — Composite grade, category contributors, criteria taxonomy, coverage disclosure, and the v2 risk envelope.

Framework Taxonomy

GET /api/v3/framework — Public endpoint returning the full criteria taxonomy and roadmap status. No API key required.

​
Versioning contract

V3 responses carry a stable contract on every request. Pin it and you get reproducible scoring across the deprecation window.

​
URL path

/api/v3/... — parallel to /api/v2/.... The major version lives in the path; minor revisions ship under the same path with additive fields.

​
Response body

Every V3 response includes a top-level schema_version field (currently "3.0").

​
Response headers

HeaderValueMeaning
Webacy-Api-Version3.0Major.minor version of the response schema
Webacy-Framework-Versionv1Which criteria taxonomy was used to score this response
Webacy-Grading-Schemev1Which letter-grade mapping was used (echoes the resolved pin)

​
Query parameters for pinning

ParameterDefaultBehavior on unknown value
?framework_version=v1v1400 with { error, supported_versions: ['v1'] }
?grading_scheme=v1v1400 with { error, supported_schemes: ['v1'] }
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 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-: 
{
  "schema_version": "3.0",
  "composite": {
    "grading_scheme": "v1",
    "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.

​
Categories

All V3 responses include scores for seven Webacy risk categories. Phase 1 ships 28 of 42 criteria live; the rest are present in the taxonomy with live: false and a phase marker.
KeyNamePhase 1 weight
smart_contractSmart contract0.20
operational_governanceOperational governance0.20
asset_collateralAsset & collateral0.15
market_liquidityMarket & liquidity0.20
counterpartyCounterparty0.10
hack_exploit_historyHack & exploit history0.15
chain_infrastructureChain infrastructure0.00
chain_infrastructure has zero weight in Phase 1 (the category is present so the schema is stable) and becomes non-zero in Phase 2B. The category’s criteria object on the vault detail response will be empty ({}) until then. For the full criteria taxonomy — including which criteria are live in Phase 1 and which phase each unlive criterion is scheduled for — call the framework endpoint. 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: 
{
  "coverage": {
    "framework_version": "v1",
    "total_criteria": 42,
    "live_criteria": 28,
    "per_category": { /* live + total counts per WebacyCategory */ }
  }
}
This is a deliberate honesty 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.

Framework Methodology

How the framework is structured, how scores compose, and why the taxonomy is API-driven.

v2 → V3 Migration

What changed, what stayed, and how to pin your client for stable scoring.

Vault Detail (V3)

Full request/response reference for GET /api/v3/vaults/{address}.

Framework Taxonomy

Public endpoint returning the live framework taxonomy.