Get what a token is, its supply, price, market cap and holder count
/v1/chains/{chain}/tokens/{token}Call this for the head of a token page. data holds the token's name and symbol (null when the contract does not answer them), decimals, total_supply and:
price_usd: the current price,nullwhen no price is known (coveragetoken_price_unknown).fdv_usd:total_supplytimesprice_usd,nullwithout a price.market_cap_usd: the circulating market cap a data provider reports,nullwhen it reports none. Providers count a token's supply on every chain, so for a bridged token such as USDC it is above this chain'sfdv_usd, and the record then holdstoken_market_cap_multichain.holder_countandtop10_share(the share of the 10 largest holders), from the same provider.logo_url: the token's logo as an https URL, from a curated token list first and a data provider next,nullwhen none gives one.sources: the sources that answered, andcoverage: the limits that apply. When a provider fails the record still answers, with the fields it feeds set tonullandtoken_source_unavailableincoverage.
An address is a token when it answers both decimals() and totalSupply(). The route takes no query parameters, and the token is a 0x address of 40 hex digits in any case, which Sona lowercases. Sona keeps the answer for 1 minute, but one whose coverage holds token_source_unavailable for 15 seconds, so the full record replaces it soon.
Path parameters
| Name | Type | Description |
|---|---|---|
chainRequired | string | The chain, as a CAIP-2 chain ID. Ethereum, |
tokenRequired | string | The token contract: |
Response
The answer, wrapped in the {data, meta, links} envelope. meta.finality is none, because the record is not about one block.
| Field | Type | Description |
|---|---|---|
| chain | string | A chain ID in the CAIP-2 format |
| coverage | array of strings | The codes of the limits that apply to this answer, in a fixed order. It is empty when none applies. |
| decimals | integer | |
| fdv_usd | number | null | The total supply times the price in US dollars, null without a price. |
| holder_count | integer | null | |
| kind | string | token_info |
| logo_url | string | null | The token's logo as an https URL, from a curated token list or a data provider. Null when none gives one. |
| market_cap_usd | number | null | The circulating market cap a provider reports in US dollars, null when it reports none. |
| name | string | null | The contract's name, null when it does not answer one. |
| price_usd | number | null | The price of one whole token in US dollars, null when none is known. |
| sources | array of strings | The data sources that answered. |
| symbol | string | null | The contract's ticker, null when it does not answer one. |
| token | string | The token address in lowercase. |
| top10_share | number | null | The share of the total supply the 10 largest holders keep, from 0 to 1. |
| total_supply | object | A token quantity, given both exactly and in a readable form. |
Cost
1 credit. The time limit is 5 seconds.
Errors
| Status | Code |
|---|---|
| 400 | invalid_idinvalid_query |
| 404 | unsupported_chainnot_found |
| 429 | rate_limitedcredits_exhausted |
| 500 | internal |
| 503 | upstream_unavailable |
| 504 | deadline_exceeded |
400 invalid_id for a chain that is no CAIP-2 id or a token that is not 0x and 40 hex digits (native included), 400 invalid_query for any query key, 404 unsupported_chain for a chain other than Ethereum, Monad and Arc, 404 not_found when the address is not an ERC-20 token (it answers decimals() and totalSupply() or it is none), 429 rate_limited or credits_exhausted, 503 upstream_unavailable with retry_after_s when a data source the route needs does not answer, and 504 deadline_exceeded when the budget runs out.