# Token holders API

> A token's largest holders, with what each holds, what it is worth and how that wallet has done, and a plain statement of how complete the list is.

## Read the largest holders

A token's 100 largest holders:

```bash
curl -s -H 'Authorization: Bearer <key>' 'https://app.aurelia.build/api/tokens/solana/7GCihgDB8fe6KNjn2MYtkzZcRjQy3t9GHdC8uHYmW2hr/holders?limit=100'
```

[`GET /tokens/:chain/:address/holders`](https://app.aurelia.build/docs/token-holders) returns up to 100 a page, and pages reach the 1,000 largest. A request costs 1 credit.

| Field | What it is |
|---|---|
| `count`, `top10Share` | How many addresses hold any, and the supply share of the 10 largest, pools and the burn address left out. Only from a complete list, otherwise `null` |
| `complete`, `coverage`, `source` | How complete the list is, and where it was read from |
| `holders[].address`, `balance`, `share`, `valueUsd` | Who, how much, what share of supply, and its USD value |
| `holders[].tags`, `labels` | `pool`, `burn` or `creator`, and its [wallet labels](https://app.aurelia.build/docs/labels) |
| `holders[].position` | That wallet's position in this token, with its PnL. `null` for a pool, or an address that never traded it |

## How complete the list is, per chain

- Solana: complete, one holder per owner, unless the mint has too many token accounts. Then its 20 largest, and the answer says so.
- EVM chains: complete, with a count, for a token whose whole history the index holds. Otherwise the balances of the addresses that moved it, with no count.

A list that is not complete gives `null` for its count, never a guess. Read `complete` before you treat a list as everyone.

## Check concentration

The largest holders' share of supply:

```javascript
const res = await fetch(
  "https://app.aurelia.build/api/tokens/solana/7GCihgDB8fe6KNjn2MYtkzZcRjQy3t9GHdC8uHYmW2hr/holders?limit=10",
  { headers: { Authorization: "Bearer <key>" } },
);
const { complete, top10Share, holders } = await res.json();
if (complete) console.log("top 10 hold", top10Share);
for (const h of holders) console.log(h.address, h.share, h.valueUsd);
```

## Follow holders live

The [holders channel](https://app.aurelia.build/docs/live-holders) sends the same body for a token's 100 largest, and sends it again as they change.

## Related

- [Holders reference](https://app.aurelia.build/docs/token-holders).
- [Honeypot check API](https://app.aurelia.build/guides/honeypot-check-api): `top10Share` as part of a token's risk checks.
- [Wallet PnL API](https://app.aurelia.build/guides/wallet-pnl-api): follow a holder further.