Get detailed ERC-20 token balances for wallet addresses across 60+ chains via x402 micropayment.
What it does
The Zapper token-balances endpoint returns detailed fungible token holdings for one or more Ethereum-compatible wallet addresses. It is part of Zapper's x402-gated API suite, which covers onchain data across 60+ chains including token prices, NFTs, portfolios, DeFi positions, transactions, and social identity.
For each address you supply, the endpoint returns a paginated list of token balances including token name, symbol, current price, raw balance, USD-denominated balance, and the network the token lives on. You can optionally filter by chain IDs and control the page size (max 20 tokens per call). The response also includes a `totalBalanceUSD` aggregate. Payment is $0.001125 per call, settled in USDC on Base (chain 8453) via the x402 protocol.
The endpoint accepts a POST with a JSON body containing an `addresses` array (required), an optional `first` integer (default 10, max 20), and an optional `chainIds` array. It is live and returns a standard x402 402 challenge to unauthenticated callers. Zapper also exposes sibling endpoints for DeFi balances, NFT balances, portfolio totals, token prices, transaction history, search, rankings, and more—all at the same base URL under `/x402/{tool}`.
Capabilities
Use cases
- —Retrieve all ERC-20 token holdings and USD values for a wallet address
- —Build a portfolio dashboard aggregating balances across multiple chains
- —Let an AI agent check a user's token positions before executing a trade
- —Monitor wallet balances programmatically for alerting or analytics
- —Compare holdings across multiple addresses in a single call
Fit
Best for
- —Agents or apps that need real-time multi-chain token balances
- —Portfolio trackers requiring USD-denominated balance breakdowns
- —Developers building wallet analytics across 60+ EVM chains
Not for
- —Fetching DeFi/LP positions (use the defi-balances endpoint instead)
- —NFT balance queries (use the nft-balances endpoint instead)
- —Free or high-volume bulk indexing without per-call payment
Quick start
curl -X POST https://public.zapper.xyz/x402/token-balances \
-H "Content-Type: application/json" \
-H "X-Payment: <x402-payment-token>" \
-d '{"addresses":["0xd8da6bf26964af9d7eed9e03e53415d37aa96045"],"first":10}'Example
Request
{
"first": 10,
"chainIds": [
1,
8453
],
"addresses": [
"0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
]
}Response
{
"data": {
"portfolioV2": {
"tokenBalances": {
"byToken": {
"edges": [
{
"node": {
"name": "Ether",
"price": 3812.45,
"symbol": "ETH",
"balance": 32.1,
"network": {
"name": "Ethereum Mainnet"
},
"balanceUSD": 122379.65
}
},
{
"node": {
"name": "USD Coin",
"price": 1,
"symbol": "USDC",
"balance": 3052.91,
"network": {
"name": "Base"
},
"balanceUSD": 3052.91
}
}
],
"totalCount": 42
},
"totalBalanceUSD": 125432.56
}
}
}
}Endpoint
Quality
Full OpenAPI schema with input/output descriptions, live 402 challenge captured, clear pricing ($0.001125 USDC per call on Base), and example request/response shapes provided. Docked slightly because the response schema is example-based rather than a strict JSON Schema, and no external documentation page was reachable (404 on /docs, /pricing, /README).
Warnings
- —Zapper's /docs, /pricing, and /README pages all return 404; documentation may have moved to build.zapper.xyz
- —The legacy v2 API at /api shows a deprecation notice pointing to build.zapper.xyz
- —Response example is inferred from the output schema shape, not from an actual 200 response body
Citations
- —Endpoint is live and returns a 402 x402 challenge with x402Version 2https://public.zapper.xyz/x402/token-balances
- —Price is 1125 base units of USDC on Base (chain 8453), i.e. $0.001125 per callhttps://public.zapper.xyz/x402/token-balances
- —Zapper API covers onchain data across 60+ chains including token prices, NFTs, portfolios, transactions, and morehttps://public.zapper.xyz/api
- —The legacy Zapper v2 API has a deprecation notice directing users to build.zapper.xyzhttps://public.zapper.xyz/api
- —Required body field is addresses (array of 0x wallet addresses); optional fields are first (max 20) and chainIdshttps://public.zapper.xyz/x402/token-balances