Balance Endpoints
Bitcoin Balance API
Operation Identity:- Operation ID:
getBitcoinBalanceForWalletAddress GET /v1/btc-mainnet/address/{walletAddress}/balances_v2/- SDK:
BitcoinService.getBitcoinNonHdWalletBalances()
Path Parameters
Query Parameters
Response Fields
Item Fields
Credit Cost: 1 per call
Processing: Realtime
Tip: Estimate your monthly cost for this API using the Pricing Calculator.
Bitcoin HD Wallet Balance API
Operation Identity:- Operation ID:
getBitcoinHdWalletBalances GET /v1/btc-mainnet/address/{walletAddress}/hd_wallets/- SDK:
BitcoinService.getBitcoinHdWalletBalances()
Path Parameters
Query Parameters
Response Fields
Item Fields
Credit Cost: 0.1 per item
Processing: Realtime
Tip: Estimate your monthly cost for this API using the Pricing Calculator.
Note: Requests that return status 200 and no data cost 0.1 credits.
ERC-20 Token Transfers API
Operation Identity:- Operation ID:
getErc20TransfersForWalletAddress GET /v1/{chainName}/address/{walletAddress}/transfers_v2/- SDK:
BalanceService.getErc20TransfersForWalletAddress()
Path Parameters
Query Parameters
Response Fields
Item Fields
Pagination Fields
Credit Cost: 0.05 per item
Processing: Realtime
Tip: Estimate your monthly cost for this API using the Pricing Calculator.
Historical Bitcoin Balance API
Operation Identity:- Operation ID:
getHistoricalBitcoinBalanceForWalletAddress GET /v1/btc-mainnet/address/{walletAddress}/historical_balances/- SDK:
BitcoinService.getBitcoinNonHdWalletBalances()
Path Parameters
Query Parameters
Response Fields
Item Fields
Credit Cost: 1 per call
Processing: Realtime
Tip: Estimate your monthly cost for this API using the Pricing Calculator.
Historical Portfolio Value API
Operation Identity:- Operation ID:
getHistoricalPortfolioForWalletAddress GET /v1/{chainName}/address/{walletAddress}/portfolio_v2/- SDK:
BalanceService.getHistoricalPortfolioForWalletAddress()
Path Parameters
Query Parameters
Response Fields
Item Fields
Credit Cost: 2 per 30 days
Processing: Realtime
Tip: Estimate your monthly cost for this API using the Pricing Calculator.
Note: Rebasing tokens (e.g. stETH, aTokens, cTokens) are supported on Foundational Chains.
Historical Token Balance API
Operation Identity:- Operation ID:
getHistoricalTokenBalancesForWalletAddress GET /v1/{chainName}/address/{walletAddress}/historical_balances/- SDK:
BalanceService.getHistoricalTokenBalancesForWalletAddress()
Path Parameters
Query Parameters
Response Fields
Item Fields
Credit Cost: 1 per call
Processing: Realtime
Tip: Estimate your monthly cost for this API using the Pricing Calculator.
Note: Endpoint only supported on all Foundational Chains.Rebasing tokens (e.g. stETH, aTokens, cTokens) also supported on Foundational Chains.
Native Token Balance API
Operation Identity:- Operation ID:
getNativeTokenBalance GET /v1/{chainName}/address/{walletAddress}/balances_native/- SDK:
BalanceService.getNativeTokenBalance()
Path Parameters
Query Parameters
Response Fields
Item Fields
Credit Cost: 0.5 per call
Processing: Realtime
Tip: Estimate your monthly cost for this API using the Pricing Calculator.
Note: Not supported on non-EVM chains such as Bitcoin and Solana.
ERC-20 Token Balance API
Operation Identity:- Operation ID:
getTokenBalancesForWalletAddress GET /v1/{chainName}/address/{walletAddress}/balances_v2/- SDK:
BalanceService.getTokenBalancesForWalletAddress()
Path Parameters
Query Parameters
Response Fields
Item Fields
Credit Cost: 1 per call
Processing: Realtime
Tip: Estimate your monthly cost for this API using the Pricing Calculator.
Note: Rebasing tokens (e.g. stETH, aTokens, cTokens) are supported on Foundational Chains.
Related guides
Understanding Web3 Wallets with GoldRush How to Get Bitcoin Balances and Transactions Comparing GoldRush’s Token Balances API to RPC ProvidersToken Holders API
Operation Identity:- Operation ID:
getTokenHoldersV2ForTokenAddress GET /v1/{chainName}/tokens/{tokenAddress}/token_holders_v2/- SDK:
BalanceService.getTokenHoldersV2ForTokenAddress()
Path Parameters
Query Parameters
Response Fields
Item Fields
Pagination Fields
Credit Cost: 0.02 per item
Processing: Realtime
Tip: Estimate your monthly cost for this API using the Pricing Calculator.
Note: 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, at0.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 withpage-size=1000 and step page-number from 0 until pagination.has_more is false:
cURL
Python
JavaScript
TypeScript SDK
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
Passdate (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.
date or block-height for the latest holders.
Track holder count over time
Readtotal_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 asBigInts:
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
balanceandtotal_supplyare 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 asBigInts.contract_decimalsscales a balance for display:balance / 10^contract_decimals.block_heightis the block the list is from. Store it with the data so a figure can be reproduced.updated_atis when the response was generated, andchain_tip_heightthe 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; passno-snapshot=trueto bypass it.pagination:total_countis the number of holders,has_moreisfalseon the last page, andpage-sizeis100(default) or1000.
FAQ
How do I get all holders of a token?
Requestpage-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.
How many holders does a token have?
Readpagination.total_count from any page. One request at the default page size costs at most 2 credits.
How do I get the token holders of a token on Base?
Usebase-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.
Can I get a token’s holders at a past block or date?
Yes, on the Foundational chains: passblock-height or date. On other chains those params return a 400. Token Holders chain support lists both groups.
How do I get the top holders of a token?
Fetch every holder, then sort bybalance (as BigInt) and take the first N. See Find the top holders and whales.
Which chains does the Token Holders API support?
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.Is the Token Holders API free?
It is on every plan, including the 14-day free trial with 25,000 credits: enough for 1,250,000 holders at0.02 credits each.
Does it work for NFTs?
Yes. Pass an ERC-721 collection’s contract address to get every address that holds at least one token in the collection.Related
- Token Holders chain support: which chains serve latest and past holders.
- Measuring token holder concentration (Gini & HHI): compute concentration metrics from a full holder list.
- Token Holders API overview: what you can build, pricing and how GoldRush compares.
Enhanced Bitcoin Support
GoldRush offers production-grade Bitcoin data for wallets, tax tools, explorers, and analytics. We operate dedicated Bitcoin node infrastructure and index the chain from the genesis block to ensure complete, accurate balance and transaction history.Key Concepts
- Hierarchical Deterministic (HD) Wallet refers to a wallet that generates all of its keys and addresses from a single source (e.g. a seed phrase). These keys and addresses can be organized into a tree (hierarchial) and are always generated the same way (deterministic).
- Extended public keys (e.g.,
xpub...,ypub...,zpub...) are HD address-level public keys used to derive many child receive addresses. - Non-HD addresses or child addresses follow different standards:
- BIP44 Legacy, P2PKH: addresses typically start with
1, derived pathm/44'/0'/... - BIP49 Nested SegWit, P2SH-P2WPKH: addresses typically start with
3, derived pathm/49'/0'/... - BIP84 Native SegWit, P2WPKH/bech32: addresses typically start with
bc1, derived pathm/84'/0'/... - BIP86 Taproot, P2TR: addresses typically start with
bc1p, derived pathm/86'/0'/...
- BIP44 Legacy, P2PKH: addresses typically start with
Capabilities
- Full-chain ingestion: Dedicated node and indexers ingest all Bitcoin transactions from genesis for complete historical coverage.
- Extensive HD wallet derivation scans (gap limit 20): We continue to derive child addresses until encountering 20 consecutive child addresses with zero balance and no transaction history.
- Support multiple child address formats: Includes BIP44 Legacy, BIP49 Nested SegWit, BIP84 Native SegWit.
- Spot and historical balances for non-HD/child addresses: Includes current and historical fiat price conversions.
- Spot balances for derived child addresses from HD wallet addresses (xpub/ypub/zpub): Includes spot balances, fiat prices and 24hr deltas.
- Historical transactions for non-HD addresses: Retrieve time-ordered transactions for a Bitcoin address for statements, tax, and activity feed workflows.