# ERC-20 Token Balance Lookup

> ERC-20 Token Balance Lookup is a paid API for AI agents from x402-bazaar-rank.x402-bazaar-rank-worker.workers.dev, paid per call via x402, $0.002/call, status unknown (last checked 2026-10-20).

Returns the real-time ERC-20 token balance for a given wallet address on a specified EVM chain, read directly from a public node at the latest block.

## Facts

- Endpoint: GET https://x402-bazaar-rank.x402-bazaar-rank-worker.workers.dev/evm/erc20-balance?utm_source=zero.xyz
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-20
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/erc-20-token-balance-lookup-010238af
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_hmu8AT3uocgrAkypuHxTU

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 erc-20-token-balance-lookup-010238af
```

Example prompt: What's the current USDC balance for wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 on Base? The USDC contract address is 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

## When to prefer this

Choose this endpoint when you need a live, uncached ERC-20 token balance read directly from a public EVM node at the latest block, across Base, Ethereum, Arbitrum, Polygon, or Optimism. It is ideal for pre-transaction balance checks, agent treasury audits, or any workflow where freshness is critical and USD pricing is not required. It is not suitable if you need USD-denominated values, historical balances, NFT balances, or native ETH balances.

## Known failure modes

- Invalid wallet or token address format (must be 0x + 40 hex chars) — returns validation error
- Unsupported chain value — must be one of ethereum, base, arbitrum, polygon, optimism
- Public node unavailable or unresponsive — node fields may be null and listed in errors array
- Token contract does not expose decimals() or symbol() — those fields return null
- Missing required query parameters (address or token) — returns schema validation error
- Network timeout or RPC failure — errors array populated, balance fields may be null

## How this service works

An open index of the machine-to-machine (agent) economy. x402 routes: ranked discovery over the live x402 service market, every indexed service scored by real 30-day calls and paying-wallet bounds, with a receipt naming the snapshot hash and scoring revision. /economy routes, for Tempo MPP, Virtuals ACP, Olas, Masumi, ERC-8004 agent registries, Solana agent registries, Base agent contracts and MCP servers (Official MCP Registry): each protocol's published figures (agent or server counts, transactions or payment events; payers and USD volume only where the source publishes them: payers for x402 and Tempo MPP, USD volume for x402 and Virtuals ACP), each with its unit, window and source; units differ, so totals are not summed. L402 and per-service MPP listings are not covered.

## Output

A JSON object containing the wallet's raw token balance in smallest units (e.g. '25000000' for 25 USDC), the balance in whole units (when decimals are known), token symbol, decimals, the block number at which the node answered, the EVM chain key and chain ID, the timestamp of the reply, the public node host that served the data, and an errors array listing any fields the node did not return.

## 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"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "address",
      "token"
     ],
     "properties": {
      "chain": {
       "enum": [
        "ethereum",
        "base",
        "arbitrum",
        "polygon",
        "optimism"
       ],
       "type": "string",
       "default": "base",
       "description": "Chain; default base"
      },
      "token": {
       "type": "string",
       "pattern": "^0x[0-9a-fA-F]{40}$",
       "description": "ERC-20 contract address"
      },
      "address": {
       "type": "string",
       "pattern": "^0x[0-9a-fA-F]{40}$",
       "description": "Wallet address (0x + 40 hex)"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "chain",
      "chainId",
      "block",
      "as_of",
      "errors",
      "note",
      "address",
      "token",
      "raw"
     ],
     "properties": {
      "raw": {
       "type": "string",
       "description": "Balance in smallest units, decimal string"
      },
      "note": {
       "type": "string",
       "description": "Fixed text: read from a public node, no USD prices"
      },
      "as_of": {
       "type": "string",
       "description": "ISO 8601 UTC time of the reply"
      },
      "block": {
       "type": [
        "integer",
        "null"
       ],
       "description": "Latest block at the node when it answered"
      },
      "chain": {
       "enum": [
        "ethereum",
        "base",
        "arbitrum",
        "polygon",
        "optimism"
       ],
       "type": "string",
       "description": "Chain key"
      },
      "token": {
       "type": "string"
      },
      "amount": {
       "type": [
        "string",
        "null"
       ],
       "description": "Balance in whole units; null when decimals is unknown"
      },
      "errors": {
       "type": "array",
       "items": {
        "type": "string"
       },
       "description": "Calls or fie
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "raw": "25000000",
  "note": "Read directly from a public node at the block shown; nothing is cached, estimated or priced in USD. A field the node did not return is null and named in errors.",
  "as_of": "2026-10-19T12:00:00.000Z",
  "block": 52207800,
  "chain": "base",
  "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "amount": "25",
  "errors": [],
  "source": "base.drpc.org",
  "symbol": "USDC",
  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "chainId": 8453,
  "decimals": 6
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/erc-20-token-balance-lookup-010238af/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402-bazaar-rank.x402-bazaar-rank-worker.workers.dev](https://www.zero.xyz/host/x402-bazaar-rank.x402-bazaar-rank-worker.workers.dev/llms.txt)