Get Balance
Read native and token balances for a connected wallet.
Installs viem, @solana/web3.js
"use client";
import { useAccount, useBalance, useReadContract } from "wagmi";
import { formatUnits } from "viem";
import { useState } from "react";
// ★ ERC-20 balanceOf ABI — the only function you need to read a token balance
const erc20BalanceOfAbi = [
{
name: "balanceOf",
type: "function",
stateMutability: "view",
inputs: [{ name: "account", type: "address" }],
outputs: [{ name: "balance", type: "uint256" }],
},
] as const;
export function GetNativeBalance() {
const { address } = useAccount();
const { data: balance, isLoading } = useBalance({ address });
if (isLoading) return <p>Loading...</p>;
return (
<div>
<h2>Native Balance</h2>
<p>{balance?.formatted} {balance?.symbol}</p>
</div>
);
}
export function GetTokenBalance() {
const { address } = useAccount();
const [tokenAddress, setTokenAddress] = useState("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"); // USDC on Ethereum
const [decimals, setDecimals] = useState("6");
const { data: balance, isLoading } = useReadContract({
address: tokenAddress as `0x${string}`,
abi: erc20BalanceOfAbi,
functionName: "balanceOf",
args: address ? [address] : undefined,
});
return (
<div>
<h2>ERC-20 Token Balance</h2>
<input
value={tokenAddress}
onChange={(e) => setTokenAddress(e.target.value)}
placeholder="Token contract address"
/>
<input
value={decimals}
onChange={(e) => setDecimals(e.target.value)}
placeholder="Decimals (e.g., 6)"
/>
{isLoading && <p>Loading...</p>}
{balance !== undefined && (
<p>Balance: {formatUnits(balance, Number(decimals))} (raw: {balance.toString()})</p>
)}
</div>
);
}Get Balance — Learn
How balances work on-chain
EVM: State in the contract
On EVM chains, token balances are stored inside each token's smart contract as a mapping:
// Inside the USDC contract
mapping(address => uint256) private _balances;
To read your USDC balance, you call balanceOf(yourAddress) on the USDC contract. This is a "view" function — it reads state without modifying it, so it costs no gas.
Native ETH balance is different — it's tracked by the chain itself, not a contract. Every address has a native balance managed by the protocol.
Solana: Accounts hold everything
On Solana, everything is an account. Your SOL balance is stored in your main account. But token balances are stored in separate "token accounts":
Your wallet (main account)
├── SOL balance: stored here
├── USDC token account: a separate account holding your USDC
├── BONK token account: another separate account
└── ... one account per token you hold
Each token account is owned by the SPL Token program and associated with both your wallet and the token's "mint" (the token's identifier).
Associated Token Accounts (ATAs)
The "Associated Token Account" is a deterministic address derived from your wallet + the token mint. It's the standard way to find someone's token account:
ATA = deriveAddress(wallet, tokenMint, TOKEN_PROGRAM_ID)
If the ATA doesn't exist, it means the wallet has never held that token. You can create it (costs ~0.002 SOL rent) when sending tokens to someone for the first time.
The decimals problem
Blockchains don't have floating-point numbers. Balances are stored as integers.
On-chain: 1000000 (integer)
Display: 1.000000 USDC (formatted with 6 decimals)
Every token defines its own decimal precision:
- ETH: 18 decimals → 1 ETH = 10^18 wei
- SOL: 9 decimals → 1 SOL = 10^9 lamports
- USDC: 6 decimals on both EVM and Solana
- WBTC: 8 decimals
Getting decimals wrong is a common source of bugs. Sending 1000000 of a token with 18 decimals sends 0.000000000001 tokens, not 1 million.
Read operations: Free but not instant
Reading balances doesn't cost gas because you're querying an RPC node's cached state, not executing a transaction. But:
- RPC rate limits: Free endpoints (Alchemy, QuickNode) have request limits
- Stale data: The RPC node's state may lag by a few seconds
- Different nodes, different answers: During chain reorgs, different RPC nodes may report different balances briefly