# Zapper Token Balances

> Zapper Token Balances is a paid API for AI agents from public.zapper.xyz, paid per call via x402, $0.001125/call, status down (last checked 2026-09-16).

Fetches detailed token balances (with USD values, prices, and metadata) for one or more wallet addresses, optionally filtered by chain.

## Facts

- Endpoint: POST https://public.zapper.xyz/x402/token-balances
- Price: $0.001125/call
- Payment: x402
- Status: down
- Last checked: 2026-09-16
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/public-zapper-xyz-1907f0a2
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_h2NvCy9EwL7bHu0rMntba

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 public-zapper-xyz-1907f0a2 -d '<json body>'
```

Example prompt: Show me the top 10 token balances for wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 on Ethereum mainnet (chain ID 1) using Zapper — include USD values and token prices.

## When to prefer this

Use this endpoint when you need granular per-token breakdown of a wallet's holdings including USD valuation, token metadata, and multi-chain filtering. Prefer this over the portfolio totals endpoint when you need individual token-level detail rather than aggregate network summaries.

## Known failure modes

- Invalid wallet address format returns an error or empty result
- Chain ID not supported returns empty token list
- Requesting more than 20 tokens per page is capped at 20
- No tokens found for the address on the specified chain returns empty edges array
- Network or upstream Zapper API errors may return non-JSON or partial responses

## How this service works

Fetch detailed token balances for a single address or list of addresses, optionally filtered by chain, with pagination (max 20 tokens).

## Output

Returns a paginated list of up to 20 tokens held by the queried address(es), including token name, symbol, price, raw balance, USD balance, contract address, image URL, and network. Also includes a totalBalanceUSD aggregated across all returned tokens.

## Example request

```json
{
 "first": 10,
 "chainIds": [
  1
 ],
 "addresses": [
  "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
 ]
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "first": {
   "type": "integer",
   "default": 10,
   "description": "Number of tokens to return (max 20)"
  },
  "chainIds": {
   "type": "array",
   "items": {
    "type": "integer"
   },
   "description": "Optional list of Chain IDs to filter by (e.g. [1, 8453])"
  },
  "addresses": {
   "type": "array",
   "items": {
    "type": "string",
    "description": "A 0x wallet address"
   },
   "description": "Array of 0x wallet addresses to aggregate"
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/public-zapper-xyz-1907f0a2/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from public.zapper.xyz](https://www.zero.xyz/host/public.zapper.xyz/llms.txt)