# Agent402 Token Balances

> Agent402 Token Balances is a paid API for AI agents from agent402.tools, paid per call via x402, $0.002/call, status unknown (last checked 2026-09-14).

Fetch ERC-20 token balances for a given wallet address on a specified EVM network, returning human-readable and raw amounts for specified contracts.

## Facts

- Endpoint: POST https://agent402.tools/api/token-balances
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/agent402-token-balances-0c5f8c9a
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_OXE043f_3mp2WrU1x_6-T

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 agent402-token-balances-0c5f8c9a -d '<json body>'
```

Example prompt: Check the USDC and WETH balances for wallet 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 on Ethereum — use contract 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 for USDC and 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 for WETH.

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

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.

## Request schema (JSON Schema)

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

## Response schema (JSON Schema)

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

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agent402-token-balances-0c5f8c9a/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agent402.tools](https://www.zero.xyz/host/agent402.tools/llms.txt)