> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Holders Chain Support

> Which chains the GoldRush Token Holders API serves: latest ERC-20 and ERC-721 holders on 16 chains including Ethereum, Base, Arbitrum and Polygon, and holders at a past block or date on the Foundational chains.

The [Token Holders API](https://goldrush.dev/docs/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2.md) (`token_holders_v2`) returns every holder of an ERC-20 or ERC-721 token with its balance. What it can return depends on the chain:

* **Latest holders** are served on every chain in the table below.
* **Holders at a past block or date** (the `block-height` and `date` params) are served only on the [Foundational chains](https://goldrush.dev/docs/chains/overview.md#foundational-chains). On any other chain, passing either param returns a `400`.

### Supported chains

The Token Holders API serves **16 chains**. All of them return the latest holders; **6** of them, the Foundational chains, also return holders at a past block or date.

| Chain | `chainName` | Chain ID | Latest holders | Holders at a past block or date |
| - | - | - | - | - |
| [Base](https://goldrush.dev/docs/chains/base.md) | `base-mainnet` | 8453 | Yes | Yes |
| [BNB Smart Chain (BSC)](https://goldrush.dev/docs/chains/bnb-smart-chain-bsc.md) | `bsc-mainnet` | 56 | Yes | Yes |
| [Ethereum](https://goldrush.dev/docs/chains/ethereum.md) | `eth-mainnet` | 1 | Yes | Yes |
| [Gnosis](https://goldrush.dev/docs/chains/gnosis.md) | `gnosis-mainnet` | 100 | Yes | Yes |
| [Optimism](https://goldrush.dev/docs/chains/optimism.md) | `optimism-mainnet` | 10 | Yes | Yes |
| [Polygon](https://goldrush.dev/docs/chains/polygon.md) | `matic-mainnet` | 137 | Yes | Yes |
| [ApeChain](https://goldrush.dev/docs/chains/apechain.md) | `apechain-mainnet` | 33139 | Yes | No |
| [Arbitrum](https://goldrush.dev/docs/chains/arbitrum.md) | `arbitrum-mainnet` | 42161 | Yes | No |
| [Avalanche C-Chain](https://goldrush.dev/docs/chains/avalanche-c-chain.md) | `avalanche-mainnet` | 43114 | Yes | No |
| [Berachain](https://goldrush.dev/docs/chains/berachain.md) | `berachain-mainnet` | 80094 | Yes | No |
| [Linea](https://goldrush.dev/docs/chains/linea.md) | `linea-mainnet` | 59144 | Yes | No |
| [Mantle](https://goldrush.dev/docs/chains/mantle.md) | `mantle-mainnet` | 5000 | Yes | No |
| [Plasma](https://goldrush.dev/docs/chains/plasma.md) | `plasma-mainnet` | 9745 | Yes | No |
| [Taiko](https://goldrush.dev/docs/chains/taiko.md) | `taiko-mainnet` | 167000 | Yes | No |
| [Unichain](https://goldrush.dev/docs/chains/unichain.md) | `unichain-mainnet` | 130 | Yes | No |
| [World Chain](https://goldrush.dev/docs/chains/world-chain.md) | `world-mainnet` | 480 | Yes | No |

Pass either the `chainName` or the chain ID as the first path segment. Both resolve to the same chain.

### Latest holders on any supported chain

```bash theme={null}
curl -u "$GOLDRUSH_API_KEY:" \
  "https://api.covalenthq.com/v1/arbitrum-mainnet/tokens/0x912CE59144191C1204E64559FE8253a0e49E6548/token_holders_v2/?page-size=1000"
```

Holders come back 100 per page by default, or 1,000 with `page-size=1000`. `pagination.total_count` is the number of holders, so you know how many pages to request.

### Holders at a past date on a Foundational chain

```bash theme={null}
curl -u "$GOLDRUSH_API_KEY:" \
  "https://api.covalenthq.com/v1/base-mainnet/tokens/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913/token_holders_v2/?date=2026-01-01"
```

Use `block-height` instead of `date` to pin the snapshot to an exact block. Each item carries the `block_height` it was taken at, so rerunning the same request returns the same holders.

> [!WARNING]
>
> On a chain marked **No** in the last column, the same request with `date` or `block-height` returns `400`. Call it without either param to get the latest holders instead.

### Cost

Every holder returned costs `0.02` credits, on every chain and for both latest and past snapshots: 1,000 holders cost 20 credits. Use the [Pricing Calculator](https://goldrush.dev/docs/pricing-calculator.md?endpoint=%2Fapi-reference%2Ffoundational-api%2Fbalances%2Fget-token-holders-as-of-any-block-height-v2) to estimate a month of usage.

### Related

* [Token Holders API reference](https://goldrush.dev/docs/api-reference/foundational-api/balances/get-token-holders-as-of-any-block-height-v2.md): every parameter and response field.
* [Measuring token holder concentration (Gini & HHI)](https://goldrush.dev/docs/goldrush-foundational-api/guides/token-holders-goldrush-vs-etherscan.md): pull every holder, then compute concentration at a past block.
* [Foundational API supported chains](https://goldrush.dev/docs/goldrush-foundational-api/supported-chains.md): every chain the Foundational API serves.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.