# Base Wallet ERC20 Token Balance Checker

> Base Wallet ERC20 Token Balance Checker is a paid API for AI agents from x402-gateway.blackwoodstate8.workers.dev, paid per call via x402, $0.003/call, status unknown (last checked 2026-10-23).

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

## Facts

- Endpoint: POST https://x402-gateway.blackwoodstate8.workers.dev/v1/wallet-balances?utm_source=zero.xyz
- Price: $0.003/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-23
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/base-wallet-erc20-token-balance-checker-495a0474
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_NFWjWS6WPiT48lUq7hlU4

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability base-wallet-erc20-token-balance-checker-495a0474 -d '<json body>'
```

Example prompt: Check the ETH and all major ERC20 token balances for wallet 0x5A6c77758820182484EA8DE614FC65423E80749a on Base, and also include the custom token at 0x4200000000000000000000000000000000000006.

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

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.

## Request schema (JSON Schema)

```json
{
 "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": {
      
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "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
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/base-wallet-erc20-token-balance-checker-495a0474/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402-gateway.blackwoodstate8.workers.dev](https://www.zero.xyz/host/x402-gateway.blackwoodstate8.workers.dev/llms.txt)