eth_getBalance: Read an Address's ETH Balance

What eth_getBalance does

Balances are part of Ethereum's state, not its history. The node looks up the account in the state trie of the block you named and reports the balance stored there. That applies to externally owned accounts and contracts alike; a contract holding ETH is just an account with a balance, and an address that has never been used returns 0x0 rather than an error.

The block parameter is what makes the method interesting. latest reads the head, finalized reads settled state, a hex block number reads history, and pending reads the node's own projection including transactions sitting in its mempool. Historical reads only work while the node still holds that block's state, which is the practical limit on how far back you can go.

The result is wei: 18 decimal places, routinely a number in the 10^18 range and beyond. It is returned as a hex quantity precisely because it does not fit in a double-precision float, so the value has to be parsed into a big integer and formatted for display rather than read as a number.

Parameters

What it returns

A hex quantity: the balance in wei. 0x0 means the account holds no ETH, whether or not it has ever been used; there is no separate "account does not exist" answer.

Only native ETH is reported. Token balances are contract storage, not account balance, so an address holding a million USDC and no ETH returns 0x0 here.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x5c0a880814b3b96c"
}

0x5c0a880814b3b96c is 6,632,262,969,544,915,308 wei, about 6.63 ETH, as of the block this page was written against. The live call returns whatever the address holds now.

import { JsonRpcProvider, formatEther } from "ethers";

const provider = new JsonRpcProvider("https://ethereum-rpc.publicnode.com");
const address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045";

const wei = await provider.getBalance(address); // bigint, never a number
console.log(formatEther(wei), "ETH");

// same call pinned to a block the node still has state for
const head = await provider.getBlockNumber();
const earlier = await provider.getBalance(address, head - 100);
console.log("delta over 100 blocks:", formatEther(wei - earlier));

Gotchas and common errors

What eth_getBalance costs on BLAZED.sh

eth_getBalance costs 1 credit per call on BLAZED.sh and returns a few dozen bytes, so the over-100KB surcharge never applies. Cost only becomes a topic when the pattern is fan-out: a portfolio tracker checking thousands of addresses every block is issuing thousands of requests, each trivially small. That workload is where a local socket changes the economics, since every one of those calls is a sub-10ms round-trip on the node host instead of a queued request against a shared gateway.

eth_getBalance: frequently asked questions