Skip to main content

Balance Endpoints

Bitcoin Balance API

Operation Identity:
  • Operation ID: getBitcoinBalanceForWalletAddress
  • GET /v1/btc-mainnet/address/{walletAddress}/balances_v2/
  • SDK: BitcoinService.getBitcoinNonHdWalletBalances()
Role: specialized | Credit Cost: 1 per call | API Type: REST Chains: btc-mainnet

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()
Role: specialized | Credit Cost: 0.1 per item | API Type: REST Use Cases: wallets, accounting-tax-reporting, portfolio-tracking Chains: btc-mainnet

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()
Role: primary | Credit Cost: 0.05 per item | API Type: REST Chains: All supported chains

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()
Role: specialized | Credit Cost: 1 per call | API Type: REST Use Cases: accounting-tax-reporting, audit-compliance-forensics, portfolio-tracking Chains: btc-mainnet

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()
Role: primary | Credit Cost: 2 per 30 days | API Type: REST Use Cases: portfolio-tracking, accounting-tax-reporting Chains: All supported chains

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()
Role: specialized | Credit Cost: 1 per call | API Type: REST Chains: eth-mainnet, matic-mainnet, bsc-mainnet, base-mainnet, optimism-mainnet, gnosis-mainnet

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()
Role: primary | Credit Cost: 0.5 per call | API Type: REST Use Cases: wallets, accounting-tax-reporting, portfolio-tracking Chains: All supported chains

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()
Role: primary | Credit Cost: 1 per call | API Type: REST Use Cases: wallets, portfolio-tracking, accounting-tax-reporting Chains: All supported chains

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.
Understanding Web3 Wallets with GoldRush How to Get Bitcoin Balances and Transactions Comparing GoldRush’s Token Balances API to RPC Providers

Token Holders API

Operation Identity:
  • Operation ID: getTokenHoldersV2ForTokenAddress
  • GET /v1/{chainName}/tokens/{tokenAddress}/token_holders_v2/
  • SDK: BalanceService.getTokenHoldersV2ForTokenAddress()
Role: specialized | Credit Cost: 0.02 per item | API Type: REST Chains: eth-mainnet, matic-mainnet, bsc-mainnet, base-mainnet, optimism-mainnet, gnosis-mainnet, arbitrum-mainnet, linea-mainnet, mantle-mainnet, plasma-mainnet (+6 more)

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, 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:
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

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

How do I get all holders of a token?

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.

How many holders does a token have?

Read pagination.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?

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.

Can I get a token’s holders at a past block or date?

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.

How do I get the top holders of a token?

Fetch every holder, then sort by balance (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 at 0.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.
  • 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 path m/44'/0'/...
    • BIP49 Nested SegWit, P2SH-P2WPKH: addresses typically start with 3, derived path m/49'/0'/...
    • BIP84 Native SegWit, P2WPKH/bech32: addresses typically start with bc1, derived path m/84'/0'/...
    • BIP86 Taproot, P2TR: addresses typically start with bc1p, derived path m/86'/0'/...
For an excellent resource to understand HD wallets and derivation paths, see: Learn Me A Bitcoin - HD Wallets

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.

API endpoints