What's the best way to get the list of token(ERC20) holders with their balance at a specific time? Thank you.

  • 3
    Getting the list is hard. (Easiest way is probably to process all the logs for the contract looking for Transfer events.) Getting the balance is just a matter of providing a block number with the eth_call call. (I believe this is available via web3.js too.)
    – user19510
    Commented Jan 15, 2018 at 1:30
  • 1
    Indeed, you can provide a block number to any method call in web3.js. In this case, you'll be calling balanceOf on the token contract.
    – user19510
    Commented Jan 15, 2018 at 1:32

4 Answers 4


ERC-20 tokens do not maintain an iterable list of current token holders, the used mapping type allows you only to check for a known address - balance. To get a list of all token holders, you need to process this offline and build it yourself from blockchain data.

I have created a standalone tool which collects ERC-20 token holders and transactions to SQLite database

  • Take a token contract address

  • Iterate over all Transfer events for token using eth_getLogs JSON-RPC API

  • Build a local database of these events

  • Allow you to use SQL to query any account balance on any point of time (block num) by just running a SUM() of account balances changes between blocks 1 - end block.

You can find the command line application execution example how to build the token holder database here

The core Python logic is here.

There are some quirks here and there: for example detecting mint / creation event for some tokens is not straightforward. Thus, you will may negative balance on the account receiving initial total supply if you rely on Transfer event only.

  • You can view the list of the particular token holders on etherscan under the Holders tab for example here etherscan.io/token/…. Also, if you view the Analytics tab for its contract you will find useful information for the balance during the contract's start date to present like here etherscan.io/address/…
    – mzaidi
    Commented Feb 6, 2020 at 6:57
  • Also, Etherscan offers balance checker tool. You can access it by going to contract -> more info (displayed on the right) -> select check previous balance by clicking on the 3 dots and then select the date for checking the balance. For example here etherscan.io/…. Hope that helps.
    – mzaidi
    Commented Feb 6, 2020 at 9:52
  • Now there is an example available in web3.py documentation. Commented Apr 20, 2021 at 8:17
  • is there a similar set of libs to do this with javascript?
    – dcsan
    Commented Aug 21, 2021 at 15:56
  • 1
    Seems like the link broke (docs.tokenmarket.net/erc-20-holders.html).
    – merc1er
    Commented Aug 29, 2022 at 5:43

This method does not always work, however it doesn't require writing code.

  1. Go to the etherscan page of the token you want to get the token holders from. (ie https://etherscan.io/token/0xdac17f958d2ee523a2206206994597c13d831ec7#balances)

  2. Click on the little graph icon under the analytics column of the holders table.

  3. The new page that pops up has a graph of the token balance over time. Check if it held the token at the specific time that you wanted.

This won't be too useful if the token has many holders, however, for tokens with less holders or if you just need one address that held the token at a specific time for testing, this works great!


Alternatively, you can use blockchain data APIs that have indexed data. Bitquery for example, has a token holder API that gives you the exact count and details of token holders at a point in time.


Full disclosure, I work at Bitquery


I think the easiest way to get this done, is to use The Graph.

Then in a similar way to @mikko-ohtamaa's answer store the Transfer events.

You can get it done with no code, if using the graph as it will generate all code.

So in sort, follow their guide https://thegraph.com/docs/en/quick-start/

After the graph is deployed just do a simple graphQL query and done

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.