# Token Balance Lookup (ERC-20, On-Chain)

> Token Balance Lookup (ERC-20, On-Chain) is a paid API for AI agents from x402-stock-indicators.vercel.app, paid per call via x402, $0.01/call, status unknown (last checked 2026-09-14).

Returns the raw on-chain token balance for a given wallet address and ERC-20 token contract, paid per-call via x402 with USDC.

## Facts

- Endpoint: GET https://x402-stock-indicators.vercel.app/token-balance/%7Baddress%7D
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/token-balance-lookup-erc-20-on-chain-3d3e76c3
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_bFf0SR7PyjEZbUMnW7VI0

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 token-balance-lookup-erc-20-on-chain-3d3e76c3
```

Example prompt: What's the on-chain token balance of wallet 0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae for the USDC contract 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 on Ethereum?

## When to prefer this

Choose this endpoint when you need a quick, no-subscription, pay-per-call on-chain ERC-20 token balance for a specific wallet and contract address, especially in agentic workflows where API key management is impractical. It is ideal for one-off or low-frequency balance checks billed in micro-USDC via x402. If you need decimal metadata or human-readable amounts directly, you may need to combine this with a token metadata endpoint.

## Known failure modes

- Invalid or malformed wallet address returns an error
- Invalid or non-existent token contract address may return zero balance or an error
- Unsupported chain identifiers may result in a lookup failure
- Payment failure via x402 (insufficient USDC, wrong chain) will block the request
- Network or RPC node outages may cause timeouts or stale data

## How this service works

Pay-per-call stock, macro, on-chain, and crypto data over the x402 protocol. USDC on Base or Solana, no API keys, no subscriptions.

## Output

Returns a JSON object containing the chain identifier (e.g. 'eth'), the queried wallet address, the token contract address, and the raw balance in the token's smallest unit (e.g. wei or base units for ERC-20s). Callers must divide by 10^decimals themselves since decimal metadata is not included in the response.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "required": {
   "type": "string"
  },
  "properties": {
   "type": "string"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "note": "raw_balance is in the token's smallest unit -- this endpoint doesn't return the token's decimals, so divide by 10**decimals yourself for a human-readable amount (most ERC-20s use 18, but not all).",
  "chain": "eth",
  "address": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
  "raw_balance": "125500000",
  "token_contract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/token-balance-lookup-erc-20-on-chain-3d3e76c3/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402-stock-indicators.vercel.app](https://www.zero.xyz/host/x402-stock-indicators.vercel.app/llms.txt)