Token Holder API

Every holder of an ERC-20 or ERC-721 token, with balances, on Ethereum, Base and 14 more chains. Ask for today's holders or the holders at any past block or date, at 0.02 credits per holder.

Get a free API keyRead the API reference
UNI holders on Ethereum31 Dec 2025, block 24,128,884
Holders
386,723
Held by the top 6
47.43%
Largest UNI holders on 31 Dec 2025
AddressSupply
0x1a9c…35bc26.96%
0x0000…dead10.01%
0xf977…acec5.33%
0x61cb…96eb2.30%
0x5069…0f7e1.49%
0x611f…b09d1.33%
One call to token_holders_v2 with date=2025-12-31, 0.02 credits per holder returned.

Used by EY, Fidelity and Consensys

  • EY
  • Fidelity
  • Consensys
  • Jump
  • Ondo
  • ThorWallet
  • Rainbow
  • Matcha
  • Velora
  • AtomicWallet
  • Atlas Wallet
  • OneKey
Read the case studies

Get every holder of a token

One endpoint, token_holders_v2, with the chain and the token's contract address. Each item is one holder: its address, raw balance, the token's total supply and decimals, and the block the list is from.

pagination.total_count is the number of holders, so the first page tells you how many more to request. Pages hold 100 holders, or 1,000 with page-size=1000.

API=https://api.covalenthq.com/v1
AUTH="Authorization: Bearer $GOLDRUSH_API_KEY"
UNI=0x1f9840a85d5af5bf1d1762f925bdaddc4201f984
URL="$API/eth-mainnet/tokens/$UNI/token_holders_v2/"

# The latest UNI holders, 1,000 a page: 20 credits a page
curl "$URL?page-size=1000&page-number=0" -H "$AUTH"

# Step page-number until pagination.has_more is false
curl "$URL?page-size=1000&page-number=1" -H "$AUTH"

Token holders at any past block or date

Pass date or block-height and every holder comes back as of one block, which each item carries. Rerun the same request and you get the same holders, so an airdrop list, a governance snapshot or a concentration chart can be checked by anyone. Past snapshots work on the 6 Foundational chains: Base, BNB Smart Chain (BSC), Ethereum, Gnosis, Optimism, Polygon.

import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY!);
const UNI = "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984";

// Every UNI holder as of 31 Dec 2025. The SDK steps
// through the pages for you.
const balances: bigint[] = [];
let supply = 0n;
for await (const page of client.BalanceService
    .getTokenHoldersV2ForTokenAddress("eth-mainnet", UNI, {
        date: "2025-12-31",
        pageSize: 1000,
    })) {
    for (const h of page.data?.items ?? []) {
        balances.push(BigInt(h.balance ?? 0));
        supply = BigInt(h.total_supply ?? 0);
    }
}

// Share of supply held by the 10 largest holders
balances.sort((a, b) => (b > a ? 1 : b < a ? -1 : 0));
const top10 = balances.slice(0, 10).reduce((s, b) => s + b, 0n);
console.log(Number((top10 * 10_000n) / supply) / 100, "%");
API=https://api.covalenthq.com/v1
UNI=0x1f9840a85d5af5bf1d1762f925bdaddc4201f984
URL="$API/eth-mainnet/tokens/$UNI/token_holders_v2/"
AUTH="Authorization: Bearer $GOLDRUSH_API_KEY"

# UNI holder count at each quarter end: up to 2 credits a date
for d in 2025-03-31 2025-06-30 2025-09-30 2025-12-31; do
  curl -s "$URL?date=$d" -H "$AUTH" \
    | jq -r --arg d "$d" '"\($d) \(.data.pagination.total_count)"'
done

Holder count over time

pagination.total_count at a past date is the number of holders on that day. Read it at month or quarter ends to chart holder growth, at up to 2 credits a point, on any Foundational chain.

The same call with page-size=1000 and every page gives the full list at that date, for distribution and top-holder share over time.

What teams build with holder data

  • Airdrop and reward snapshots

    Every eligible holder and balance at the block you announced, so the list can be checked by anyone who reruns the call.

    Holders at a past block

  • Concentration and whale tracking

    The share of supply held by the top 10, 100 or 1,000 addresses, and how it moves after a vesting release or a listing.

    Compute Gini and HHI from a holder list

  • Governance

    Voting power per address at a proposal's snapshot block, from the same call on any Foundational chain.

  • Token and NFT dashboards

    Holder counts, distribution charts and top-holder tables for a token page, or the owners of an ERC-721 collection.

    Historical blockchain data API

How to choose a token holder API

Holder API roundups score providers on the same few things. Here is how GoldRush does on each, including where it falls short.

Criteria for choosing a token holder API, and how the GoldRush Token Holder API meets each
What to checkGoldRush
Distribution, not just a countBalances and total supply for every holder, so shares and concentration can be computedtotal_supply on every item and total_count on every page; top-10 share in a few lines
Historical snapshotsHolders at a past block or date, not only todayOn the 6 Foundational chains with date or block-height; latest only on the other 10
Contract and exchange filteringLabels for pools, bridges and exchange wallets, which distort concentrationNo labels: exclude the burn address and the contracts you know yourself
Chain coverageThe chains your token lives on, behind one interface16 EVM chains on one endpoint and one key. No Solana.
FreshnessHow old the latest list isupdated_at and chain_tip_height on every response; no-snapshot=true skips the last snapshot
Plan and priceWhich plan the data needs, and what a full list costsEvery plan, including the free trial; 0.02 credits per holder returned

Sources: Token Holders API reference and Token Holders chain support.

Token holders on 16 chains

All 16, including Ethereum, Base, Arbitrum and Polygon, return the latest holders. The Foundational chains also return holders at a past block or date; elsewhere, those params return a 400.

Token Holders API chains16 chains
Chains the GoldRush Token Holders API supports, and which serve past snapshots
ChainPast block or date
BaseYes
BNB Smart Chain (BSC)Yes
EthereumYes
GnosisYes
OptimismYes
PolygonYes
ApeChainLatest only
ArbitrumLatest only
Avalanche C-ChainLatest only
BerachainLatest only
LineaLatest only
MantleLatest only
PlasmaLatest only
TaikoLatest only
UnichainLatest only
World ChainLatest only
From the endpoint's chain list in the docs. Pass the chain name or the chain ID in the URL.

Etherscan token holder API alternative

Etherscan's holder list is the usual starting point. Here is what changes when the same job runs on GoldRush.

Etherscan tokenholderlist compared with the GoldRush Token Holders API
Etherscan tokenholderlistGoldRush token_holders_v2
Plan requiredA PRO endpoint, on the Standard plan and aboveEvery plan, including the free trial, at 0.02 credits per holder
Holders at a past block or dateNo: the current list onlyYes, with block-height or date, on 6 Foundational chains
Fields per holderAddress and quantityAddress, balance, total supply, decimals, block height and token metadata
Holder countA separate tokenholdercount callpagination.total_count in every response
Token standardsERC-20ERC-20 and ERC-721

Sources: Etherscan tokenholderlist, Etherscan tokenholdercount and GoldRush Token Holders API reference.

Start free

Every account starts with a 14-day free trial and 25,000 credits: enough for 1,250,000 holders. The same key works on every Foundational API endpoint, and plans start at $10 a month.

What holder data costs0.02 credits per holder
Example Token Holder API costs in credits
RequestCredits
A token's holder count (one page of 100)2
1,000 holders (one page of 1,000)20
Holder count at 12 month ends24
Every UNI holder at the end of 2025 (386,723)7,734.46
At most: a token with fewer holders than a full page costs less.
Get a free API keySee pricingEstimate your cost

Token Holder API FAQ

An API that returns the addresses holding a token and how much each holds. No contract stores that list, so it has to be rebuilt from every transfer; the API does that indexing. GoldRush's is token_holders_v2, part of the Foundational API: every holder of an ERC-20 or ERC-721 token, with balances, total supply, decimals and the block the list is from.

Token Holder API docs

Reference

Guides

Related