How to get changes in token holders between two blocks heights via Covalent API

4 min readApr 25, 2021


In this quick tutorial, I’ll show you how to get a wide variety of data from the blockchain network using the Covalent API. How to get your own Covalent API for this actions, what information can be extracted using the covalent API in Covalent Docs, and much more.

Before you start working with the Covalent API in Covalent Docs, you need to get your API key. To get it, you need to go to and register your account.

After completing the quick registration procedure, you will be able to receive your API key. It will look like this ( I hid the last few characters of my key because I’m greedy):

So now that you have obtained the required API key, you can start working in Covalent Docs.

Then I recommend that you familiarize yourself with the Overview tab to understand exactly what Covalent Docs are and how teams work. Then, by going to the Changelog tab,
You need to enter your API key before starting to get the information correctly. Some commands from ClassA can work without obtaining an API key, such as Get token balances for address and Get historical portfolio value over time.

Having done all the preparatory steps before working with the API, you can start working with more interesting options. In this article, we will cover the section Get changes in token holders between two blocks heights:

Get changes in token holders between two block heights real-time

GET /v1/{chain_id}/tokens/{address}/token_holders_changes/

Get token balance changes for token holders between starting-block and ending-block Return a paginated list of token holders and their current/historical balances. If ending-block is omitted, the latest block is used.


  1. chain_id — in this field you need to enter the network in which you are going to work. Currently supports 1 for Ethereum Mainnet, 137 for Polygon/Matic Mainnet, 80001 for Polygon/Matic Mumbai Testnet, 56 for Binance Smart Chain, 43114 for Avalanche C-Chain Mainnet, 43113 for Fuji C-Chain Testnet, and 250 for Fantom Opera Mainnet.
  2. address — in this field you need to enter the NFT contract address


  1. starting-block — in this field you need to enter the starting block to define the block range.
  2. ending-block — in this field you need to enter the ending block to define a block range.
  3. page-number — in this field you need to enter the specific page to be returned.
  4. page-size — in this field you need to enter the number of results per page.
  5. format — in this field you need to enter the format of response. CSV or JSON.

As an example I decided to consider changes in YFI token holders between block 12200000 and 12283704. So I filled in the fields with the following data:

chain_id — 1

address — 0x0bc529c00c6401aef6d220be8c6ea1667f6ad93e

starting-block — 12200000

ending-block — 12283704

page-number —1

page-size — 10

format — JSON

And then click TRY button:

If everything was entered correctly, you will receive the following response:

You can find out exactly how to read the answer received a little below in the MODEL tab. this section of Covalent API:

There is not very big table with a description of all possible commands, as well as an example of a response in the tab EXAMPLE. You should explore these two tabs for a deeper understanding and quality data analytics.

In this example, thanks to this section of the Covalent API and the knowledge of the commands we can determine how the balance of the selected tokens changed among holders for a certain amount of time (blocks). And also we can see the difference:

This function of the Covalent API helps to work with a large volume of blockchain data and we can determine how the holders of a particular token behaved over a selected period of time, for example. It is very useful feature, but how exactly you will use it depends only on your skills and imagination!