Tokenomics

Query tokenomics and unlock data.

GET/api/v1/fundamentals/tokenomics

Domain

Fundamentals

Level

Crypto asset

MCP tool

fundamentals_query (task=tokenomics)

Available data

Returns: Tokenomics and unlock data
Market coverage: Crypto
Query granularity: One token per query; daily snapshot, not mixed with other tokens

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

tokenomicsobject

Nested batch object (strict 5 sections): asset / supply / allocation_summary / unlock_summary / risk_summary; no outer extras; no coverage → no_data

assetobject

asset_idstringExampleasset_btc

Canonical asset id (e.g. asset_btc)

namestring | nullExampleBitcoin

Display name

symbolstring | nullExampleBTC

Ticker / token symbol

primary_chainstring | nullExamplebitcoin

Primary chain (key always present; null when unknown)

contract_addressstring | null

Contract address (key always present; null for natives / scrubbed mints / unknown)

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; always present; completes total composition

untracked_supplynumber | string | nullExample0

Untracked residual supply; always present; completes total composition

circulating_percentagenumber | nullExample95.57373

Circulating % of supply

unlocked_percentagenumber | nullExample95.5722

Unlocked % of supply

allocation_summaryobject

team_and_founders_percentagenumber | nullExample0

Team & founders allocation %

investors_percentagenumber | nullExample0

Investors allocation %

community_and_ecosystem_percentagenumber | nullExample100

Community & ecosystem allocation %

treasury_and_reserve_percentagenumber | nullExample0

Treasury & reserve allocation %

others_percentagenumber | nullExample0

Others / residual allocation %

unlock_summaryobject

next_unlock_datestring | null

Next unlock timestamp (RFC3339 / ISO8601)

next_unlock_amountnumber | string | null

Next unlock amount

next_unlock_percentage_of_circulatingnumber | null

Next unlock as % of circulating supply

next_unlock_categorystring | null

Next unlock category (e.g. team_and_founders)

risk_summaryobject

supply_pressure_levelstring | nullExamplelow

Supply pressure level (low / medium / high, …)

supply_pressure_scorenumber | nullExample4

Supply pressure score

main_factorstring | nullExample剩余锁仓占 Tokenomics 总供应量 4.426281%

Primary pressure factor (natural language)

metadataobject

as_ofstringExample2026-08-16

Batch snapshot day (YYYY-MM-DD)

snapshot_kindstringExamplebatch_daily

Always batch_daily for this path

schema_versionstringExample1.0

Nested response schema version

currencystringExampleUSD

Currency; defaults to USD

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

Snapshot generation timestamp when present

actual_taskstringExampletokenomics

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:08Z

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.