# TzKT Token Balances API

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

Retrieves Tezos token balances for accounts, filterable by contract, token ID, standard, and balance amount

## Facts

- Endpoint: GET https://x402.tzkt.io/v1/tokens/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/tzkt-token-balances-api-a128d621
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_csBiNzSkd628nm68IgQ_k

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 tzkt-token-balances-api-a128d621
```

Example prompt: Show me all FA2 token balances for the Tezos address tz1abc123... — return up to 50 results sorted by balance descending.

## When to prefer this

Use this endpoint when you need to query Tezos token holdings — FA1.2, FA2, or NFT balances — for one or more accounts without needing an API key. Prefer this over general Tezos RPC nodes when you need indexed, filterable, paginated token balance data rather than raw chain state.

## Known failure modes

- Invalid account address format returns empty array or 400 error
- Unknown contract address returns empty results
- Limit exceeding 10000 returns validation error
- Invalid sort field name returns 400 error
- Network congestion may cause slower response times
- Malformed filter operators (e.g. balance comparisons) return 400

## How this service works

TzKT is a comprehensive Tezos blockchain indexer API. Access blocks, operations, accounts, contracts, bigmaps, delegates, tokens and network stats through a fast REST API. No signup or API key required.

## Output

Returns an array of token balance objects, each containing the account address, token contract details (address, token ID, standard, metadata), and the current balance amount. Supports pagination and field selection for efficient data retrieval.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "sort": {
   "type": "string",
   "description": "Sorting field and direction"
  },
  "limit": {
   "type": "integer",
   "description": "Max items to return (1-10000)"
  },
  "offset": {
   "type": "integer",
   "description": "Pagination offset"
  },
  "select": {
   "type": "string",
   "description": "Comma-separated list of fields to return"
  },
  "account": {
   "type": "string",
   "description": "Filter by account address"
  },
  "balance": {
   "type": "string",
   "description": "Filter by balance (supports .eq .gt .lt)"
  },
  "contract": {
   "type": "string",
   "description": "Filter by token contract address"
  },
  "token.tokenId": {
   "type": "string",
   "description": "Filter by token ID"
  },
  "token.standard": {
   "enum": [
    "fa1.2",
    "fa2"
   ],
   "type": "string",
   "description": "Filter by token standard"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "array",
 "items": {
  "type": "object"
 }
}
```

## More

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