{"uid":"cap_OXE043f_3mp2WrU1x_6-T","slug":"agent402-token-balances-0c5f8c9a","name":"Agent402 Token Balances","description":"ERC-20 balances of one wallet for a NAMED list of token contracts (1-20) - the targeted complement to the full-portfolio wallet-balance tool. One balance read for the whole list plus symbol/decimals per contract (cached an hour server-side), so 'how much USDC and WETH does this wallet hold on Base?' is a single cheap call with exact decimal strings, not a portfolio dump.","url":"https://agent402.tools/api/token-balances","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"address":{"type":"string","description":"0x-prefixed 40-char EVM wallet address."},"network":{"type":"string","description":"ethereum / base / polygon / arbitrum / optimism (default ethereum)."},"contracts":{"type":"array","items":{"type":"string"},"description":"1-20 ERC-20 contract addresses to read."}}},"responseSchema":{"type":"json","example":{"source":"alchemy","tokens":[{"raw":"37192124","name":"USDC","symbol":"USDC","balance":"37.192124","contract":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","decimals":6},{"raw":"1461000000000000000","name":"Wrapped Ether","symbol":"WETH","balance":"1.461","contract":"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2","decimals":18}],"address":"0xd8da6bf26964af9d7eed9e03e53415d37aa96045","chainId":1,"network":"ethereum","fetchedAt":"2026-08-22T12:00:00.000Z"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.002","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.002/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_DzxBR29PQBaPUPbZRTiYu","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.002","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Fetch ERC-20 token balances for a given wallet address on a specified EVM network, returning human-readable and raw amounts for specified contracts.","exampleAgentPrompt":"Check the USDC and WETH balances for wallet 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 on Ethereum — use contract 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 for USDC and 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 for WETH.","exampleUseCases":[{"title":"Pre-swap balance check for DeFi bot","prompt":"Before executing a swap, check if wallet 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 has at least 50 USDC on Ethereum — look up contract 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48."},{"title":"Multi-token portfolio snapshot on Base","prompt":"Pull the current balances for three tokens on Base for wallet 0xAbCd1234... — give me the human-readable amounts for USDC, WETH, and DAI contracts."},{"title":"Monitor stablecoin reserves on Polygon","prompt":"What's the current USDC balance for wallet 0x1234abcd... on Polygon? I want to know if reserves have dropped below $100 — check contract 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174."}],"resultDescription":"Returns a JSON object containing the wallet address, network, chain ID, fetch timestamp, and an array of token objects — each with name, symbol, contract address, decimal count, raw integer balance, and human-readable decimal-adjusted balance.","failureModes":["Invalid or malformed wallet address returns an error","Unsupported network name causes a validation failure","Contract address array exceeding 20 items may be rejected","Network congestion or Alchemy upstream outage returns a 5xx error","Non-ERC-20 contract addresses may return empty or zero balances"],"whenToPreferThis":"Use this endpoint when you need accurate, human-readable ERC-20 token balances for one or more specific contracts on a named EVM chain (Ethereum, Base, Polygon, Arbitrum, Optimism) without managing API keys or node infrastructure. Prefer it over raw RPC calls when you want normalized decimal handling and metadata (name, symbol) bundled in one response. Pay-per-call with no signup makes it ideal for agents that need occasional balance lookups.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T00:49:24.754Z","isFirstParty":false}