> ## 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.
# Get risk data for a single vault
> Returns the v3 Webacy-native vault decomposition: `composite` grade + per-category `contributors`, the dense `categories` criteria map, `coverage` disclosure, plus pass-through v2 `metadata` and `risk`. POLARITY: scores are 0–100, higher = worse (A+ = 0, F = 100). `composite.score` is floored from below by `upstream_risk`.
Returns the full V3 risk decomposition for one vault — composite grade, per-category contributors, the dense criteria taxonomy, coverage disclosure, and the pass-through v2 `risk` envelope.
**Understanding the version numbers.** Three independent version axes show up on the V3 surface — they are not the same number:
* **API version `v3`** — the URL path (`/v3/...`) and the response `schema_version` (`3.0`).
* **`framework_version`** — which criteria taxonomy was used. `v1` today (the only supported value).
* **`grading_scheme`** — which letter-grade band table is applied. **`v2` is the default** (the standard 11-band scale); `v1` is frozen and deprecated.
So the V3 API uses `framework_version=v1` and `grading_scheme=v2` by default. Seeing `v1` on `framework_version` does **not** mean you're on an older API.
## Supported chains
The `chain` query parameter is required. 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.
## Assessing freshness
This endpoint does **not** return a `stale` flag or `generated_at`. To assess freshness, use `metadata.last_scored_at` on the response, or read the v2 list / grades endpoints, which carry `stale`.
Treat missing, stale, or errored data as **unknown — never as safe**. See [Hard-gating and fail behavior](/api-reference/introduction#hard-gating-and-fail-behavior).
## OpenAPI
````yaml GET /v3/vaults/{address}
openapi: 3.0.1
info:
title: Risk Score API
description: API definition for Webacy Risk Scores
version: 1.9.1
servers:
- url: https://api.webacy.com
description: Webacy Risk Score API (Production)
- url: https://api-development.webacy.com
description: Webacy Risk Score API (Development)
- url: http://0.0.0.0:3030/api/v1/risk-score
description: Webacy Risk Score API - Local
security:
- api_key: []
tags:
- name: Webhooks
description: >-
Subscribe to and manage real-time event notifications (currently
DEPEG_TIER_CHANGE)
- name: Threat Risks
description: Analyze addresses for security threats and malicious activity
- name: Sanction Checks
description: Check addresses against OFAC and other sanction lists
- name: Approval Risks
description: Analyze token approvals and associated risks
- name: Transaction Risks
description: Assess risk details for blockchain transactions
- name: Exposure Risk
description: Understand risk profile and exposure of addresses
- name: Contract Risk
description: Real-time smart contract security analysis
- name: URL Risks
description: Analyze URLs for phishing and security threats
- name: API Usage
description: Monitor and manage API consumption
- name: Holder Analysis
description: Token holder distribution and sniper detection
- name: Address Poisoning
description: Detect address poisoning attack patterns
- name: Token Analysis
description: Comprehensive token security and market analysis
- name: Pool Analysis
description: Liquidity pool data and analysis
- name: Transaction Scanning
description: Scan and simulate transactions for risks
- name: trading-lite
description: Lightweight trading risk assessment
- name: RWA & Pegged Tokens
description: >-
Real-world asset and pegged-token analytics (supply flows, mint/burn
velocity)
- name: Vault Risk v3
description: >-
Webacy-native v3 vault risk surface — composite grade, categories,
coverage, and the framework taxonomy.
- name: RWA Risk v3
description: >-
Webacy-native v3 RWA / stablecoin risk surface — composite grade,
structural-health criteria, and batch scoring.
- name: Stablecoins v3
description: >-
Stablecoin-only aliases of the v3 RWA routes: same grades, same shapes,
`segment` fixed to `stablecoin`.
paths:
/v3/vaults/{address}:
get:
tags:
- Vault Risk v3
summary: Get v3 vault risk detail (Webacy-native)
description: >-
Returns the v3 Webacy-native vault decomposition: `composite` grade +
per-category `contributors`, the dense `categories` criteria map,
`coverage` disclosure, plus pass-through v2 `metadata` and `risk`.
POLARITY: scores are 0–100, higher = worse (A+ = 0, F = 100).
`composite.score` is floored from below by `upstream_risk`.
operationId: getVaultRiskDetailV3
parameters:
- name: address
in: path
required: true
schema:
type: string
description: Vault contract address.
- name: chain
in: query
required: true
schema:
type: string
enum:
- eth
- base
- bsc
- pol
- opt
- arb
- avax
- sol
- stellar
- hedera
- tron
- sui
- ton
- sei
- btc
- gnosis
description: Chain identifier (e.g. eth, base, pol). Required.
- name: grading_scheme
in: query
required: false
schema:
type: string
enum:
- v1
default: v1
description: >-
Grading scheme to pin (default v1). Unknown values return 400 with
the supported list.
responses:
'200':
headers:
x-credit-token:
$ref: '#/components/headers/XCreditToken'
x-credit-balance-cu:
$ref: '#/components/headers/XCreditBalanceCu'
description: Webacy-native v3 vault detail.
content:
application/json:
schema:
$ref: '#/components/schemas/VaultV3Response'
example:
schema_version: '3.0'
metadata:
address: '0xD50DA5F859811A91fD1876C9461fD39c23C747Ad'
chain: eth
name: MEV Capital Resolv USR
symbol: MC-USR
lender_concentration:
hhi: 0.18
risk_band: low
participant_count: 42
top10_share_pct: 55.2
top30_share_pct: 78.1
top_participants:
- address: '0x1111111111111111111111111111111111111111'
share_pct: 12.3
borrower_concentration:
hhi: 0.31
risk_band: medium
participant_count: 17
top10_share_pct: 71.4
top30_share_pct: 92
top_participants:
- address: '0x2222222222222222222222222222222222222222'
share_pct: 22.6
curator_concentration:
hhi: 0.29
risk_band: medium
market_count: 12
top10_share_pct: 61
top30_share_pct: 88.4
top_markets:
- market_key: 8453-0x9103da5da5c9f9b6e4bda4b2f8f3f0e1d2c3b4a5
label: cbBTC/USDC
share_pct: 20.1
total_supply_usd: 1234567890
vault_count: 8
curator: '0x3333333333333333333333333333333333333333'
composite:
grading_scheme: v1
grade: F
stars: 1
score: 98.5
contributors:
smart_contract:
score: 0
weight: 0.2
weighted_contribution: 0
operational_governance:
score: 0
weight: 0.2
weighted_contribution: 0
asset_collateral:
score: 10
weight: 0.15
weighted_contribution: 1.5
market_liquidity:
score: 35
weight: 0.2
weighted_contribution: 7
counterparty:
score: 0
weight: 0.1
weighted_contribution: 0
hack_exploit_history:
score: 0
weight: 0.15
weighted_contribution: 0
chain_infrastructure:
score: 0
weight: 0
weighted_contribution: 0
upstream_risk: 98.5
clamped_by_upstream: true
score_source: upstream
drivers_complete: false
drivers:
- category: market_liquidity
category_name: Market & liquidity
score: 35
weight: 0.2
weighted_contribution: 7
criteria:
- key: large_holder_concentration
name: Large-holder concentration bounded
status: warn
evidence:
hci_10: 0.34
categories:
smart_contract:
score: 0
criteria:
contract_verified:
name: Contract verified on explorer
status: pass
data_quality:
confidence: 0.95
last_observed_at: '2026-06-02T09:49:36Z'
source: rwa-grade-pipeline
market_liquidity:
score: 35
criteria:
large_holder_concentration:
name: Large-holder concentration bounded
status: warn
data_quality:
confidence: 0.95
last_observed_at: '2026-06-02T09:49:36Z'
source: rwa-grade-pipeline
evidence:
hci_10: 0.34
coverage:
framework_version: v1
total_criteria: 42
live_criteria: 28
per_category:
smart_contract:
live: 6
total: 8
risk:
overallRisk: 98.5
'400':
description: Invalid address, chain, or grading_scheme.
'402':
$ref: '#/components/responses/X402PaymentRequired'
'403':
description: Missing or invalid x-api-key.
'404':
description: Vault not found.
'503':
$ref: '#/components/responses/X402ServiceUnavailable'
security:
- api_key: []
components:
headers:
XCreditToken:
description: >-
Opaque bearer token for a prepaid x402 CU balance. Send it as
`x-credit-token` to spend that balance. If the balance is insufficient
and a payment for its verified payer settles, the same token is topped
up and returned; otherwise the paid call returns a new independent
token.
schema:
type: string
XCreditBalanceCu:
description: CU remaining for the returned or presented credit token after this call.
schema:
type: integer
minimum: 0
example: 480
schemas:
VaultV3Response:
type: object
description: >-
Webacy-native v3 vault detail. `metadata` and `risk` are pass-through
from the v2 vault response; `composite`/`categories`/`coverage` are the
v3 additions. The three category-keyed maps are dense across all 7
WebacyCategory keys.
properties:
schema_version:
type: string
example: '3.0'
metadata:
type: object
description: Pass-through v2 vault identity/market metadata.
additionalProperties: true
composite:
$ref: '#/components/schemas/V3Composite'
categories:
type: object
additionalProperties:
$ref: '#/components/schemas/V3Category'
coverage:
$ref: '#/components/schemas/V3Coverage'
risk:
type: object
description: Pass-through v2 risk envelope (overallRisk etc.).
additionalProperties: true
required:
- schema_version
- metadata
- composite
- categories
- coverage
- risk
V3Composite:
type: object
description: >-
Headline grade block. POLARITY (load-bearing): `score` is 0–100, HIGHER
= WORSE (A+ = 0, F = 100) — same direction as the v2 `risk.score` on the
same response. `score = max(Σ contributors·weight, upstream_risk)`:
floored from below by the upstream pipeline risk.
properties:
grading_scheme:
type: string
example: v1
grade:
type: string
enum:
- A+
- A
- A-
- B+
- B
- B-
- C
- C-
- D
- E
- F
stars:
type: integer
minimum: 1
maximum: 5
score:
type: number
description: 0–100, higher = worse; rounded to one decimal.
contributors:
type: object
description: 'Dense map: every WebacyCategory key is present.'
additionalProperties:
$ref: '#/components/schemas/V3Contributor'
upstream_risk:
type: number
nullable: true
description: >-
Verbatim upstream pipeline risk (0–100, higher = worse). Acts as a
lower bound on `score`. `null` when there is no upstream score
(data-only vaults, e.g. Kamino on Solana awaiting native scoring) —
in that case no upstream floor is applied. Guard against null before
formatting.
clamped_by_upstream:
type: boolean
description: >-
true iff upstream_risk exceeded the framework composite and pulled
`score` up.
score_source:
type: string
enum:
- framework
- upstream
description: >-
What set the emitted `score`: `framework` when the v3 weighted
composite won, `upstream` when the pipeline floor did (equivalent to
`clamped_by_upstream`).
drivers:
type: array
description: >-
Ranked subcategory drivers of the grade (descending by
`weighted_contribution`), each with the warn/fail criteria and
evidence that drove it. Detail endpoints only (`GET
/v3/vaults/{address}`, `GET /v3/rwa/{address}`); batch/list omit it.
Read with `drivers_complete`: an empty `[]` is only a clean grade
when `drivers_complete` is true.
items:
$ref: '#/components/schemas/V3CompositeDriver'
drivers_complete:
type: boolean
description: >-
Whether `drivers` is the complete explanation of the grade. `true`
(framework-sourced) ⇒ `drivers` fully attribute it and `[]` means a
genuinely clean grade. `false` (upstream-clamped) ⇒ `drivers`
reflect only the framework sub-signal and can be empty even on a bad
grade — render `upstream_risk`, not "no risk". Detail endpoints
only, alongside `drivers`.
required:
- grading_scheme
- grade
- stars
- score
- contributors
- upstream_risk
- clamped_by_upstream
V3Category:
type: object
description: >-
A Webacy-native category. `score` is 0–100, HIGHER = WORSE
(risk-magnitude; A+ = 0, F = 100). Categories with no live criteria emit
`{ score: 0, criteria: {} }`.
properties:
score:
type: number
description: 0–100, higher = worse. Integer in practice.
criteria:
type: object
additionalProperties:
$ref: '#/components/schemas/V3Criterion'
required:
- score
- criteria
V3Coverage:
type: object
description: >-
How many criteria are live today vs defined by the framework — so what
the grade reflects is on the wire, not just in docs.
properties:
framework_version:
type: string
example: v1
total_criteria:
type: integer
live_criteria:
type: integer
per_category:
type: object
additionalProperties:
$ref: '#/components/schemas/V3CategoryCoverage'
required:
- framework_version
- total_criteria
- live_criteria
- per_category
V3Contributor:
type: object
description: >-
One row of `composite.contributors`: a category's resolved score and its
weight under the current grading scheme.
properties:
score:
type: number
description: 0–100, higher = worse. Integer.
weight:
type: number
description: >-
Category weight under the grading scheme (sums to 1 across
categories).
weighted_contribution:
type: number
description: >-
Points this category adds to the framework composite — `score ×
weight`, rounded to one decimal. The rounded sum across contributors
approximates the framework composite (each contribution is rounded
independently).
required:
- score
- weight
V3CompositeDriver:
type: object
description: >-
One ranked subcategory driver of the grade (descending by
`weighted_contribution`), with the warn/fail criteria that drove it.
NOTE: for RWA, `criteria` are descriptive context, not a numeric
decomposition of `score` (RWA category scores come from inverted v2
pillars, not criterion penalties).
properties:
category:
type: string
example: market_liquidity
category_name:
type: string
example: Market & liquidity
score:
type: number
weight:
type: number
weighted_contribution:
type: number
criteria:
type: array
items:
$ref: '#/components/schemas/V3DriverCriterion'
required:
- category
- category_name
- score
- weight
- weighted_contribution
- criteria
V3Criterion:
type: object
description: >-
One graded criterion: pass/warn/fail verdict, human-readable label,
provenance, and the underlying values behind the verdict.
properties:
name:
type: string
description: >-
Human-readable criterion label, mirrored from the framework
taxonomy.
example: Large-holder concentration bounded
status:
type: string
enum:
- pass
- warn
- fail
data_quality:
$ref: '#/components/schemas/V3DataQuality'
evidence:
type: object
description: >-
Underlying values behind the verdict — the actual risk numbers (e.g.
`{ hci_10: 0.34 }`, `{ looping_rate: 0.82 }`, `{ audit_count: 1,
auditor_tier: "mid" }`). For tag-driven vault criteria with no
numeric field, a non-pass verdict carries `{ triggered_by_tag:
}`. Omitted when no value is available.
additionalProperties: true
example:
hci_10: 0.34
required:
- status
- data_quality
V3CategoryCoverage:
type: object
properties:
live:
type: integer
total:
type: integer
required:
- live
- total
V3DriverCriterion:
type: object
description: >-
One non-pass criterion inside a composite driver — the specific
warn/fail check that pulled a subcategory's score up, with the evidence
behind it.
properties:
key:
type: string
example: large_holder_concentration
name:
type: string
example: Large-holder concentration bounded
status:
type: string
enum:
- warn
- fail
evidence:
type: object
description: Underlying values behind the verdict, when available.
additionalProperties: true
example:
hci_10: 0.34
required:
- key
- name
- status
V3DataQuality:
type: object
description: >-
Provenance envelope on every emitted v3 criterion. Vault criteria
currently report vault-level freshness uniformly; RWA / stablecoin
criteria report true per-source values.
properties:
confidence:
type: number
description: 0–1 confidence in the underlying data point.
example: 0.95
last_observed_at:
type: string
format: date-time
description: Upstream observation timestamp.
source:
type: string
example: rwa-grade-pipeline
required:
- confidence
- last_observed_at
- source
responses:
X402PaymentRequired:
description: >-
Keyless x402 payment required. Returned for a keyless caller (gateway
entry `x-webacy-entry: x402`) with no prepaid CU balance or insufficient
CU on the presented credit token. Identified by the base64
`PAYMENT-REQUIRED` response header; the body carries the x402 challenge
(a USDC price on Base and a Stripe-minted deposit address). Pay it, then
retry with the `PAYMENT-SIGNATURE` header to unlock the resource and
receive a credit token. An authenticated api-key caller with a
past_due/unpaid subscription may instead receive a different 402
(`Subscription payment required`, plain JSON, no `PAYMENT-REQUIRED`
header).
headers:
PAYMENT-REQUIRED:
description: >-
Base64-encoded x402 challenge (network, asset, amount, payTo,
resource.url). The edge rollout supplies the canonical public
request path through a valid gateway claim; missing or invalid
claims safely fall back to the public origin plus an internal path
identifier. resource.url is not yet suitable for publishing to a
public x402 discovery catalog (Coinbase's Bazaar): route-specific
declarations and live paid validation are still pending.
schema:
type: string
content:
application/json:
example:
x402Version: 1
error: payment required
X402ServiceUnavailable:
description: >-
x402 paywall fails CLOSED: if payment configuration is incomplete or
invalid, the x402 route unexpectedly has no payment requirement, or the
facilitator, credit store, or settlement is unavailable, a gated keyless
request returns 503 (`Payment service temporarily unavailable`) rather
than serving the resource unpaid.
content:
application/json:
example:
message: Payment service temporarily unavailable
securitySchemes:
api_key:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.