Ops Indexer Query

Indexer Query

Query the Boundless Indexer REST API to retrieve on-chain data across multiple chains.

Two Types of Indexer

There are two distinct indexer types with different endpoint sets:

1. Market Indexers -- Deployed per L2 chain. Provide market, requestor, prover, and efficiency endpoints.
2. ZKC Indexers -- Deployed per ZKC token deployment (Ethereum L1). Provide staking, PoVW, and delegation endpoints.

These endpoint sets do not overlap. Market endpoints only work on market indexers; staking/PoVW/delegation endpoints only work on ZKC indexers.

Network Selection

If the user does not specify which network to query, ask them which network they want. Use the query topic to determine whether you need a market indexer or ZKC indexer (or both).

Market Indexers

Available endpoints: /v1/market/**, /v1/market/requestors/**, /v1/market/provers/**, /v1/market/efficiency/**

ZKC Indexers

Available endpoints: /v1/staking/**, /v1/povw/**, /v1/delegations/**

Choosing the Right Indexer

• For proof requests, provers, requestors, market stats, efficiency -> use the market indexer for the relevant L2 chain.
• For staking, PoVW rewards, delegations -> use the ZKC indexer for the corresponding Ethereum deployment.
• If the user asks about both (e.g. "show me prover X's market stats and staking info"), you need to query both the market indexer and the corresponding ZKC indexer.

Use prod URLs by default unless the user explicitly asks for staging.

Store the selected base URL(s) in shell variables for reuse:

export MARKET_INDEXER_URL="https://d2mdvlnmyov1e1.cloudfront.net"
export ZKC_INDEXER_URL="https://d3ig5wxf8178te.cloudfront.net"

Credentials

First, try to read network_secrets.toml from the repo root. If it exists, extract the indexer API key for the selected environment from [environments.<env>.indexer] api_key. Also read network_address_labels.json (same directory) for translating addresses to human-readable labels in output.

If network_secrets.toml is not present, recommend the user create it -- instructions and credentials are in the Boundless runbook. The API still works without a key, but they'll have lower rate limits.

If network_address_labels.json is not present, recommend the user create it -- the canonical address mapping is in the Boundless runbook. The file is plain JSON ({"0xaddr": "label", ...}).

When an API key is available:

export INDEXER_API_KEY="the-key"

Include it in requests via the x-api-key header. Without an API key, omit the header.

Known Addresses

If network_address_labels.json exists at the repo root, use it to label addresses in results. The file is plain JSON ({"0xaddr": "label", ...}) so the user can paste directly from the canonical mapping. When displaying addresses from API responses, check if the address (case-insensitive) has a known label and show it alongside, e.g. 0xbdA9...5542 (BP1).

Provers we operate are labeled with a BP prefix (e.g. BP1, BP2, BPNightlyAWS). When investigating any issue, always highlight what our BP provers are doing -- did they skip, fail, drop, or fulfill? This should be called out explicitly even when the investigation is not specifically about our provers.

Secondary Fulfillment

When a prover locks an order but fails to fulfill it, the order becomes available for secondary fulfillment by any other prover, who earns the slash collateral as reward. In the indexer, a secondary fulfillment is visible when fulfill_prover_address differs from lock_prover_address on a request. Market aggregates include a total_secondary_fulfillments field. When investigating expired or slashed requests, always check whether secondary fulfillment occurred or was attempted -- especially by our BP provers.

Rate Limiting

The API is protected by AWS WAF rate limits:

• Without API key: 200 requests per IP per 5 minutes
• With API key: 1000 requests per IP per 5 minutes

Self-rate-limit when making multiple requests:

• Add sleep 1 between sequential requests
• If a request returns HTTP 429 or 403, back off for 30 seconds before retrying