> For the complete documentation index, see [llms.txt](https://zerc20.gitbook.io/zerc20/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zerc20.gitbook.io/zerc20/for-developers/indexer-api.md).

# Indexer API Reference

The indexer is the public read API for zERC20 transfer history and Merkle proof data. Browser applications and SDK integrations may call the indexer directly. Relayer and Decider endpoints are separate services and are not covered by this page.

## Base URL

Hosted indexer URLs are token scoped:

```
https://<api-host>/indexer/<token>
```

Current hosted endpoints:

| Environment     | Token | Base URL                                         |
| --------------- | ----- | ------------------------------------------------ |
| Stage / testnet | zUSDC | `https://beta-v1.api.zerc20.io/indexer/zusdc`    |
| Stage / testnet | zETH  | `https://beta-v1.api.zerc20.io/indexer/zeth`     |
| Stage / testnet | zBNB  | `https://beta-v1.api.zerc20.io/indexer/zbnb`     |
| Stage / testnet | zJPYC | `https://beta-v1.api.zerc20.io/indexer/zjpyc`    |
| Prod / mainnet  | zUSDC | `https://v1.mainnet.api.zerc20.io/indexer/zusdc` |
| Prod / mainnet  | zETH  | `https://v1.mainnet.api.zerc20.io/indexer/zeth`  |
| Prod / mainnet  | zBNB  | `https://v1.mainnet.api.zerc20.io/indexer/zbnb`  |
| Prod / mainnet  | zJPYC | `https://v1.mainnet.api.zerc20.io/indexer/zjpyc` |

Token availability can differ by environment. Use the token registry or the environment configuration as the source of truth for the exact endpoint for a token and network.

## CORS Policy

The hosted indexer is intended to be callable from browser SDK integrations, so the indexer may be served with public CORS enabled.

This public CORS policy applies only to the indexer read API. Relayer and Decider endpoints remain restricted to explicit origin allowlists because they can trigger state-changing or cost-bearing operations.

## Endpoints

### Health

```http
GET /healthz
```

Returns service health.

### Status

```http
GET /status
```

Returns per-token indexer synchronization status.

### Events By Recipient

```http
GET /events?chain_id=<chainId>&token_address=<address>&to=<recipient>&limit=<limit>
```

Returns indexed transfer events for one token and one recipient address.

Limits:

| Parameter | Default | Maximum |
| --------- | ------- | ------- |
| `limit`   | `100`   | `1000`  |

Requests above the maximum are rejected with `400 Bad Request`.

### Events Across Tokens

```http
GET /all-events?recipients=<address>&recipients=<address>&limit=<limit>
```

Returns indexed transfer events across configured tokens for one or more recipient addresses. This endpoint is used by receive flows that need to scan multiple chains for the same burn recipient.

Limits:

| Parameter    | Default | Maximum                         |
| ------------ | ------- | ------------------------------- |
| `recipients` | -       | `100` addresses                 |
| `limit`      | `100`   | `100` per recipient/token group |

Requests above the maximum are rejected with `400 Bad Request`.

### Tree Index By Root

```http
GET /tree-index?chain_id=<chainId>&token_address=<address>&transfer_root=<root>
```

Returns the tree index for a previously indexed transfer root.

### Historical Proofs

```http
POST /proofs
Content-Type: application/json
```

Request body:

```json
{
  "chain_id": 11155111,
  "token_address": "0x0000000000000000000000000000000000000000",
  "target_index": 123,
  "leaf_indices": [1, 2, 3]
}
```

Limits:

| Field             | Maximum   |
| ----------------- | --------- |
| `leaf_indices`    | `100`     |
| JSON payload size | `128 KiB` |

Requests above the maximum are rejected.

## Method And Path Restrictions

Hosted deployments should only proxy the documented indexer paths.

| Path          | Allowed methods   |
| ------------- | ----------------- |
| `/healthz`    | `GET`, `OPTIONS`  |
| `/status`     | `GET`, `OPTIONS`  |
| `/events`     | `GET`, `OPTIONS`  |
| `/all-events` | `GET`, `OPTIONS`  |
| `/tree-index` | `GET`, `OPTIONS`  |
| `/proofs`     | `POST`, `OPTIONS` |

Unexpected methods may return `405 Method Not Allowed`. Unexpected paths under the indexer prefix may return `404 Not Found`.

## Rate Limits And Operational Limits

Hosted indexer deployments may enforce edge limits to protect shared infrastructure:

* IP-based request rate limits
* request body size limits
* request header/body timeouts
* upstream proxy timeouts

Clients should treat `429 Too Many Requests`, `413 Request Entity Too Large`, and `5xx` responses as retryable operational errors where appropriate. Use exponential backoff rather than tight retry loops.

## SDK Receive Flow Limits

The SDK receive flow uses the indexer to fetch candidate events and then fetches Merkle proofs for eligible events. Because proof requests are capped at 100 leaf indices, SDK receive helpers cap `indexerFetchLimit` at `100`.

Recommended default:

```typescript
const indexerFetchLimit = 20;
```

Maximum for SDK receive helpers:

```typescript
const indexerFetchLimit = 100;
```

Use the default unless your integration has a specific reason to fetch more events per request.

## Privacy Note

Calling the hosted indexer reveals the recipient or burn address being queried to the hosted service. For stronger privacy, run a self-hosted indexer and point your SDK configuration at that endpoint.