Skip to main content

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

​
Endpoints

Vault Detail (V3)

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

Framework Taxonomy

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

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.

​
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: 
{
  "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": "<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.

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