Top holders of a token

See holders on an entity page →

The largest current holders of a token contract on Ethereum mainnet — up to 100 of them in descending balance order, plus holderCount: how many addresses hold a positive balance right now.

Holders are stated only for tokens whose balances are covered — today that leaves out every NFT collection. Such a token is refused with 422 token_not_covered rather than answered with an empty list: "not covered" is not "nobody holds it".

GET https://tracefast.xyz/api/v1/chains/1/tokens/{token}/holders

Parameter	In	Type	Notes
`token`	path	string	the token contract address, `0x`-prefixed, 40 hex characters, any case
`limit`	query	integer, optional	1..100, default 100

chains/1 is a literal: the method serves Ethereum mainnet data. Other chain ids answer 404 chain_not_supported. There are no other parameters — in particular there is no as-of-block form: only the current ranking exists, and block is refused rather than quietly ignored.

Access — an API key on the Intelligence plan or higher (plans), or no key at all: pay per call with x402 at the same path on https://mpp.tracefast.xyz/api/v1, at the price its 402 states. As a tool for AI agents: get_token_holders on the MCP server. Stable — see stability.

Response

200 application/json, here with ?limit=3:

{
  "data": {
    "token": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "holderCount": 15965087,
    "holders": [
      { "address": "0xf977814e90da44bfa03b6295a0616a897441acec", "balance": "17000000000000198" },
      { "address": "0x47ac0fb4f2d84898e4d9e7b4dab3c24507a6d503", "balance": "9184997801482302" },
      { "address": "0x835678a611b28684005a5e2233695fb6cbbb0007", "balance": "5508960113234750" }
    ]
  },
  "meta": {
    "chain": "ethereum",
    "timestamp": 1788454017710,
    "cached": true,
    "docs": "https://docs.tracefast.xyz/api/token-holders"
  }
}

Field	Meaning
`data.token`	the token contract, lowercase
`data.holderCount`	how many addresses hold a positive balance now — the size of the set this list is the top of. An address that once held and now holds nothing is not counted
`data.holders[]`	at most `limit` rows in descending balance order, with no rank number: balances can tie, and the order is all the data supports
`holders[].address`	the holder address, lowercase
`holders[].balance`	a decimal string in the token's smallest unit
`meta.cached`	`true` when the answer came from the response cache

A covered token with no current holders answers 200 with an empty list and holderCount: 0 — a real zero, not an error. A token outside the covered set is a 422, never a zero.

Two things to get right

Balances are integers, not amounts. balance is in the token's smallest unit and is not divided by decimals. USDT has 6 decimals, so "17000000000000198" is 17,000,000,000.000198 USDT. Read decimals from the contract before displaying anything.

These are the same balances as everywhere else. A holder's balance here is the balance token balance answers for that address and token, and the one the portfolio values. The ranking and the single-balance answer never disagree.

Errors

Every error is JSON: { "error": { "code": "...", "message": "...", "details": { … } } }

Status	`code`	When	`details`
400	`bad_request`	malformed token address; `limit` outside 1..100; an unknown query parameter	`reason: limit_out_of_range`, `maxLimit: 100`
400	`bad_request`	`block` was passed — only the current ranking exists	`reason: block_not_supported`
404	`chain_not_supported`	a chain id other than `1`	—
422	`token_not_covered`	the token's balances are not covered, so neither a holder list nor a holder count can be stated — not zero holders. Today this is every NFT collection	`token`
402	—	payment required, or payment rejected — see Paying with x402	—

Numbers a client has to act on are in details, never parsed out of message.

API — the method list and the response envelope
Paying with x402 — how a call is paid for
Address counterparties — who an address deals with
Address attributes — what an address is
Tokens & Collections — the same ranking, read in the app

Last updated 22 Oct 2026, 08:06 UTC · verified against TraceFast v1.0.261 · Markdown

Top holders of a token

Response

Two things to get right

Errors

Related pages