Token supply

Query token supply data.

GET/api/v1/fundamentals/supply

Domain

Fundamentals

Level

Crypto asset

MCP tool

fundamentals_query (task=tokenomics)

Available data

Returns: Token supply data
Market coverage: Crypto
Query granularity: One token per query; supply only, without allocation or unlock detail

Authentication

Send Authorization: Bearer YOUR_API_KEY or X-API-KEY on every request.

Query Parameters

Asset positioning

Provide query, asset_id, or symbol when possible; an empty request may return no_data.

querystringqueryExampleBTCoptional

Ticker, name, or free text.

asset_idstringqueryExampleasset_btcoptional

Canonical asset_id (preferred; 400 param_conflict when it disagrees with query/symbol)

symbolstringqueryExampleBTCoptional

Compatibility alias of query.

Resolution options

All optional.

chain_idstringqueryExampleethereumoptional

Disambiguate same-name assets. Tokenomics remains asset-level.

Response

dataobject

supplyobject

Supply subset: asset + supply only (no allocation/unlock/risk, no outer extras)

assetobject

asset_idstringExampleasset_btc

Canonical asset id

namestring | nullExampleBitcoin

Display name

symbolstring | nullExampleBTC

Token symbol

primary_chainstring | nullExamplebitcoin

Primary chain

contract_addressstring | null

Contract address (same rules as tokenomics)

supplyobject

max_supplynumber | string | nullExample21000000

Max supply; may be the string "∞" when unbounded

total_supplynumber | string | nullExample21000000

Total supply; may be the string "∞" when unbounded

circulating_supplynumber | string | nullExample20070484

Circulating supply

unlocked_supplynumber | string | nullExample20070162

Unlocked supply

locked_supplynumber | string | nullExample929518.94

Locked supply

tbd_locked_amountnumber | string | nullExample0

TBD locked residual (key always present)

untracked_supplynumber | string | nullExample0

Untracked residual supply (key always present)

circulating_percentagenumber | nullExample95.57373

Circulating %

unlocked_percentagenumber | nullExample95.5722

Unlocked %

metadataobject

as_ofstringExample2026-08-16

Batch snapshot day (YYYY-MM-DD)

snapshot_kindstringExamplebatch_daily

Always batch_daily

schema_versionstringExample1.0

Nested schema version

currencystringExampleUSD

Currency; defaults to USD

generated_atstring | nullExample2026-08-15T17:05:00.000+0000

Snapshot generation timestamp when present

actual_taskstringExamplesupply

Routed task: profile / statements / metrics / …

data_statusDataStatusExampleok

ok / partial / no_data / not_ready / stale

limitations[]string[]Exampleserving_mvp

Coverage / MVP limitation tags

route_reasonstringExampleexplicit_task

Route reason (e.g. explicit_task)

updated_atdatetime | stringExample2026-08-17T08:25:11Z

Envelope update time (UTC)

object_refs[]object[]

Unified object references

typeObjectRefTypeExampleasset

Object reference type

idstringExampleasset_btc

Canonical object identifier

asset_idstringExampleasset_btc

Canonical asset identifier

data_statusDataStatusExampleok

ok / partial / no_data / not_ready / stale

empty_reasonstring | null

Empty / partial reason code when applicable

errorobject | null

Error object (code / message); null on success

external_refs[]object[]

External refs (e.g. SEC EDGAR filings)

lineage_refs[]object[]

Lineage refs (usually [] on the public body)

source_refs[]object[]

Upstream source refs (usually [] on the public body)

Errors & fallback

200

assets_resolve name multi-match; confirm from data[] candidates.

200

The object resolved but no data is available; empty_reason may be not_covered_by_source, unsupported_metric, or limited_depth.

400

Invalid parameters or an ambiguous market listing; ambiguity responses include required_params + candidates.

401

The API key is missing or invalid.

403

The current key scope or plan cannot access this data domain.

404

The requested resource does not exist; source coverage gaps are not 404 responses.

402

Credits or monthly quota exhausted.

429

Request rate exceeded; retry_after is returned in the body and Retry-After in the response headers.