Skip to main content
GET
GoldRush SDK

Credit Cost

0.02 per item

Processing

Realtime
Estimate your monthly cost for this API using the Pricing Calculator.
The endpoint returns the latest token holders snapshot for: Ethereum, Polygon, BSC, Optimism, Base, Gnosis, ApeChain, Arbitrum, Avalanche, Berachain, Linea, Mantle, Plasma, Taiko, Unichain, and World Chain.Querying historical snapshots via block-height or date is supported only on the Foundational Chains. On other chains, supplying these parameters returns a 400 error.Page size is either 100 (default) or 1000.

What the Token Holders API returns

The Token Holders API returns every address that holds an ERC-20 or ERC-721 token, with its balance, the token’s total supply and decimals, and the block the list is from. One endpoint covers the latest holders and holders at any past block or date, on Ethereum, Base, Arbitrum, Polygon, BNB Smart Chain, Optimism and 10 more chains. It is available on every GoldRush plan, including the free trial, at 0.02 credits per holder returned. Use it for airdrop and reward snapshots, holder concentration and whale tracking, governance voting power at a snapshot block, token and NFT dashboards, and token gating.

Supported chains

All 16 chains return the latest holders. The Foundational chains (Ethereum, Base, BNB Smart Chain, Polygon, Optimism and Gnosis) also return holders at a past block or date; on the others, block-height and date return a 400. Token Holders chain support lists every chain with its chainName and chain ID.

Get every holder of a token

Request 1,000 holders per page with page-size=1000 and step page-number from 0 until pagination.has_more is false:

Count a token’s holders

pagination.total_count on any page is the number of holders, so one request with the default page-size=100 answers “how many holders does this token have?” for at most 2 credits:

Get token holders at a past date or block

Pass date (YYYY-MM-DD) or block-height to get every holder as of one block, a snapshot for an airdrop or a governance vote. Each item carries the block_height it is from, and the same request always returns the same holders.
Past snapshots are served on the Foundational chains only. Elsewhere, call without date or block-height for the latest holders.

Track holder count over time

Read total_count at a series of dates to chart holder growth. Each point is one request at the default page-size=100, so at most 2 credits per date:

Find the top holders and whales

With the full list in hand (see Get every holder of a token), sort by balance for the top holders, or filter by a balance threshold for whales. Balances are raw integers at the token’s decimals, so compare them as BigInts:
Take out addresses that can’t move tokens, such as the 0x…dead burn address, before measuring concentration. For Gini and HHI, see Measuring token holder concentration.

Example response

Abridged to one item and the fields that matter here, from UNI holders on Ethereum on 31 December 2025 (balance rounded):

Reading the response

  • balance and total_supply are raw integers at the token’s decimals, sent as strings. Divide one by the other for a holder’s share of supply. At 18 decimals they exceed JavaScript’s safe integer range, so divide them as BigInts.
  • contract_decimals scales a balance for display: balance / 10^contract_decimals.
  • block_height is the block the list is from. Store it with the data so a figure can be reproduced.
  • updated_at is when the response was generated, and chain_tip_height the chain’s latest block at that time, so you can show how fresh the list is. By default the latest holders come from the last snapshot; pass no-snapshot=true to bypass it.
  • pagination: total_count is the number of holders, has_more is false on the last page, and page-size is 100 (default) or 1000.

FAQ

Request page-size=1000 and step page-number from 0 until pagination.has_more is false. The TypeScript SDK’s getTokenHoldersV2ForTokenAddress does this for you as an async iterator.
Read pagination.total_count from any page. One request at the default page size costs at most 2 credits.
Use base-mainnet (or chain ID 8453) as the chain and the token’s contract address. Base is a Foundational chain, so date and block-height work there too.
Yes, on the Foundational chains: pass block-height or date. On other chains those params return a 400. Token Holders chain support lists both groups.
Fetch every holder, then sort by balance (as BigInt) and take the first N. See Find the top holders and whales.
Sixteen, including Ethereum, Base, Arbitrum, Polygon, BNB Smart Chain and Optimism. See Token Holders chain support for the full table with chain names and IDs.
It is on every plan, including the 14-day free trial with 25,000 credits: enough for 1,250,000 holders at 0.02 credits each.
Yes. Pass an ERC-721 collection’s contract address to get every address that holds at least one token in the collection.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form: Bearer <token>, where <token> is your GoldRush API Key.

Path Parameters

chainName
string
required

The chain name eg: eth-mainnet.

tokenAddress
string
required

The requested address. Passing in an ENS, RNS, Lens Handle, or an Unstoppable Domain resolves automatically.

Query Parameters

no-snapshot
boolean

Defaults to false. Set to true to bypass last snapshot and get the latest token holders list.

block-height
integer

Ending block to define a block range. Omitting this parameter defaults to the latest block height.

date
string

Ending date to define a block range (YYYY-MM-DD). Omitting this parameter defaults to the current date.

page-size
integer

Number of items per page. Note: Currently, only values of 100 and 1000 are supported. Omitting this parameter defaults to 100.

page-number
integer

0-indexed page number to begin pagination.

Response

200 - application/json

Successful response

updated_at
string<date-time>

The timestamp when the response was generated. Useful to show data staleness to users.

chain_id
integer

The requested chain ID eg: 1.

chain_name
string

The requested chain name eg: eth-mainnet.

chain_tip_height
integer

The latest block height of the blockchain at the time this response was provided.

chain_tip_signed_at
string<date-time>

The timestamp of the latest signed block at the time this response was provided.

items
object[]

List of response items.

pagination
object

Pagination metadata.