How to Get ERC-20 Token Balance at a Given Block

The token balances for a user address is a critical data point for almost any web3 use case - be it DeFi platforms, wallets, analytics, exchanges, and many others. A common use case would be displaying the balances as below in your wallet app.

Sample wallet screen displaying coin balances

To fetch this data you have 2 options:

1. Fetch the Transaction History for the token’s contract, for example take USDT, which is millions of records. Then search through for your user’s address among those records (will take hours) and then show that to your user. Not to forget, do this indexing process every second forever to keep it updated for every user.
2. OR just use Alchemy’s getTokenBalances endpoint.

If you’re like most web3 developers, you probably want to go for the second option!

About this Tutorial

We will write a simple script in Node to gets us the balance of USDT for a particular wallet address. We will get the latest balance, the balance at a a particular block (in our case, 1000000), and at a particular human-readable time using Alchemy’s Token API Quickstart.

Creating the Token Balances Script

Step 1: Install Node and npm

In case you haven’t already, install node and npm on your local machine.

Make sure that node is at least v14 or higher by typing the following in your terminal:

$
node -v

Step 2: Create an Alchemy app

In case you haven’t already, sign up for a free Alchemy account.

Alchemy’s account dashboard where developers can create a new app on the Ethereum blockchain.

Next, navigate to the Alchemy Dashboard and create a new app.

Make sure you set the chain to Ethereum and the network to Mainnet.

Once the app is created, click on your app’s View Key button on the dashboard.

Take note of the HTTP URL.

The URL will be in this form: https://eth-mainnet.g.alchemy.com/v2/xxxxxxxxx

You will need this later.

Step 3: Create a node project

Let’s now create an empty repository and install all node dependencies.

To make requests to the Token API, use the Alchemy SDK.

You can also use axios or fetch alternatively.

$
mkdir token-balances && cd token-balances
>
npm init -y
>
npm install --save alchemy-sdk
>
touch main.js

This will create a repository named token-balances that holds all your files and dependencies.

Next, open this repo in your favorite code editor.

We will be writing all our code in the main.js file.

Step 4: Get the latest USDT balance

To get the USDT balance of a particular wallet, we will use the getTokenBalances method.

This method takes in two arguments:

1. DATA: The wallet address whose USDT balance we want to check
2. Array: An array containing the list of token contract addresses we are interested in. In our case, it’s just one address (i.e of USDT).

Add the following code to the main.js file.

1
const { Alchemy, Network, Utils } = require("alchemy-sdk");
2
3
const config = {
4
    apiKey: "<-- ALCHEMY API KEY -->",
5
    network: Network.ETH_MAINNET,
6
};
7
const alchemy = new Alchemy(config);
8
9
const main = async () => {
10
11
    // Wallet address
12
    const walletAddress = "0xef0dcc839c1490cebc7209baa11f46cfe83805ab";
13
14
    // USDT contract address
15
    const contractAddress = "0xdAC17F958D2ee523a2206206994597C13D831ec7";
16
    const numDecimals = 6;
17
18
    // Get latest USDT balance
19
    let balance = await alchemy.core.getTokenBalances(walletAddress, [contractAddress])
20
    balance = balance['tokenBalances'][0]['tokenBalance'];
21
    balance = (parseInt(balance) / 10 ** numDecimals).toFixed(2);
22
    console.log("Balance:", balance, "USDT");
23
};
24
25
const runMain = async () => {
26
    try {
27
        await main();
28
        process.exit(0);
29
    } catch (error) {
30
        console.log(error);
31
        process.exit(1);
32
    }
33
};
34
35
runMain();

You can find the contract address of any token by searching its ticker or name on Etherscan.

In order to format a token into its human-readable format, you simply convert the hexadecimal result received from the API response into a decimal, and then divide by the number of decimal places that that particular token has. USDT, for instance, has 6. You can find out how many decimal places any currency has by reading the decimals value from the contract’s page on Etherscan.

Solidity does not support decimal point numbers. So, If you want an ERC20 token to have the ability to be subdivided with a precision of 2 decimal places, you need to represent 1 token as 100 (set its decimal places to 2). Similarly if I you want an ERC20 token to have the ability to subdivided with a precision of 18 decimal places, you need to represent 1 token as 1000000000000000000 (set its decimal places to 18).

So, the formula for number of tokens becomes:

tokenSupplyWithDecimalZeros = actualTokenSupply * (10 ** decimals)

That is why we need to divide the decimal value by the number of decimal places, to get the actual token value.

Run the script using the following command:

$
node main.js

If all goes well, you should see output that looks something like this:

$
Balance: 61900000.01 USDT

Step 5: Get USDT balance at a particular block

In order to get the balance of a token at a particular block, we need to leverage the eth_call method. This will allow us to query USDT contract’s balanceOf method at a particular block number.

Create a new file called historical_balance.js and add the following code:

1
const { Alchemy, Network, Utils } = require("alchemy-sdk");
2
const ethers = require('ethers');
3
4
const config = {
5
    apiKey: "<-- ALCHEMY API KEY -->",
6
    network: Network.ETH_MAINNET,
7
};
8
const alchemy = new Alchemy(config);
9
10
const main = async () => {
11
12
    // Wallet address
13
    const walletAddress = "0xef0dcc839c1490cebc7209baa11f46cfe83805ab";
14
15
    // USDT contract address
16
    const contractAddress = "0xdAC17F958D2ee523a2206206994597C13D831ec7";
17
    const numDecimals = 6;
18
19
    // Block number
20
    const blockNum = 12026456;
21
22
    // ABI
23
    let abi = [
24
        'function balanceOf(address account)'
25
    ];
26
27
    // Create function call data -- eth_call
28
    let iface = new ethers.utils.Interface(abi)
29
    let data = iface.encodeFunctionData("balanceOf", [walletAddress]);
30
31
    // Get balance at a particular block -- usage of eth_call
32
    let balance = await alchemy.core.call({
33
        to: contractAddress,
34
        data: data,
35
    }, blockNum);
36
37
    balance = (parseInt(balance) / 10 ** numDecimals).toFixed(2);
38
    console.log("Balance:", balance, "USDT");
39
};
40
41
const runMain = async () => {
42
    try {
43
        await main();
44
        process.exit(0);
45
    } catch (error) {
46
        console.log(error);
47
        process.exit(1);
48
    }
49
};
50
51
runMain();

Run this script using:

$
node historical_balance.js

If all goes well, you should see output that looks something like this:

$
Balance: 61933384.84 USDT

Step 6: Get USDT balance at a particular timestamp

The process to get the USDT balance at a particular timestamp is identical to the previous, except that we need to figure out a way to convert a timestamp into a block number.

In order to do this, we will use a library called ethereum-block-by-date.

Install this package by running the following command in your terminal:

$
npm install ethereum-block-by-date

Replace the contents of historical_balance.js with the following:

1
const { Alchemy, Network, Utils } = require("alchemy-sdk");
2
const ethers = require('ethers');
3
const EthDater = require('ethereum-block-by-date');
4
5
const config = {
6
    apiKey: "<-- ALCHEMY API KEY -->",
7
    network: Network.ETH_MAINNET,
8
};
9
const alchemy = new Alchemy(config);
10
11
const dater = new EthDater(
12
    alchemy.core // Ethers provider, required.
13
);
14
15
const main = async () => {
16
17
    // Wallet address
18
    const walletAddress = "0xef0dcc839c1490cebc7209baa11f46cfe83805ab";
19
20
    // USDT contract address
21
    const contractAddress = "0xdAC17F958D2ee523a2206206994597C13D831ec7";
22
    const numDecimals = 6;
23
24
    // Set timestamp
25
    const timestamp = '2021-02-20T13:20:40Z';
26
27
    // Get blocknumber 
28
    let block = await dater.getDate(timestamp);
29
    let blockNum = block['block']
30
31
    // ABI
32
    let abi = [
33
        'function balanceOf(address account)'
34
    ];
35
36
    // Create function call data
37
    let iface = new ethers.utils.Interface(abi)
38
    let data = iface.encodeFunctionData("balanceOf", [walletAddress]);
39
40
    // Get balance at a particular block -- usage of eth_call
41
    let balance = await alchemy.core.call({
42
        to: contractAddress,
43
        data: data,
44
    }, blockNum);
45
46
    balance = (parseInt(balance) / 10 ** numDecimals).toFixed(2);
47
    console.log("Balance:", balance, "USDT");
48
};
49
50
const runMain = async () => {
51
    try {
52
        await main();
53
        process.exit(0);
54
    } catch (error) {
55
        console.log(error);
56
        process.exit(1);
57
    }
58
};
59
60
runMain();

Running the same command as in step 5 should produce the same output.

$
Balance: 61933384.84 USDT

Conclusion

Congratulations! You now know how to use the Alchemy Ethereum API and Token API to get the token balance of a wallet at present, a particular block height or timestamp.

If you enjoyed this tutorial on how to get ETH balance at a point in time, give us a tweet @Alchemy.

Don’t forget to join our Discord server to meet other blockchain devs, builders, and entrepreneurs.

Ready to start using the Alchemy Token API?

Create a free Alchemy account and share your project with us!