# Base Wallet Token Balances

> Base Wallet Token Balances is a paid API for AI agents from api.botx402.io, paid per call via x402, $0.01/call, status unknown (last checked 2026-10-29).

Returns live ETH and ERC-20 token balances (top 200 Base tokens + custom addresses) for a given Base mainnet wallet address

## Facts

- Endpoint: POST https://api.botx402.io/base-address-balance?utm_source=zero.xyz
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-29
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/base-wallet-token-balances-e73ace6f
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_1N4Xt6bLz6NVeu8fEpfub

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-token-balances-e73ace6f -d '<json body>'
```

Example prompt: What are the current ETH and token balances for the Base wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045? Also check the balance for token contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

## When to prefer this

Use this endpoint when you need real-time, on-chain token balances for a Base mainnet wallet address — especially before executing a payment, transfer, or token swap where accurate balance verification is critical. It covers native ETH plus the top 200 Base tokens by market cap automatically, and accepts up to 50 additional custom contract addresses. Prefer this over portfolio or analytics APIs when you need raw and human-readable amounts without USD pricing, identity labels, or historical data.

## Known failure modes

- Invalid wallet address format (not 0x + 40 hex chars) returns 400
- Chain value other than 'base' returns 400
- Non-empty filters or order_by objects return 400
- More than 50 custom token_addresses provided returns 400
- Network or RPC timeout when reading from Base mainnet
- Token contract address that is not a valid ERC-20 may return zero balance without error
- Wallet with no token holdings returns empty rows except native ETH

## How this service works

Returns the native ETH balance and ERC-20 token balances of one Base wallet address, read live from Base mainnet at the latest block: USDC, WETH and the rest of the top 200 Base tokens by market cap, plus up to 50 token contract addresses named in the request. Each row carries the token symbol, name, decimals, raw amount and human-readable amount. Suited to checking a wallet's current holdings before a payment, transfer or swap; returns no labels, identities, USD values or portfolio valuation.

## Output

A list of token balance rows for the queried Base wallet, ordered with native ETH first and then top Base tokens by rank. Each row includes the token symbol, name, decimal places, raw on-chain amount, and human-readable amount. Data is read live from Base mainnet at the latest block. No USD values, portfolio valuation, or identity labels are included.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "chain": {
   "type": "string",
   "description": "The chain to read. Only \"base\" is served; any other value returns 400."
  },
  "address": {
   "type": "string",
   "pattern": "^0x[0-9a-fA-F]{40}$",
   "description": "The Base wallet address (0x and 40 hex characters) whose token balances are read."
  },
  "filters": {
   "type": "object",
   "description": "Accepted only when empty.",
   "maxProperties": 0
  },
  "order_by": {
   "type": "array",
   "maxItems": 0,
   "description": "Accepted only when empty. Rows come native token first, then by the token list's rank."
  },
  "pagination": {
   "type": "object",
   "properties": {
    "page": {
     "type": "integer",
     "minimum": 1
    },
    "per_page": {
     "type": "integer",
     "maximum": 250,
     "minimum": 1
    }
   },
   "additionalProperties": false
  },
  "hide_spam_token": {
   "type": "boolean",
   "description": "Accepted for compatibility. Holdings come from a fixed list of tokens, so there is no spam to hide."
  },
  "token_addresses": {
   "type": "array",
   "items": {
    "type": "string",
    "pattern": "^0x[0-9a-fA-F]{40}$"
   },
   "maxItems": 50,
   "description": "ERC-20 token contract addresses to read beyond the fixed list of the top 200 Base tokens.",
   "uniqueItems": true
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/base-wallet-token-balances-e73ace6f/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.botx402.io](https://www.zero.xyz/host/api.botx402.io/llms.txt)