Get the largest holders of a token as a map, with the transfers between them
/v1/chains/{chain}/tokens/{token}/holder-mapCall this for the bubble map of a token page. data.nodes are the limit largest holders, largest first, each with its balance (the decimal value), its share of the total supply (null when the supply is 0), a label, its kind and its cluster. data.links are pairs of nodes that sent each other the token, and data.clusters the groups of nodes that links connect.
- Nodes: on Ethereum they are Blockscout's holder list (coverage
token_holders_ranked_by_provider), withkindcontractorwalletand a name tag or contract name aslabel. On Monad and Arc they come from Sona's index, only when the index of the token is complete (coveragetoken_balances_from_transfers), withkindunknownand nolabel. Otherwisenodesis empty with coveragetoken_holder_map_index_incomplete, ortoken_index_unavailablewhen the index cannot take the token. The first request for a Monad or Arc token starts building its index. - Links: read on Ethereum only (on Monad
links.statusisunavailablewith coveragetoken_holder_map_links_ethereum_only). They are theTransferlogs of the last 30 days between two nodes. Each item is one unordered pair,fromis the lower address of the two and not the sender,transferscounts both directions andamountsums them in token units.links.statusisready(itemsholds the stored read,built_atsays when it finished andwindow_daysthe days it covers),building(no read is stored yet and one is queued,itemsis empty, so ask again in a minute or a few) orunavailable(no read will come for now, and coverage says why). A busy token whose 30 days do not fit in the read gets a shorter window that ends at the newest block (coveragetoken_holder_map_window_cut). Coveragetoken_holder_map_queue_fullsays too many maps wait for links, andtoken_holder_map_links_failedthat the last read failed and is retried 10 minutes later. - Clusters: the nodes that links connect, directly or through other nodes. Only clusters of two or more nodes are listed, largest
sharefirst,idis that rank from 1 and a node'sclusteris its cluster'sid(nullwithout links). A cluster says the holders moved the token between each other, which can be one owner's wallets, an exchange and its hot wallets, or a pool and a router. It does not say they share an owner.
Each limit is its own map with its own links. Sona keeps an answer with links.status ready or unavailable for 10 minutes, and one with building for 15 seconds, so a new read shows soon. The token is a 0x address of 40 hex digits in any case, which Sona lowercases. limit is a whole number from 50 to 250 (default 100).
Path parameters
| Name | Type | Description |
|---|---|---|
chainRequired | string | The chain, as a CAIP-2 chain ID. Ethereum, |
tokenRequired | string | The token contract: |
Query parameters
| Name | Type | Description |
|---|---|---|
limit | integerDefault 100 | How many of the largest holders the map shows, from 50 to 250. Default: 100. Each value is its own map with its own links. A number out of range answers 400 |
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 |
| clusters | array of objects | Clusters of two or more nodes, largest share first. |
| coverage | array of strings | The codes of the limits that apply to this answer, in a fixed order. It is empty when none applies. |
| kind | string | holder_map |
| links | object | |
| nodes | array of objects | The largest holders, largest first. |
| token | string |
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 a limit out of range or another 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, 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.