Ctrlk

USDD Public API

USDD exposes a set of public, read-only REST APIs for protocol data — supply, yield, collateral, Vaults and Smart Allocator allocations. All endpoints are free to use, require no API key, and support CORS.

1. Common — Network & Auth

Item
Value

Base URL

https://openapi.usdd.io

Method

GET only

Authentication

None — all endpoints are public, no API key

Content-Type

application/json (except the two bare-number endpoints, §6.1 / §6.2)

CORS

Enabled — callable directly from browsers

Rate limit

No documented per-key limit; treat as best-effort and cache where possible

All request examples below use the absolute Base URL, so they are copy-pasteable without consulting this table.

2. Common — Conventions

2.1 Response envelope

Most endpoints return a standard JSON envelope:

{ "code": 0, "message": "SUCCESS", "data": { ... } }
Field
Type
Existence
Description

code

integer

always

0 = success; non-zero = error (see §3)

message

string

always

SUCCESS, or an error description when code != 0

data

object | array

always

Payload; shape depends on the endpoint

Two endpoints — GET /totalSupply and GET /circulatingSupply — return a bare numeric value with no envelope.

2.2 Data conventions

Topic
Convention

Number types

Numeric fields may be returned as number or string; string-encoded numbers are exact and can be parsed safely as high-precision decimals

Precision

Some APY fields carry up to 29 digits of precision — transport them as strings and truncate (typically to 4 decimal places) for display

*DailyChange fields

Change versus the previous day, based on the 00:00 UTC+8 daily snapshot; the value can be negative

Field stability

Published field names are not renamed within a version; new fields are added in a non-breaking way

2.3 Units

Every response field table includes a Unit column. The possible values:

Unit
Where it appears
How to read it

USDD / sUSDD

totalSupply, mintedUSDD, curMinted, debt, line, usdd[], susdd[], etc.

Token amount, already de-scaled. Use as-is; USDD and sUSDD are each ≈ 1 USD

USD

tvl, totalCollateralValue, earnTvl, earnSa, lockedValue, holdingAmount, *DailyChange, etc.

Already de-scaled US dollars. Use as-is

decimal

tronApy, ethApy, bscApy, currentApy, stabilityFee, psmFee, earnApy, etc.

Annualized rate as a decimal. 0.045 means 4.5% — multiply by 100 for a percentage

percent

apy of smart-allocator/detail-overview only

Already a percentage. 3.4268 means 3.4268% — use as-is

ratio

collateralRatio, minCollateralRatio

A multiple. 2.6 means 260%; 1.2 means 120%

epoch ms

statisticTime

Millisecond Unix timestamp

datetime

time

Human-readable date-time string (UTC+8)

address

contractAddress, operatorAddress

Blockchain address — TRON Base58 or EVM hex depending on chain

enum

chain

One value from a fixed set, e.g. tron / eth / bsc

text

symbol, ilk, vaultType, platform, gemSymbol, strategy, tag

Free-form string identifier

—

items[] and other array containers

The row is a container, not a value — it has no unit

2.4 Existence column

Response field tables include an Existence column so an agent knows whether a missing or null value is normal:

Existence
Meaning

always

The field is always present with a non-null value

nullable

The field is always present, but its value may be null

conditional

The field is present only when a stated condition holds

2.5 Empty result ≠ error

An empty or zero-valued result is a successful response, not an error. Examples: a Vault with no debt returns curMinted: "0" and totalCollateral: "0"; a chain with no Earn deployment returns earnTvl: 0. Do not treat these as failures or retry them.

2.6 Context tips

Several endpoints return long arrays — the APY history (§6.8), supply history (§6.9), collateral history (§6.10) and per-chain history (§6.13). When only the latest point is needed, read the last array element instead of loading the full series, and prefer the snapshot endpoints (§6.1, §6.6, §6.12) over history endpoints.

3. Common — Errors

Error model. Business-level errors are returned as HTTP 200 with a non-zero code in the JSON envelope; the HTTP status is not used to signal business errors. The only exception is an unknown URL path, which returns a real HTTP 404 with a non-JSON nginx page. An agent should therefore branch on the code field, not on the HTTP status (except for routing 404s).

3.1 Code table

code
message
Meaning

0

SUCCESS

Request succeeded

1

FAIL

Request failed

404

NOT_FOUND

URI does not exist

500

INTERNAL_SERVER_ERROR

Internal server error

10001

PARAMETER_MISSING

A required parameter is missing

10002

PARAMETER_ERROR

A parameter value is invalid

3.2 Common error cases

Case
Trigger
Actual response

Missing required parameter

Omit chain on §6.12, or chain/interval on §6.13

HTTP 200, code: 1, message Required request parameter '...' is not present

Invalid parameter value

Unsupported chain (e.g. solana) or interval

HTTP 200, code: 10002, message Invalid chain. / Invalid interval.

Unknown path

Request a path that does not exist

HTTP 404, non-JSON nginx page

Note: code 10001 PARAMETER_MISSING is defined, but a fully absent required query parameter currently returns code: 1 via framework-level validation.

4. Endpoint Index

#
Group
Name
Path

6.1

A

Total Supply

GET /totalSupply

6.2

A

Circulating Supply

GET /circulatingSupply

6.3

A

Earn APY

GET /api/v1/external/earn-apy

6.4

A

USDD Supply by Chain

GET /api/v1/external/total-supply/usdd

6.5

A

sUSDD Supply by Chain

GET /api/v1/external/total-supply/susdd

6.6

B

Protocol Overview

GET /api/v1/market-site/overview

6.7

B

Protocol Overview (with 24h change)

GET /api/v1/data-platform/overview/info

6.8

B

DSR APY (current / average / history)

GET /api/v1/market-site/overview/apy

6.9

B

USDD Total Supply History

GET /api/v1/data-platform/overview/supply-value-history

6.10

B

Total Collateral Value History

GET /api/v1/data-platform/overview/collateral-value-history

6.11

B

Vault Configuration List

GET /api/v1/vault/collaterals

6.12

B

Per-chain Collateral Snapshot

GET /api/v1/data-platform/latest-collateral

6.13

B

Per-chain Historical Series

GET /api/v1/data-platform/collateral-history

6.14

B

Smart Allocator Detail

GET /api/v1/smart-allocator/detail-overview

5. Endpoint Reference

6.1 Total Supply

Overview. True total supply of USDD: USDD in circulation + sUSDD. Typical use: a single headline supply figure. When not to use: for a per-chain breakdown use §6.4 / §6.5; for USD value use §6.6.

Endpoint. GET /totalSupply — Base URL & auth see §1.

Request parameters. None.

Request example.

Response. A bare numeric value (no JSON envelope), unit USDD.

Errors. See §3. This endpoint takes no parameters, so only routing 404 or 5xx apply.

6.2 Circulating Supply

Overview. True circulating supply of USDD: USDD in circulation + sUSDD. Typical use: a single headline circulating-supply figure. When not to use: same as §6.1.

Endpoint. GET /circulatingSupply — Base URL & auth see §1.

Request parameters. None.

Request example.

Response. A bare numeric value (no JSON envelope), unit USDD.

Errors. See §3.

6.3 Earn APY

Overview. Current Earn (DSR) annual yield for each chain. Typical use: show the current savings rate per chain. When not to use: for historical APY use §6.8.

Endpoint. GET /api/v1/external/earn-apy — Base URL & auth see §1.

Request parameters. None.

Request example.

Response fields.

Field
Type
Existence
Unit
Description

tronApy

string

always

decimal

Earn APY on TRON, 4 decimal places (0.0400 = 4.00%)

ethApy

string

always

decimal

Earn APY on Ethereum, 4 decimal places

bscApy

string

always

decimal

Earn APY on BNB Chain, 4 decimal places

Response example.

Errors. See §3.

6.4 USDD Supply by Chain

Overview. USDD circulating supply (excluding sUSDD), broken down by chain. Refreshes every 5 minutes. Typical use: per-chain USDD distribution. When not to use: for the combined supply use §6.1; for sUSDD use §6.5.

Endpoint. GET /api/v1/external/total-supply/usdd — Base URL & auth see §1.

Request parameters. None.

Request example.

Response fields.

Field
Type
Existence
Unit
Description

symbol

string

always

text

Always USDD

totalSupply

number

always

USDD

USDD in circulation across all chains, excluding sUSDD

tron

number

always

USDD

USDD supply on TRON

eth

number

always

USDD

USDD supply on Ethereum

bsc

number

always

USDD

USDD supply on BNB Chain

Response example.

Errors. See §3.

6.5 sUSDD Supply by Chain

Overview. sUSDD supply broken down by chain. Refreshes every 5 minutes. Typical use: per-chain sUSDD distribution. When not to use: for USDD use §6.4.

Endpoint. GET /api/v1/external/total-supply/susdd — Base URL & auth see §1.

Request parameters. None.

Request example.

Response fields.

Field
Type
Existence
Unit
Description

symbol

string

always

text

Always sUSDD

totalSupply

number

always

sUSDD

sUSDD supply across all chains

tron

number

always

sUSDD

sUSDD supply on TRON

eth

number

always

sUSDD

sUSDD supply on Ethereum

bsc

number

always

sUSDD

sUSDD supply on BNB Chain

Response example.

Errors. See §3. A chain with no sUSDD returns 0 — empty ≠ error (§2.5).

6.6 Protocol Overview

Overview. Real-time cross-chain core metrics for the USDD protocol. Typical use: a protocol dashboard snapshot. When not to use: for 24-hour deltas use §6.7; for totalCollateralValue use §6.7 (this endpoint does not return it); for history use §6.8–§6.10.

Endpoint. GET /api/v1/market-site/overview — Base URL & auth see §1.

Request parameters. None.

Request example.

Response fields.

Field
Type
Existence
Unit
Description

totalSupply

number

always

USDD

Total USDD circulating supply across all chains

totalSupplyValue

number

always

USD

Total value of USDD + sUSDD across all chains

tvl

number

always

USD

Protocol total collateral locked value

earnTvl

number

always

USD

Earn (DSR) module locked value

tronApy

number

always

decimal

Current DSR APY on TRON

ethApy

number

always

decimal

Current DSR APY on Ethereum (precision up to 29 digits)

bscApy

number

always

decimal

Current DSR APY on BNB Chain (precision up to 29 digits)

Response example.

Errors. See §3.

6.7 Protocol Overview (with 24h change)

Overview. Aggregated protocol metrics with 24-hour deltas. Authoritative source for totalCollateralValue and earnSa. Typical use: a dashboard that shows day-over-day movement. When not to use: for a plain real-time snapshot use §6.6.

Endpoint. GET /api/v1/data-platform/overview/info — Base URL & auth see §1.

Request parameters. None.

Request example.

Response fields.

Field
Type
Existence
Unit
Description

totalSupplyValue

string

always

USD

Total value of USDD + sUSDD across all chains

totalSupplyValueDailyChange

string

always

USD

Change versus the previous day of totalSupplyValue

totalCollateralValue

string

always

USD

Total collateral value across all chains

totalCollateralValueDailyChange

string

always

USD

Change versus the previous day of totalCollateralValue

earnTvl

string

always

USD

Earn module locked value

earnTvlDailyChange

string

always

USD

Change versus the previous day of earnTvl

earnSa

string

always

USD

Cumulative investment profits generated across all Vaults on every chain

earnSaDailyChange

string

always

USD

Change versus the previous day of earnSa

Response example.

Errors. See §3. *DailyChange values can be negative — that is normal.

6.8 DSR APY (current / average / history)

Overview. Aggregate current and historical-average APY, plus a per-chain daily time series. Typical use: render an APY history chart. When not to use: for just the current APY use §6.3 or §6.6.

Endpoint. GET /api/v1/market-site/overview/apy — Base URL & auth see §1.

Request parameters. None.

Request example.

Response fields.

Field
Type
Existence
Unit
Description

averageApy

string

always

decimal

Cross-chain historical average APY

currentApy

string

always

decimal

Cross-chain current APY

items[]

array

always

—

Per-chain breakdown

items[].chain

string

always

enum

tron / eth / bsc

items[].currentApy

string

always

decimal

Current APY for the chain

items[].averageApy

string

always

decimal

Historical average APY for the chain

items[].items[]

array

always

—

Per-chain APY time series

items[].items[].statisticTime

number

always

epoch ms

Timestamp

items[].items[].apy

string

always

decimal

APY value at that point

Response example (truncated).

Errors. See §3. Context tip (§2.6): the nested items[].items[] series can be long.

6.9 USDD Total Supply History

Overview. Daily history of USDD and sUSDD supply across the three chains. Typical use: render a Total Supply line chart. When not to use: for the current value use §6.4 / §6.5.

Endpoint. GET /api/v1/data-platform/overview/supply-value-history — Base URL & auth see §1.

Request parameters. None.

Request example.

Response fields. data is an array; each element:

Field
Type
Existence
Unit
Description

statisticTime

number

always

epoch ms

Timestamp

usdd

string[3]

always

USDD

USDD amount per chain, order [tron, eth, bsc]

susdd

string[3]

always

sUSDD

sUSDD amount per chain, order [tron, eth, bsc]

Response example (truncated).

Errors. See §3. Context tip (§2.6): the array spans the full protocol history.

6.10 Total Collateral Value History

Overview. Daily history of total collateral value across the three chains. Typical use: render a Collateral Value line chart. When not to use: for the current value use §6.7.

Endpoint. GET /api/v1/data-platform/overview/collateral-value-history — Base URL & auth see §1.

Request parameters. None.

Request example.

Response fields. data is an array; each element:

Field
Type
Existence
Unit
Description

statisticTime

number

always

epoch ms

Timestamp

collateralValue

string[3]

always

USD

Collateral value per chain, order [tron, eth, bsc]

Response example (truncated).

Errors. See §3.

6.11 Vault Configuration List

Overview. Static contract-level configuration of all Vault types. Typical use: list Vault parameters (collateral ratio, stability fee, ceiling). When not to use: for real-time per-Vault state use §6.12.

Endpoint. GET /api/v1/vault/collaterals — Base URL & auth see §1.

Request parameters. None.

Request example.

Response fields.

Field
Type
Existence
Unit
Description

items[]

array

always

—

Vault list

items[].ilk

string

always

text

Vault identifier, e.g. TRX-A, USDT-A

items[].minCollateralRatio

string

always

ratio

Minimum collateral ratio (1.2 = 120%)

items[].stabilityFee

string

always

decimal

Annual stability fee (0.005 = 0.5%)

items[].maxMinted

string

always

USDD

Debt ceiling

items[].dust

string

always

USDD

Dust Limit / Debt Floor — minimum USDD that can be minted per Vault

items[].curMinted

string

always

USDD

Currently minted USDD

items[].totalCollateral

string

always

USD

Total locked collateral value (not native units)

Current Vault types: TRX-A, TRX-B, TRX-C, USDT-A, STRX-A, WBTC-A, WBTC-B.

Response example (truncated).

Errors. See §3. A Vault with no usage returns curMinted: "0" and totalCollateral: "0" — empty ≠ error (§2.5).

6.12 Per-chain Collateral Snapshot

Overview. Real-time collateral and supply state for a specific chain, with a per-Vault breakdown. Items include regular Vaults, PSM Vaults and Smart Allocator Vaults. Typical use: a per-chain Vault dashboard. When not to use: for static config use §6.11; for history use §6.13.

Endpoint. GET /api/v1/data-platform/latest-collateral — Base URL & auth see §1.

Request parameters.

Parameter
In
Type
Required
Default
Description

chain

query

string

yes

—

tron / eth / bsc

Request example.

Response fields — top level.

Field
Type
Existence
Unit
Description

apy

number

always

decimal

Current DSR APY on this chain

usddTotalSupply

number

always

USDD

USDD circulating supply on this chain

totalSupplyValue

number

always

USD

USDD + sUSDD value on this chain

totalSupplyValueDailyChange

number

always

USD

Change versus the previous day of totalSupplyValue

totalCollateralValue

number

always

USD

Total collateral value on this chain

totalCollateralValueDailyChange

number

always

USD

Change versus the previous day of totalCollateralValue

earnTvl

number

always

USD

Earn locked value on this chain

earnTvlDailyChange

number

always

USD

Change versus the previous day of earnTvl

items[]

array

always

—

Per-Vault breakdown

Response fields — items[].

Field
Type
Existence
Unit
Description

vaultType

string

always

text

Vault identifier, e.g. TRX-A, PSM-USDT-A, SA001-A

chain

string

always

enum

Chain identifier

collateralType

number

always

1 / 2 / 3

1 = regular Vault, 2 = PSM, 3 = Smart Allocator

contractAddress

string

always

address

Vault contract address

mintedUSDD

number

always

USDD

Minted USDD

debt

number

always

USDD

Current debt including accumulated stability fees

lockedValue

number

always

USD

Locked collateral value

collateralRatio

number

always

ratio

Current collateral ratio

minCollateralRatio

string

always

ratio

Minimum collateral ratio

stabilityFee

string

always

decimal

Annual stability fee

line

string

always

USDD

Debt ceiling

apy

number | null

nullable

decimal

Vault APY; null for regular Vaults

estimatedAnnualEarnings

number | null

nullable

USD

Estimated annual earnings; null when not applicable

psmFee

string | null

nullable

decimal

PSM swap fee; null for non-PSM Vaults

Response example (truncated).

Errors. See §3. Missing chain → code: 1; invalid chain → code: 10002.

6.13 Per-chain Historical Series

Overview. Time-series data for a specific chain — used to render 7D / 1M / 6M / 1Y charts. Typical use: a per-chain history chart. When not to use: for the current snapshot use §6.12.

Endpoint. GET /api/v1/data-platform/collateral-history — Base URL & auth see §1.

Request parameters.

Parameter
In
Type
Required
Default
Description

chain

query

string

yes

—

tron / eth / bsc

interval

query

string

yes

—

WEEKLY (7 days) / MONTHLY (1 month) / BIANNUAL (6 months) / ANNUAL (1 year)

Request example.

Response fields. data.items is an array; each element:

Field
Type
Existence
Unit
Description

statisticTime

number

always

epoch ms

Timestamp

time

string | null

nullable

datetime

Human-readable time (UTC+8); the latest entry may be null

collateralValue

number

always

USD

Collateral value at this point

debt

number

always

USDD

Debt amount

mintedUSDD

number

always

USDD

Minted USDD

usddTotalSupply

number

always

USDD

USDD circulating supply

totalSupplyValue

number

always

USD

USDD + sUSDD value

earnTvl

number

always

USD

Earn locked value

earnApy

number

always

decimal

APY at this point

Response example (truncated).

Errors. See §3. Missing chain/interval → code: 1; invalid value → code: 10002. The latest time may be null — that is normal, not an error.

6.14 Smart Allocator Detail

Overview. Allocation and earnings detail of USDD protocol reserves across DeFi platforms. Typical use: show where reserve funds are deployed and what they earn. When not to use: for cumulative profit (earnSa) use §6.7 — it is not here.

Endpoint. GET /api/v1/smart-allocator/detail-overview — Base URL & auth see §1.

Request parameters. None.

Request example.

Response fields — top level.

Field
Type
Existence
Unit
Description

apy

number

always

percent

Smart Allocator blended APY — a percentage (3.4268 = 3.4268%)

debt

number

always

USDD

Total debt managed by Smart Allocator

platformSummaryInfos[]

array

always

—

Positions per (platform × chain × asset)

vaultInfos[]

array

always

—

Smart Allocator Vaults per chain

Response fields — platformSummaryInfos[].

Field
Type
Existence
Unit
Description

platform

string

always

text

DeFi platform, e.g. Aave, Morpho, JustLend, Spark, Venus, ListaDAO

chain

string

always

enum

Chain, e.g. eth, tron, bsc, plasma

gemSymbol

string

always

text

Asset symbol, e.g. USDT, USDC, USDS, USDT0

holdingAmount

number

always

USD

Current holding

apyHoldingAmount

number

always

USD

APY-weighted holding amount used in the blended APY calculation

apy

number

always

decimal

Position APY

actualEarnings

number

always

USD

Cumulative actual earnings

operatorAddress

string

always

address

Operator address

strategy

string

always

text

Strategy type, e.g. Investment

tag

string | null

nullable

text

Risk-curator tag, e.g. Gauntlet, Steakhouse; may be empty or null

Response fields — vaultInfos[].

Field
Type
Existence
Unit
Description

chain

string

always

enum

Chain

vaultType

string

always

text

SA Vault identifier, e.g. SA001-A

contractAddress

string

always

address

Vault contract address

debt

number

always

USDD

Current Vault debt

Response example (truncated).

Errors. See §3. Note apy here is a percentage, unlike every other APY field in this document.

7. Quick Reference for AI Agents

To query
Call
Key fields

Total / circulating supply (single number)

§6.1 / §6.2

bare numeric value

Earn APY per chain

§6.3

tronApy / ethApy / bscApy

USDD or sUSDD supply by chain

§6.4 / §6.5

totalSupply, tron, eth, bsc

Protocol size, real-time

§6.6

totalSupply, tvl

Protocol size with 24h change

§6.7

*DailyChange

Cumulative Vault investment profits

§6.7

earnSa

APY history curve

§6.8

items[].items[]

USDD supply history

§6.9

usdd[3], susdd[3]

Collateral value history

§6.10

collateralValue[3]

Vault list and configuration

§6.11

items[]

Vault real-time state per chain

§6.12

items[].collateralRatio, mintedUSDD

Single-chain history (debt / supply / apy)

§6.13

items[]

Smart Allocator allocations and earnings

§6.14

platformSummaryInfos[]

Rules for automated consumption:

  • Branch on the code field, not the HTTP status — business errors return HTTP 200 (§3).

  • Always check code == 0 before reading data (except §6.1 / §6.2, bare numbers).

  • Treat APY as a decimal, except smart-allocator/detail-overview.apy, which is a percentage.

  • Null-check nullable fields: apy, estimatedAnnualEarnings, psmFee, tag, time.

  • An empty or zero result is success, not an error (§2.5).

  • In history arrays of length 3, element order is fixed: [tron, eth, bsc].

  • Use a high-precision decimal type for APY fields, which may carry 29 digits.

PreviousOracleNextMCP Server

Last updated