How to Programmatically Check an Ethereum Account Balance

If you're developing a decentralized application or working with the Ethereum blockchain, knowing how to programmatically check an account balance is a fundamental skill. Whether you're querying the balance of Ether (ETH) or other ERC-20 tokens, there are several methods available to developers. This guide covers the primary techniques, from using web interfaces to executing code within smart contracts.

Using Web Interfaces for Balance Checks

For a quick, non-programmatic check, you can use blockchain explorers. These websites provide a user-friendly interface to look up any Ethereum address.

Popular options include Etherscan and Etherchain. Simply enter the public address into the search bar, and the site will display the current balance of Ether and often a list of tokens held by that address. This method is ideal for quick, one-off queries but is not suitable for automated or application-integrated tasks.

Querying Balances Using Node Client Tools

For developers, interacting directly with an Ethereum node is the standard approach. This can be done using the command-line interfaces (CLIs) provided by node client software like Geth (Go-Ethereum) or other similar tools.

The JavaScript API and web3.js

These CLI tools often provide a JavaScript runtime environment where you can use the web3.js library. This library is the primary JavaScript SDK for interacting with the Ethereum blockchain.

A basic command to check the balance of your default account (the coinbase) looks like this:

web3.fromWei(eth.getBalance(eth.coinbase));

In this context, eth is typically a shortcut for web3.eth that is automatically available in environments like the Geth console. The more explicit and complete version of the command is:

web3.fromWei(web3.eth.getBalance(web3.eth.coinbase));

The web3.eth.getBalance() function returns the balance in Wei, the smallest denomination of Ether. The web3.fromWei() utility function is then used to convert this large number into a more readable value in Ether.

Checking Multiple Account Balances

You are not limited to checking just the default account. All balance information on Ethereum is public. You can check the balance of any account by specifying its public address:

web3.fromWei(web3.eth.getBalance('0x2910543af39aba0cd09dbb2d50200b3e800a63d2'));

If your node manages multiple accounts, you can access them through the web3.eth.accounts array. To check all of them at once, you can use a simple function:

function checkAllBalances() {
 var i = 0;
 web3.eth.accounts.forEach(function(account) {
 var balance = web3.fromWei(web3.eth.getBalance(account), "ether");
 console.log("Account " + i + ": " + account + " | Balance: " + balance + " ETH");
 i++;
 });
};
checkAllBalances();

This script iterates through each account in the accounts array, fetches its balance, converts it to Ether, and prints the result to the console. For a comprehensive suite of development tools that simplify these tasks, you can explore more strategies.

Checking Balances from Within a Smart Contract

Sometimes, you may need a smart contract itself to check the balance of an address. The Solidity programming language makes this straightforward.

Every address in Ethereum has a .balance property that returns its balance in Wei. This property can be accessed within your contract's functions.

Consider this simple example contract:

pragma solidity ^0.8.0;

contract BalanceChecker {
    address public owner;

    constructor() {
        owner = msg.sender;
    }

    function getOwnerBalance() public view returns (uint256) {
        return owner.balance;
    }

    function getAddressBalance(address _addr) public view returns (uint256) {
        return _addr.balance;
    }
}

This contract does two things:

The getOwnerBalance function returns the balance of the contract's owner (the address that deployed it).
The getAddressBalance function takes any address as an input and returns its balance.

It is crucial to remember that the .balance property returns a value in Wei. Any subsequent logic in your dApp that uses this value must account for this denomination.

Frequently Asked Questions

What is the difference between checking ETH and token balances?

The methods above are for checking the native Ether (ETH) balance of an address. ERC-20 tokens are smart contracts, and checking their balance requires interacting with the specific token's contract using its ABI to call the balanceOf(address) function.

Why is my balance returned in Wei?

Ethereum operations use Wei to avoid floating-point numbers, which can introduce errors in financial calculations. You must convert Wei to Ether for display purposes, using a function like web3.fromWei() or by dividing by 10^18 in your code.

Can I check the balance of any address?

Yes. Balance information for any Ethereum address is public and accessible on the blockchain. You only need the public address to query its ETH balance.

What is web3.js?

web3.js is a popular JavaScript library that provides a convenient interface for interacting with the Ethereum blockchain. It allows you to connect to a node, send transactions, read data, and interact with smart contracts.

My getBalance call is returning zero. What's wrong?

First, confirm you are connected to the mainnet and not a test network. Second, double-check that the address you are querying is correct and has been used in a transaction, which ensures it is active on the blockchain.

Is it possible to get historical balance information?

The standard getBalance function only returns the current balance. To get a balance from a past block, you need to use archival node services or blockchain explorers that support historical state queries, which can be more complex. To view real-time tools that might offer this functionality, consult advanced platform features.