Token holders API

GET/tokens/:chain/:address/holders

Who holds a token now: its largest holders with their balance, share, USD value, labels and position (PnL), the holder count where it can be known, and how complete the list is.

Who holds a token now, with labels and PnL, and how complete the list is. The holders channel sends it again each time it changes.

Parameters

Name	In	Type	Default	Allowed values
`chain`	path	string	required	`evm:56` (BSC), `solana`, `evm:8453` (Base), `evm:4663` (Robinhood Chain) or `evm:1` (Ethereum)
`address`	path	string	required	Token address (BSC) or mint (Solana)
`limit`	query	integer	`20`	1–100
`cursor`	query	string	first page	The previous page's `next`: pages reach the 1,000 largest

Response

Field	Type	Meaning
`chain`, `token`, `indexedSince`	string, object, number	`token` is `{ address, symbol, name, decimals }`; `indexedSince` bounds the positions, as in Wallets and PnL.
`source`	string	How the list was established: `indexed-transfers`, `indexed-addresses` (BSC), `token-accounts`, `largest-accounts` (Solana). See the notes.
`complete`, `coverage`	boolean, string	Whether the list holds every holder, and what it covers, in words.
`block`	number	The block (Solana: slot) the balances are at.
`supply`, `priceUsd`	string \| null, number \| null	Total supply (decimals applied) and the token's price now.
`count`, `top10Share`	number \| null	How many addresses hold any, and the share of the supply the 10 largest hold, pools and the burn address left out. Only from a complete list; otherwise null.
`holders[]`	array	Largest first; ties by address. On Solana a holder is the owner of the token accounts: one per owner.
`holders[].address`, `balance`, `share`, `valueUsd`	string, string, number \| null, number \| null	The holder, its balance (decimals applied), its share of `supply`, and `balance × priceUsd`.
`holders[].tags`	string[]	`pool`: a pool of the token keeps it there (the pool, the contract holding a V4 pool's funds, or a Solana pool's vault). `burn`: a burn address. `creator`: the token's creator, when Aurelia saw the creation.
`holders[].labels`	string[]	The holder's labels.
`holders[].position`	object \| null	The holder's position in the token, as in wallet positions without `token`. Null for a pool, and for an address that never traded it.
`next`	string \| null	Cursor for the next page. `null` on the last.

Example

Captured 2026-09-28 18:03 UTC on a test instance, trimmed to 3 holders.

curl -s -H 'Authorization: Bearer <key>' 'https://app.aurelia.build/api/tokens/evm:56/0xa9fcda9bd321adeb7cbbbd30ef2dd0ed1d657777/holders?limit=3'

{
  "chain": "evm:56",
  "token": {
    "address": "0xa9fcda9bd321adeb7cbbbd30ef2dd0ed1d657777",
    "symbol": "TAX",
    "name": "Tax Token",
    "decimals": 18
  },
  "source": "indexed-transfers",
  "complete": true,
  "coverage": "Every holder: the index holds the token's whole history, and its largest balances match the chain.",
  "indexedSince": 1790546261920,
  "block": 1000750,
  "supply": "1000000000",
  "priceUsd": 0.006,
  "count": 13,
  "top10Share": 0.30015722,
  "holders": [
    {
      "address": "0x702e6533e0182381606adbe3ccbb77f682ccc58b",
      "balance": "699837340",
      "share": 0.69983734,
      "valueUsd": 4199024.04,
      "tags": [
        "pool"
      ],
      "labels": [],
      "position": null
    },
    {
      "address": "0x0f325bd174c70440fa62c31dce9f69d54baf717e",
      "balance": "200000000",
      "share": 0.2,
      "valueUsd": 1200000,
      "tags": [
        "creator"
      ],
      "labels": [
        "creator"
      ],
      "position": null
    },
    {
      "address": "0x5c952063c7fc8610ffdb798152d69f0b9550762b",
      "balance": "73000000",
      "share": 0.073,
      "valueUsd": 438000,
      "tags": [],
      "labels": [],
      "position": null
    }
  ],
  "next": "3"
}

Notes

BSC, indexed-transfers (complete): the sums of every Transfer the index holds, served only when the index has the token's whole history: all of its supply minted since indexing began, no recorded gap after its first transfer, and at the newest indexed block its supply and its 20 largest balances equal to the chain's (a rebasing or reflection token fails). The verdict is kept 5 minutes. One database query, not kept.
BSC, indexed-addresses (incomplete): any other token, most of all one minted before indexing began. The 300 addresses whose indexed balance moved most, its pools, its creator and the burn address, each read with balanceOf at the chain's head: every balance is exact, but holders that have not moved the token since indexing began are missing, so there is no count. The node keeps no older state or logs: the holder count of an older token cannot be established.
Solana (only DEX transactions are indexed, so balances come from the chain): token-accounts (complete) lists every token account of the mint, one holder per owner; largest-accounts (incomplete) is a mint with too many accounts to list, its 20 largest accounts.
A list read from the chain is kept 30 s (BSC) or 60 s (Solana), the answer 5 s. Reads spend the chain's read budget: past it, 503 with Retry-After: 10. 422 for an address that is not a token mint, 502 when the chain cannot be read, 404 {"error":"unknown token"} for a token Aurelia has never stored.
The holders channel sends the first 100 again each time they change.

Try it in the interactive docs Create a free account