How to Get Token Holder Data for ERC-20, ERC-721 and ERC-1155s

What are Token Holders

In Web3, token holders are individuals or entities that own digital tokens, which are essentially blocks of code in the form of smart contracts deployed on blockchains. Tokens contracts typically follow a standard, and the most common standards come from the Ethereum ecosystem:

1. ERC-20: This is the most widely used token standard in the Ethereum ecosystem. It defines a set of rules for creating fungible tokens, meaning each token is interchangeable with another token of the same type. ERC-20 tokens can represent fiat currencies (e.g. USD stablecoins), assets, lottery tickets, votes and more. ERC-20 tokens make up the backbone of decentralized finance (DeFi). An example of an ERC-20 token is UNI, the token that powers Uniswap.

2. ERC-721: This token standard is used for creating non-fungible tokens (NFTs). NFTs are unique digital assets representing anything from digital art to in-game items. An example of an ERC-721 token contract is the Bored Ape Yacht Club NFT collection.

3. ERC-1155: This token standard allows for the creation of both fungible and non-fungible tokens on the Ethereum network. It is designed to be more efficient than other token standards, allowing multiple token types to be created within a single smart contract. ERC-1155 allows for dynamic NFTs, which are commonly used by gaming platforms like The Sandbox.

Token holders are an essential part of the Web3 ecosystem, as they are often the primary stakeholders in a project or community. They may have voting rights or other privileges that give them a say in the direction and governance of the project and may also receive rewards or incentives based on their participation or contributions.

This guide will show how you can find a list of token holders for any ERC-20, ERC-721 or ERC-1155 token using the Covalent API!

Use Cases for Developers

There are many key use cases for developers building with token holder data, such as:

1. Market research: Analyze the current and historical behavior and demographics of a project's user base.

2. Governance tools: Determine voting rights based on the user's number of tokens. Verify a holder’s eligibility to participate in voting.

3. Airdrops: Distribute airdrops and rewards to users based on their token holdings. Covalent’s token holders endpoint allows you to get historical token holders snapshots which is useful if there’s a cutoff date to receive an airdrop.

4. Decentralized Exchanges (DEXs): Facilitate token swaps or other types of trades between users.

5. Compliance: Track the flow of tokens since creation and verify the identities of token holders, preventing financial crimes.

User Spotlight

The following are just a few examples of projects currently using the Covalent API to track token holders:

Getting Token Holders Data

Step 1: Sign up or sign in

Sign up for an API key if you haven’t gotten one yet.

Step 2: Find the API Reference

Once signed up, navigate to the API Reference page. This is where you can try out all the Covalent endpoints live.

Step 3: Find the token holders endpoint

Where you see the list of API endpoints, go to CLASS A > Balances. The endpoint we are interested in is:

• Get token holders as of any block height (V2)

This endpoint resolves ERC-20, ERC-721, and ERC-1155 tokens.

Step 4: Construct your API call

To use this endpoint, we must know the chainName (the underlying blockchain for the token contract, e.g. eth-mainnet) and the tokenAddress (the contract address for the requested token). Optionally, we can specify the block-height, which allows us to set a date, and the page-number, which enables us to paginate through the endpoint response. The page size is fixed at 100 items, so the page number parameter is necessary for any tokens with over 100 holders to capture the complete list.

Step 5: Choose a token contract

Let’s get the token holders for the Boys Club Zaddy NFT, a token that represents the support of the Boys Club community and gives holders access to fun social events. From Opensea or Etherscan, we can get the contract address 0x8158bDD0286e5B2384F2CF4Eba94e741295D437E.

Step 6: Hit Run

Input the tokenAddress and specify the chainName as eth-mainnet, then hit Run. Here is a snippet of the response you will see:

json

{
  "data": {
    "updated_at": "2023-04-04T17:28:37.934759315Z",
    "chain_id": 1,
    "chain_name": "eth-mainnet",
    "items": [
      {
        "contract_decimals": 0,
        "contract_name": "BoysClub",
        "contract_ticker_symbol": "BC",
        "contract_address": "0x8158bdd0286e5b2384f2cf4eba94e741295d437e",
        "supports_erc": [
          "erc20"
        ],
        "logo_url": "https://logos.covalenthq.com/tokens/1/0x8158bdd0286e5b2384f2cf4eba94e741295d437e.png",
        "address": "0x3bcd745dcb84834c7cb7ef0dadaa88d77018bf43",
        "balance": "306",
        "total_supply": "1955",
        "block_height": 16976991
      },
      {
        "contract_decimals": 0,
        "contract_name": "BoysClub",
        "contract_ticker_symbol": "BC",
        "contract_address": "0x8158bdd0286e5b2384f2cf4eba94e741295d437e",
        "supports_erc": [
          "erc20"
        ],
        "logo_url": "https://logos.covalenthq.com/tokens/1/0x8158bdd0286e5b2384f2cf4eba94e741295d437e.png",
        "address": "0x6ecb541f43e8af92f3d0df0acf1ac51dc9f3bc83",
        "balance": "100",
        "total_supply": "1955",
        "block_height": 16976991
      },
...
}

This response contains the address, which is the wallet address of the token holder, as well as their balance, which is how many tokens they hold in this collection. Recall that the page size is fixed at 100 items, which only returns 100 of the total number of holders. The page number starts at 0 (the current API response), so to get the next page of results, we should input the page-number as 1.

Note that you can see the current page number as well as the total_count of holders at the end of the response. This is useful for gauging the distribution of token holders for a project and analyzing the change in holders through time.

json

"pagination": {
	"has_more": true,
	"page_number": 0,
	"page_size": 100,
	"total_count": 775
}

We can cross reference the total count of holders with Etherscan or other block explorers for accuracy.

Sample Code

Here is an example of Node.js code that you can use to iterate through all the possible pages and collect the complete list of token holders:

JavaScript

// Define the endpoint URL and parameters
const url = 'https://api.covalenthq.com/v1/eth-mainnet/tokens/0x8158bDD0286e5B2384F2CF4Eba94e741295D437E/token_holders_v2/';
const params = { 'key': 'your_API_key', 'page-number': 0 };

// Make an initial request to get the first page of results
fetch(`${url}?${new URLSearchParams(params)}`)
  .then(response => response.json())
  .then(result => {
    // Extract the total number of pages from the response
    const num_pages = Math.floor(result.data.pagination.total_count/result.data.pagination.page_size);
    console.log(num_pages);

    // Create an empty array to store the token holders
    let token_holders = [];

    // Iterate through all the pages of results and append the token holders to the array
    for (let page = 0; page < num_pages; page++) {
      params['page-number'] = page;
      fetch(`${url}?${new URLSearchParams(params)}`)
        .then(response => response.json())
        .then(result => {
          token_holders = token_holders.concat(result.data.items);

          // Print the list of token holders on the last page
          if (page === num_pages - 1) {
            console.log(token_holders);
          }
        })
        .catch(error => console.log(error));
    }
  })
  .catch(error => console.log(error));

This code example combines the results from all fetched token holder pages into a single array. Remember to replace your_API_key with your Covalent API key.

Conclusion

Congratulations! You made it to the end of the guide! Now that you've learned how to find token holders for any ERC-20, ERC-721 or ERC-1155 token using the Covalent API, you are ready to dive deep into the Web3 world and build amazing decentralized applications. Whether you're a developer, investor or just curious about crypto, keep exploring and learning! Check out Covalent’s other guides to level up your skills.