Tokens
Token Holders
Holders of a token by balance, largest first.
Rendered from /openapi.json. Amounts are raw decimal strings in the units of the asset named beside them; USD values are USD × 1e18, null when unknown, with a usdSource. Quotes are hints: the contract is the final check.
GET
/api/v1/tokens/{address}/holders
Token holders. Holders by balance, largest first (offset pagination). Indexed from Transfer logs (TokenBalance); a balance can lag until the backfiller has scanned wallet-to-wallet Transfers. The token contract itself is never listed as a holder. An invite-only market (or its market token) the caller may not see answers 404, as an unknown address does (GET /api/v1/markets explains the rule).
Auth: API Key
| Param | Type | Description |
|---|---|---|
| address * | string | |
| page | integer | 1-based page. A strict integer; page x limit may reach at most 1,000,000 rows deep. Anything else answers 400 bad_param. |
| offset | integer | Row offset (rounded down to a page start); wins over page. A strict integer 0..1,000,000, else 400 bad_param. |
| limit | integer | A strict integer ("12abc" or "2.5" answer 400 bad_param); clamped to 1..100. |
| protocol | string (include | exclude) | exclude: wallets only. |
| Field | Type | Description |
|---|---|---|
| token | string | |
| main | string | null | |
| holdersCount | integer | Wallets with a positive balance (BASIS contracts and the dead address not counted). |
| protocolHolders | integer | BASIS contracts and the dead address holding the token. The same whatever ?protocol= on the holders route. |
| circulatingSupply | RawAmount | null | Same as TokenDetail: the circulating supply, as the token page shows it. Null when unknown. |
| data | object[] | |
| pagination | Pagination | |
| data[].wallet | string | |
| data[].balance | RawAmount | Raw on-chain integer as a decimal string, in the units of the asset named beside it (pairDecimals, 18 for BASIS tokens). |
| data[].shareBps | integer | null | Of circulatingSupply. |
| data[].isProtocol | boolean | True for a BASIS contract or the dead address. Same definition as holdersCount, protocolHolders and protocol=exclude. |
200 Holders400 Invalid address (invalid_address), page / offset / limit (bad_param), protocol (bad_param, with `allowed`)401 Missing or invalid API key (code unauthorized)404 Token not found (not_found)429 Rate limit exceeded (60 a minute per key), code rate_limited. X-RateLimit-* headers on every answer.503 Trading is not deployed on this network