Skip to main content
The Token Holders API (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. 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. 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

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

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.
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 to estimate a month of usage.