How to get an ETH or ERC-20 balance of an address via API
Updated 2026-11-10
Use when an agent needs the ETH or ERC-20 balance of an address on Ethereum, Base or Robinhood Chain.
From an MCP client, add https://tanod.dev/mcp and call get_balance; the first 10 calls per IP per UTC day are free (shared by all chainpeek reads), then each call is USD 0.002 with x402, no key or signup.
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, base or robinhood; address is the account; token is an optional ERC-20 contract. For many tokens, use the portfolio endpoint.
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"
}An agent wallet has one USDC balance per chain
"The wallet's USDC balance" is really balanceOf on one contract on one chain. An agent paid in USDC on Base and on Ethereum holds two separate balances, and a low-balance alert that reads only one of them fires late or never. Ask each chain for its own USDC contract and add the results. Native USDC is 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 on Base and 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum. Set the alert on each chain's balance as well as on the total, because funds on one chain cannot pay gas or fees on the other.
A=0xYourAgentWallet
for pair in base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48; do
curl -s -X POST https://tanod.dev/v1/chain/balance \
-H 'Content-Type: application/json' -H 'X-Tanod-Free: 1' \
-d "{\"chain\": \"${pair%%:*}\", \"address\": \"$A\", \"token\": \"${pair#*:}\"}" \
| jq -r '"\(.chain) \(.symbol) \(.formatted)"'
doneLimits 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, Polygon, Solana, BNB Chain or Arbitrum 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.
Paying by card instead? The same balance read runs as an Apify actor, EVM Wallet & Token Balances (tanod/evm-wallet-reader), billed through your Apify account at USD 0.002 per wallet and chain; give it a list and collect the results from the run's storage.
All endpoints →Use it from Claude without writing code: in claude.ai or Claude Desktop, add https://tanod.dev/mcp/chain?via=native-erc20-balance-api as a custom connector (steps), then ask in plain words, for example "What is the ETH balance of vitalik.eth's address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 on Ethereum?" The free daily allowance is applied automatically over MCP. Beyond it a call needs an x402 payment, which these clients can make.
Related guides: Solana balances, tokens and transactions via API, 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.