{"uid":"cap_NFWjWS6WPiT48lUq7hlU4","slug":"base-wallet-erc20-token-balance-checker-495a0474","name":"Base Wallet ERC20 Token Balance Checker","description":"Use when you need the ERC20 token balance or wallet balance of an address on Base for onchain data checks. Do not use for ethereum mainnet or other chains, NFTs, transaction history or USD values. Returns JSON with the ETH and ERC20 token balances of a wallet on Base, read on-chain in one block: 21 major tokens plus any you list for 0.004 USDC per call. Typical response time 1200 ms (p95). Category: Data.","url":"https://x402-gateway.blackwoodstate8.workers.dev/v1/wallet-balances?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method","bodyType","body"],"properties":{"body":{"type":"object","required":["address"],"properties":{"tokens":{"type":"array","items":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"maxItems":20,"description":"Extra ERC20 token addresses on Base to check, e.g. [\"0x4200000000000000000000000000000000000006\"] (up to 20, beyond the 21 major ones)"},"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Wallet address on Base, e.g. 0x5A6c77758820182484EA8DE614FC65423E80749a"},"includeZero":{"type":"boolean","description":"Also list tokens with zero balance (false when omitted)"}}},"type":{"type":"string","const":"http"},"method":{"enum":["POST"],"type":"string"},"bodyType":{"enum":["json","form-data","text"],"type":"string"}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","required":["address","network","blockNumber","native","tokens","notTokens","checkedTokens"],"properties":{"next":{"type":"object","required":["service","tool","method","url","useWhen","sample"],"properties":{"url":{"type":"string","description":"Paid route of the next call"},"tool":{"type":"string","description":"MCP tool name of the same call"},"method":{"enum":["GET","POST"],"type":"string"},"sample":{"type":"string","description":"Free fixed sample of the whole family"},"service":{"type":"string","description":"Service id of the suggested next paid call"},"useWhen":{"type":"string","description":"When the next call is the right one"}},"description":"Suggested next paid call in the same family (call it in a loop when the task continues)","additionalProperties":false},"native":{"type":"object","required":["symbol","balance","raw"],"properties":{"raw":{"type":"string"},"symbol":{"type":"string","const":"ETH"},"balance":{"type":"string"}},"additionalProperties":false},"tokens":{"type":"array","items":{"type":"object","required":["token","symbol","decimals","balance","raw"],"properties":{"raw":{"type":"string"},"token":{"type":"string"},"symbol":{"type":["string","null"]},"balance":{"type":"string"},"decimals":{"type":"integer","maximum":9007199254740991,"minimum":-9007199254740991}},"additionalProperties":false}},"address":{"type":"string"},"network":{"type":"string","const":"eip155:8453"},"notTokens":{"type":"array","items":{"type":"string"}},"blockNumber":{"type":"integer","maximum":9007199254740991,"minimum":-9007199254740991},"checkedTokens":{"type":"integer","maximum":9007199254740991,"minimum":-9007199254740991}},"additionalProperties":false}}}}},"responseSchema":{"type":"json","example":{"native":{"raw":"0","symbol":"ETH","balance":"0"},"tokens":[{"raw":"10000","token":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","symbol":"USDC","balance":"0.01","decimals":6}],"address":"0x5A6c77758820182484EA8DE614FC65423E80749a","network":"eip155:8453","notTokens":[],"blockNumber":52713897,"checkedTokens":21}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.003","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"registry","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.003/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.003","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.003","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_FgPIImrn413scepOe4uB0","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.003","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns ETH and ERC20 token balances for a wallet address on the Base network, reading 21 major tokens plus custom tokens on-chain in a single block","exampleAgentPrompt":"Check the ETH and all major ERC20 token balances for wallet 0x5A6c77758820182484EA8DE614FC65423E80749a on Base, and also include the custom token at 0x4200000000000000000000000000000000000006.","exampleUseCases":[{"title":"DeFi portfolio balance audit","prompt":"What are all the token balances for wallet 0xAbC1234567890000000000000000000000000001 on Base? Show me ETH and all ERC20 tokens including zeros."},{"title":"Pre-transaction liquidity check","prompt":"Before I send a transaction, check if wallet 0xDEF9876543210000000000000000000000000002 on Base has enough USDC and ETH — give me their current on-chain balances."},{"title":"Custom token balance lookup","prompt":"Can you check the balance of the custom ERC20 token at address 0x1234567890abcdef1234567890abcdef12345678 for wallet 0x9999888877776666555544443333222211110000 on Base?"}],"resultDescription":"A JSON object containing the queried wallet address, network name, block number at which the read was taken, native ETH balance (symbol, human-readable balance, raw wei), a list of ERC20 tokens with their symbol, contract address, decimals, human-readable balance, and raw balance, as well as a list of addresses that were checked but are not valid tokens, and the full list of checked token addresses. Also includes a suggested next call.","failureModes":["Invalid wallet address format (must be 0x + 40 hex chars) — validation error","Token contract address not on Base or invalid — listed in notTokens array","Network congestion causing RPC timeout beyond 1200ms p95","Request to Ethereum mainnet or non-Base chains — not supported by this endpoint","More than 20 custom tokens supplied — exceeds maxItems limit","Payment not settled — x402 payment required error"],"whenToPreferThis":"Use this endpoint when you need on-chain token balances specifically on the Base network for a given wallet address, covering ETH and up to 21 major ERC20 tokens plus up to 20 custom token addresses in a single atomic block read. Prefer this over alternatives when you need Base-specific data (not Ethereum mainnet, Polygon, or other EVM chains), when you need multiple token balances in one call rather than individual lookups, and when you do not need USD valuations, NFT holdings, or transaction history.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-23T00:54:45.721Z","isFirstParty":false,"canonicalSlug":"base-wallet-erc20-token-balance-checker-495a0474"}