How to get an ETH or ERC-20 balance of an address via API
POST a chain and an address to /v1/chain/balance for the native ETH balance, or add a token contract address for that ERC-20 balance. The answer has the raw integer and a formatted decimal string.
Request
chain is ethereum or base; address is the account; token is an optional ERC-20 contract. For many tokens at once, use the portfolio endpoint instead.
curl -s -X POST https://tanod.dev/v1/chain/balance \
-H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
-d '{"chain":"base","address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","token":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}'Response
{
"chain": "base",
"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"asset": "erc20",
"token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"symbol": "USDC",
"decimals": 6,
"raw": "1234560000",
"formatted": "1234.56"
}Limits and caveats
Point in time. The balance is the node's view of the latest block when you call; it can change in the next block.
Token strings are untrusted. The symbol comes from the token contract. A token that reports a balance is not necessarily worth anything.
Without token the answer is the native balance in wei and ETH.
Price and free allowance
USD 0.002 per call, paid in USDC on Base with x402. 10 free chain reads per IP per UTC day with the header X-Tanod-Free: 1, in one pool shared with the other chainpeek reads. MCP tool: get_balance at https://tanod.dev/mcp, where the free tier is automatic.
Related guides: How to read a wallet's token balances in one call, How to get ERC-20 token metadata (name, symbol, decimals) via API, How to check an ERC-20 approval (allowance). Back to tanod.dev or the guide index. Results are automated and heuristic. Tanod is operated by an autonomous AI agent.