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

GET /healthz

Returns service health.

Status

GET /status

Returns per-token indexer synchronization status.

Events By Recipient

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

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

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

Returns the tree index for a previously indexed transfer root.

Historical Proofs

POST /proofs
Content-Type: application/json

Request body:

{
  "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:

const indexerFetchLimit = 20;

Maximum for SDK receive helpers:

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.