Read an ERC-20 token balance for up to 500 wallet addresses in a SINGLE call.
Doing this yourself means issuing hundreds of eth_call requests, batching them, handling per-provider rate limits and partial failures, then scaling raw integers by token decimals. This does all of that and returns clean, ready-to-use numbers plus the block height the snapshot was taken at.
Supported chains: base (default), ethereum, optimism, arbitrum, polygon. Defaults to canonical USDC on the selected chain when no token is given.
When to use: portfolio or treasury roll-ups, airdrop and eligibility checks, holder analysis, reconciling a list of wallets.
When NOT to use: you need native ETH balances (this reads ERC-20 contracts) or balances at a historical block.
Args:
- addresses (string[], required): 1-500 EVM addresses. Duplicates removed, order preserved.
- chain (string, optional, default "base"): base | ethereum | optimism | arbitrum | polygon.
- token (string, optional): ERC-20 contract address. Defaults to USDC on the chosen chain.
Returns structuredContent:
{
"chain": "base", "chainId": 8453, "blockNumber": 34567890,
"token": { "address": "0x8335...", "symbol": "USDC", "decimals": 6 },
"requested": 3, "queried": 3, "failed": 0,
"totalBalance": "1234.56",
"holders": [ { "address": "0x...", "raw": "1234560000", "balance": "1234.56" } ]
}
A read that fails at the provider returns null for that address rather than a misleading 0, and
"failed" counts them. If every read fails the call errors and is not billed.