> ## 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 Vault Risk Detail (V3)
> 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`.
**CU cost:** 1 CU per request (`v3-vault-detail`).
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.2.0
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: 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 (RFC-019).
- name: RWA Risk v3
description: >-
Webacy-native v3 RWA / stablecoin risk surface — composite grade,
structural-health criteria, and batch (RFC-019).
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`.
**CU cost:** 1 CU per request (`v3-vault-detail`).
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
- arb
- base
- opt
- pol
- bsc
- avax
- gnosis
- sol
description: >-
Chain identifier. Vault v3 covers 9 chains: eth, arb, base, opt,
pol, bsc, avax, gnosis, sol. Any other value returns 400 "Invalid
chain". Required.
- name: grading_scheme
in: query
required: false
schema:
type: string
enum:
- v1
- v2
default: v2
description: >-
Grading scheme to pin (default v2, the standard 11-band risk scale —
lower risk = better grade). Pin v1 for the frozen legacy scale (it
uses an E band and has no C+). Unknown values return 400 with the
supported list.
responses:
'200':
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
last_scored_at: '2026-07-07T16:50:38Z'
composite:
grading_scheme: v2
grade: F
stars: 1
score: 98.5
contributors:
smart_contract:
score: 0
weight: 0.2
operational_governance:
score: 0
weight: 0.2
asset_collateral:
score: 10
weight: 0.15
market_liquidity:
score: 35
weight: 0.2
counterparty:
score: 0
weight: 0.1
hack_exploit_history:
score: 0
weight: 0.15
chain_infrastructure:
score: 0
weight: 0
upstream_risk: 98.5
clamped_by_upstream: true
categories:
smart_contract:
score: 0
criteria:
contract_verified:
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:
status: warn
data_quality:
confidence: 0.95
last_observed_at: '2026-06-02T09:49:36Z'
source: rwa-grade-pipeline
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.
'403':
description: Missing or invalid x-api-key.
'404':
description: Vault not found.
security:
- api_key: []
components:
schemas:
VaultV3Response:
type: object
description: >-
Webacy-native v3 vault detail (RFC-019). `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.
The letter set in `grade` depends on `grading_scheme`: `v2` (default,
standard 11-band scale) emits `C+` and never `E`; `v1` (frozen legacy
scale) emits `E` and never `C+`.
allOf:
- oneOf:
- title: grading_scheme v2 (standard)
properties:
grading_scheme:
type: string
enum:
- v2
grade:
type: string
enum:
- A+
- A
- A-
- B+
- B
- B-
- C+
- C
- C-
- D
- F
- title: grading_scheme v1 (legacy)
properties:
grading_scheme:
type: string
enum:
- v1
grade:
type: string
enum:
- A+
- A
- A-
- B+
- B
- B-
- C
- C-
- D
- E
- F
properties:
grading_scheme:
type: string
enum:
- v1
- v2
example: v2
grade:
type: string
description: >-
Letter grade. Valid set depends on `grading_scheme` (see the `oneOf`
above): v2 → no `E`, has `C+`; v1 → has `E`, no `C+`. The enum here
is the union across both schemes.
enum:
- A+
- A
- A-
- B+
- B
- B-
- C+
- 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
description: >-
Verbatim upstream pipeline risk (0–100, higher = worse). Acts as a
lower bound on `score`.
clamped_by_upstream:
type: boolean
description: >-
true iff upstream_risk exceeded the framework composite and pulled
`score` up.
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).
required:
- score
- weight
V3Criterion:
type: object
description: 'One graded criterion: pass/warn/fail verdict plus provenance.'
properties:
status:
type: string
enum:
- pass
- warn
- fail
data_quality:
$ref: '#/components/schemas/V3DataQuality'
evidence:
type: object
description: >-
Optional free-form provenance bag. Reserved for a future release —
not emitted today.
additionalProperties: true
required:
- status
- data_quality
V3CategoryCoverage:
type: object
properties:
live:
type: integer
total:
type: integer
required:
- live
- total
V3DataQuality:
type: object
description: >-
Provenance envelope on every emitted v3 criterion. Vault-level freshness
is painted uniformly today; true per-source values populate in a future
release.
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
securitySchemes:
api_key:
type: apiKey
in: header
name: x-api-key
````