Skip to main content

v1/{chainName}/tokens/{tokenAddress}/token_holders_v2/ REST API Endpoint

Commonly used to get a list of all the token holders for a specified ERC20 or ERC721 token. Returns historic token holders when block-height is set (defaults to latest). Useful for building pie charts of token holders.

Updated on
Jan 09, 2025

v1/{chainName}/tokens/{tokenAddress}/token_holders_v2/ REST API Endpoint

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

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
The 0-indexed page number to begin pagination

Returns

data
object
The response data containing following fields:
updated_at
string
The timestamp when the data was last updated
chain_id
integer
The ID of the blockchain network
chain_name
string
The name of the blockchain network
items
array
An array containing token holder details
contract_decimals
integer
The number of decimals used by the token contract
contract_name
string
The name of the token contract
contract_ticker_symbol
string
The ticker symbol of the token contract
contract_address
string
The address of the token contract
supports_erc
array
An array of strings indicating the ERC standards supported by the token
logo_url
string
URL of the token's logo
address
string
The address of the token holder
balance
string
The balance of the token held by the address
total_supply
string
The total supply of the token
block_height
integer
The block height at which the token holder data was retrieved
pagination
object
Pagination metadata for navigating through the data
has_more
boolean
Indicates if more pages are available
page_number
integer
The current page number
page_size
integer
The number of items per page
total_count
integer
The total number of items available
error
boolean
Indicates whether an error occurred
error_message
string
The error message if an error occurred, or null otherwise
error_code
string
The error code if an error occurred, or null otherwise
Request
1
curl --location 'https://api.covalenthq.com/v1/eth-mainnet/tokens/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/token_holders_v2/' \
2
--header 'Content-Type: application/json' \
3
--header 'Authorization: Bearer YOUR_API_KEY'
Don't have an account yet?
Create your QuickNode endpoint in seconds and start building
Get started for free