How to Get ETH Balance at a Point in Time

Perhaps the most important piece of data you can fetch about a wallet on the Ethereum blockchain is its Ether (ETH) balance. This balance is essential for virtually any dapp you build, whether that is a wallet, an NFT marketplace, or a lending protocol.

In this tutorial, we will use eth_getBalance method to fetch the ETH balance of a wallet at a particular block height. We will also implement logic that can convert UTC timestamps into block height, and thus give us the ETH balance at any given point of time.

About this Tutorial

We will write a simple script in Node that gets us the ETH balance of a wallet (say, vitalik.eth) at the latest block and at a particular UTC timestamp using a free Alchemy developer account and the Ethereum API.

Creating the ETH balance 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 network to Mainnet.

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

Take a note of the HTTP URL and API KEY.

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, you can use Viem, Ethers.js, or direct HTTP requests.

You can also use axios or fetch alternatively.

$
mkdir eth-balance && cd eth-balance
>
npm init -y
>
npm install --save viem
>
touch main.js

This will create a repository named eth-balance 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 ETH balance of a wallet

To get ETH balance of a particular wallet, we will use the getBalance method.

This method takes in two arguments:

1. The wallet address for which we want to extract the ETH balance of
2. The block height at which we want to get the ETH balance from. This can be the block number in hexadecimal or one of the predefined block tags.

We are going to set the block parameter to latest to get the most recently observed balance of the wallet.

Add the following code to the main.js file.

1
import { createPublicClient, http, formatEther } from 'viem'
2
import { mainnet } from 'viem/chains'
3
4
const apiKey = "<-- ALCHEMY API KEY -->"
5
6
const client = createPublicClient({
7
  chain: mainnet,
8
  transport: http(`https://eth-mainnet.g.alchemy.com/v2/${apiKey}`)
9
})
10
11
const main = async () => {
12
  // Set wallet address
13
  const address = 'vitalik.eth'
14
15
  // Get balance and format in terms of ETH
16
  const balance = await client.getBalance({
17
    address: address,
18
    blockTag: 'latest'
19
  })
20
21
  const formattedBalance = formatEther(balance)
22
  console.log(`Balance of ${address}: ${formattedBalance} ETH`)
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()

Note that ENS names can be resolved by Viem and Ethers.js. If you’re using direct HTTP requests (Axios/Fetch), you will need to resolve the ENS name to a hexadecimal address first.

Run the script using the following command:

$
node -v

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

$
Balance of vitalik.eth: 1000.046443844809563961 ETH

Step 5: Get ETH balance at a particular timestamp

In order to convert a timestamp into the closest block number, 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 main.js with the following:

1
import { createPublicClient, http, formatEther } from 'viem'
2
import { mainnet } from 'viem/chains'
3
const EthDater = require('ethereum-block-by-date')
4
5
const apiKey = "<-- ALCHEMY API KEY -->"
6
7
const client = createPublicClient({
8
  chain: mainnet,
9
  transport: http(`https://eth-mainnet.g.alchemy.com/v2/${apiKey}`)
10
})
11
12
// Create EthDater instance with a custom provider function
13
const customProvider = {
14
  getBlock: (blockTag) => client.getBlock({ blockTag }),
15
  getBlockNumber: () => client.getBlockNumber()
16
}
17
const dater = new EthDater(customProvider)
18
19
const main = async () => {
20
  // Set wallet address
21
  const address = 'vitalik.eth'
22
23
  // Set timestamp
24
  const timestamp = '2016-07-20T13:20:40Z'
25
26
  // Get blocknumber
27
  let block = await dater.getDate(timestamp)
28
  block = BigInt(block['block'])
29
30
  // Get balance and format in terms of ETH
31
  const balance = await client.getBalance({
32
    address: address,
33
    blockNumber: block
34
  })
35
36
  const formattedBalance = formatEther(balance)
37
  console.log(`Balance of ${address}: ${formattedBalance} ETH`)
38
}
39
40
const runMain = async () => {
41
  try {
42
    await main()
43
    process.exit(0)
44
  } catch (error) {
45
    console.log(error)
46
    process.exit(1)
47
  }
48
}
49
50
runMain()

Run the script using the following command:

$
node main.js

You should see output that looks like this:

$
Balance of vitalik.eth: 215.92554399541193451 ETH

Conclusion

Congratulations! You now know how to use the Alchemy Ethereum API to get the ETH balance of a wallet at a particular time and/or block height.

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

If you have any questions or feedback, please contact us at [email protected] or open a ticket in the dashboard.

Ready to start using the Alchemy NFT API?

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