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.
  • 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 live/planned 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-Schemev2Which 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=v2v2400 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 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": "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.

​
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.
KeyNameWeightWhat it measures
smart_contractSmart contract0.20Audit history, contract ownership model, timelock presence, and Webacy’s real-time contract analysis
operational_governanceOperational governance0.20Multisig controls, admin key practices, and operational hygiene
asset_collateralAsset & collateral0.15Collateral quality, asset integrity, reserve transparency, backing type, and share-price (depeg) stability
market_liquidityMarket & liquidity0.20On-chain liquidity depth and exit/redemption accessibility
counterpartyCounterparty0.10Exposure to external protocols, custodians, and other dependencies
hack_exploit_historyHack & exploit history0.15Known exploits or security incidents
chain_infrastructureChain infrastructure0.00Underlying-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 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. 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 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.

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

Contract Risk

Real-time smart contract security analysis and vulnerability detection.

Depeg Monitor

Real-time peg-deviation risk for 600+ stablecoins and pegged assets.

RWA Risk (v3)

Structural risk scoring for stablecoins and real-world asset tokens.