getTokenHolders

Get all token holders for the given ERC20 token contract address ordered descending by balance (supports snapshotting at a specific block number)

The getTokenHolders method is a powerful tool for retrieving information about token holders for a specific ERC20 token contract address. This method provides a comprehensive list of token holders, ordered in descending order by their token balances, allowing you to identify the largest holders at the top of the list. Additionally, it supports filtering at a specific block number, enabling you to explore historical token holder data.

How to use getTokenHolders method ?

Below, you'll find an in-depth guide that provides a comprehensive explanation of how to utilize the getTokenHolders Builder API method effectively using Blast.

Parameters

Below, you can find the query parameters accepted by the method.

Parameter	Type	Description
contractAddress	string	The token contract address
blockNumber	string	All holders at a specified block height
pageSize	integer	Number of records to be retrieved on one page
pageKey	string	Key used to get the next page of results

Returns

Discover an insightful explanation of the returned parameters here, offering a deep understanding of their significance and implications.

Parameter	Type	Description
contractAddress	string	The token contract address
contractDecimals	string	Token decimals specified in the contract
contractName	string	The name of the token
contractSymbols	string	The ticker of the token
count	integer	The number of holders
nextPageKey	string	Key to get the next page of results
tokenHolders	array	The array of Token Holders details
walletAddress	string	The wallet address of the holder
balance	string	The token balance of the holder

Example Request and Result for getTokenHolders

In this section, we provide an illustrative example of a request made to retrieve token holders' data using the getTokenHolders method. This method allows you to efficiently access and retrieve information about token holders for a specific ERC20 token contract address. You can also specify additional parameters such as the block height for snapshotting. The example request demonstrates how to make a request to fetch token holders' data, while the result showcases the expected response format. By following this example, you can gain insights into how to use the getTokenHolders method effectively and integrate it into your blockchain analysis or application development workflows.

The example in this section uses a non-existing project id.

Make sure you replace it with your Starknet endpoint when issuing the Builder API calls.

Don't have a project id? Here's a straightforward guide on how to obtain one!

Returns the token holders for the given ERC20 token contract address

GET https://starknet-mainnet.blastapi.io/<project_id>/builder/getTokenHolders

Query Parameters

Name	Type	Description
contractAddress*	String	0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7

200: OK

{
  "contractAddress": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
  "contractDecimals": "18",
  "contractName": "Ether",
  "contractSymbol": "ETH",
  "count": 100,
  "nextPageKey": "ZDM4N2UzMmVhOWExOjE3MDU5NjIwNDM6OTAwMDE2ODE1NDU2OTQ3MTE4OToweDAzMDk0MWZmYTg4NzRlYTdjNWM4Yzk0M2ZhNTBmOTE5M2QzNzQ4Y2MyMTliNjdmZGRhMzM0YjM3YmU4NTk1NWU6NTE1MTczOjE4OkV0aGVyOkVUSA",
  "tokenHolders": [
    {
      "walletAddress": "0x0179aa76deab144ef996ddda6b37f9fb259c291f7b79f4e0fca63e64228a53f5",
      "balance": "4224703087955615747118"
    },
    {
      "walletAddress": "0x03a20d4f7b4229e7c4863dab158b4d076d7f454b893d90a62011882dc4caca2a",
      "balance": "3956581557656696333533"
    },
   ... ...
    {
      "walletAddress": "0x030941ffa8874ea7c5c8c943fa50f9193d3748cc219b67fdda334b37be85955e",
      "balance": "9000168154569471189"
    }
  ]
}

curl --location 'https://starknet-mainnet.blastapi.io/<project-id>/builder/getTokenHolders?contractAddress=0xF411903cbC70a74d22900a5DE66A2dda66507255'