> ## 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.
# List Stablecoin Grades
> Stablecoin-only twin of `GET /v3/rwa/grades`: identical response, with `segment` fixed to `stablecoin` — `asset_class` fiat plus graded tokens that have not been classified yet, i.e. everything the `segment` rule does not resolve to `rwa`. `grade_counts` still covers the full graded set. A caller-supplied `segment` is ignored.
Stablecoin-only twin of [`GET /v3/rwa/grades`](/api-reference/rwa-v3/get-rwa-grades). Identical response, with `segment` pinned to `stablecoin`; a caller-supplied `segment` is ignored.
**Higher score = more risk.** `composite.score` runs **0–100**, where **0 = no structural risk** and **100 = maximum risk** (`A+` ≈ 0, `F` ≈ 100). See [Score Polarity](/api-reference/rwa-v3#score-polarity).
## The segment rule on this list
The grades universe is our grading snapshot rather than the set of classified tokens, and many tokens in it are not classified yet. Those fall to the `stablecoin` arm, so here `stablecoin` means **"pegged and not a classified RWA, including not-yet-classified"** — it is not the same as `asset_class = fiat`.
Read each row's `asset_class` to tell a confirmed fiat token (`"fiat"`) from one carrying none (`null`). A `null` has two causes: the token has not been classified yet, or it is confirmed stable without a confirmed backing type. The two segments are exclusive and total, so the `stablecoin` and `rwa` counts add up to the unfiltered total.
`grade_counts` describes the **full graded universe** — before every filter and before pagination, so pinning the segment does not narrow it. That is deliberate, for parity with `GET /v3/rwa/grades`.
## When the classification is unavailable
The classification is resolved on every request. If it cannot be resolved, this route **fails closed with `503`** rather than returning every graded token as though it were a stablecoin.
`pegType` is not accepted on either grades route — grade rows carry no denomination. Use [`GET /rwa`](/api-reference/depeg-monitor/list-pegged-tokens-with-depeg-risk) for that filter.
The unfiltered [`GET /v3/rwa/grades`](/api-reference/rwa-v3/get-rwa-grades) degrades differently: it still answers `200`, omits the classification fields on each row, and sets `classification_available: false`. Treat that flag as "unknown", never as "not a stablecoin".
## OpenAPI
````yaml GET /v3/stablecoins/grades
openapi: 3.0.1
info:
title: Risk Score API
description: API definition for Webacy Risk Scores
version: 1.9.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: 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/stablecoins/grades:
get:
tags:
- Stablecoins v3
summary: List v3 stablecoin grades
description: >-
Stablecoin-only twin of `GET /v3/rwa/grades`: identical response, with
`segment` fixed to `stablecoin` — `asset_class` fiat plus graded tokens
that have not been classified yet, i.e. everything the `segment` rule
does not resolve to `rwa`. `grade_counts` still covers the full graded
set. A caller-supplied `segment` is ignored.
operationId: getStablecoinGradesV3
parameters:
- name: chain
in: query
required: false
schema:
type: string
description: Filter by chain slug (e.g. eth, base, pol).
- name: grade
in: query
required: false
schema:
type: string
enum:
- A+
- A
- A-
- B+
- B
- B-
- C+
- C
- C-
- D
- E
- F
description: >-
Filter to a single grade letter. Accepts any letter from either
scheme (the enum is the union); a letter the resolved
`grading_scheme` never emits — e.g. `E` under `v2` or `C+` under
`v1` — simply matches no tokens.
- name: minScore
in: query
required: false
schema:
type: number
minimum: 0
maximum: 100
description: Minimum composite (risk) score, 0–100.
- name: sort
in: query
required: false
schema:
type: string
enum:
- score
- symbol
- chain
- grade
- market_cap_usd
description: Sort field.
- name: order
in: query
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: Sort order. Default asc (best grade first).
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
description: 1-based page number.
- name: pageSize
in: query
required: false
schema:
type: integer
default: 50
description: Items per page (default 50).
- name: grading_scheme
in: query
required: false
schema:
type: string
enum:
- v1
- v2
- peg
default: v2
description: >-
Grading scheme to pin — selects the per-category weights and
letter-grade band table. Default `v2` (alias of `v1`'s weights,
standard 11-band grade scale). `peg` is the peg-loss-focused
weighting. `v3`/`v4`/`peg-liquidity` are registered but withheld
behind the `v3-grading-scheme` feature flag. 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: >-
Paginated list of graded tokens. `grade_counts` covers the full
graded universe (pre-filter), not the filtered result or the
returned page.
content:
application/json:
schema:
type: object
required:
- schema_version
- items
- pagination
- grade_counts
- generated_at
- stale
properties:
schema_version:
type: string
example: '3.0'
items:
type: array
items:
type: object
required:
- symbol
- name
- chain
- address
- market_cap_usd
- tier
- composite
properties:
symbol:
type: string
name:
type: string
nullable: true
chain:
type: string
address:
type: string
market_cap_usd:
type: number
nullable: true
tier:
type: string
nullable: true
enum:
- critical
- warning
- watch
- ok
description: Risk tier from the depeg pipeline.
composite:
$ref: '#/components/schemas/V3Composite'
asset_class:
type: string
nullable: true
example: fiat
description: >-
Asset class; null when the graded token has not been
classified yet.
is_rwa:
type: boolean
nullable: true
subclass:
type: string
nullable: true
example: tbill
pagination:
type: object
required:
- total
- page
- pageSize
- totalPages
properties:
total:
type: integer
page:
type: integer
pageSize:
type: integer
totalPages:
type: integer
grade_counts:
type: object
additionalProperties:
type: integer
description: >-
Grade-letter histogram over the FULL graded universe,
computed before every filter (`segment`, `chain`, `grade`,
`minScore`) — not the filtered or paged subset. In the
resolved scheme's letters.
generated_at:
type: string
stale:
type: boolean
classification_available:
type: boolean
description: >-
false when the asset classification could not be loaded —
rows are unstamped and any segment filter was not applied.
example:
schema_version: '3.0'
items:
- symbol: usdb
name: USDBridge
chain: base
address: '0x100faa513ac917181eb29f73b64bf7a434a206fe'
market_cap_usd: null
tier: ok
composite:
grading_scheme: v2
grade: A-
stars: 5
score: 14.5
contributors:
smart_contract:
score: 41.5
weight: 0.2
operational_governance:
score: 41.5
weight: 0.15
asset_collateral:
score: 0
weight: 0.3
market_liquidity:
score: 0
weight: 0.2
counterparty:
score: 0
weight: 0
hack_exploit_history:
score: 0
weight: 0.15
chain_infrastructure:
score: 0
weight: 0
upstream_risk: 12
clamped_by_upstream: false
pagination:
total: 1
page: 1
pageSize: 50
totalPages: 1
grade_counts:
A-: 1
generated_at: '2026-06-02T09:49:36Z'
stale: false
'400':
description: Invalid chain or grading_scheme.
'402':
$ref: '#/components/responses/X402PaymentRequired'
'403':
description: Missing or invalid x-api-key.
'503':
$ref: '#/components/responses/ClassificationOrPaymentUnavailable'
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:
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
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
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
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
ClassificationOrPaymentUnavailable:
description: >-
Fails CLOSED for one of two causes.
**Asset classification unavailable** — the asset classification could
not be loaded while an asset-class filter was in force (an explicit
`segment`, or `/v3/stablecoins/grades` and `/v3/stablecoins/{address}`,
which pin one). NOTE: the `/v3/stablecoins` LIST route is NOT in this
set — it is served from a cached token set, so a classification outage
yields a stale or empty list with 200, never a 503. The request fails
rather than return an unfiltered superset presented as the filtered
answer. Retry, or call the `/v3/rwa` equivalent without `segment` to get
unstamped rows with `classification_available: false`.
**x402 payment service unavailable** — 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 rather than serving the
resource unpaid.
The `message` field distinguishes them.
content:
application/json:
examples:
assetClassificationUnavailable:
summary: Asset classification unavailable
value:
message: >-
segment=rwa cannot be applied: the asset classification is
temporarily unavailable
paymentServiceUnavailable:
summary: x402 payment service unavailable
value:
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.