> 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zerc20.gitbook.io/zerc20/for-developers/indexer-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.