ops-indexer-query

name: ops-indexer-query description: Internal — for Boundless team members only. Query the Boundless Indexer REST API for on-chain market data, staking, PoVW rewards, delegations, and market efficiency on prod/staging environments. Use when the user asks about proof requests, provers, requestors, staking data, PoVW rewards, delegations, market aggregates, leaderboards, or wants to fetch data from the indexer API on live networks. Also use when the user mentions "indexer" and wants to look up addresses, requests, or market statistics on deployed environments. Do NOT use for debugging local code changes, reviewing PRs, or investigating issues in the codebase itself.

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

Making Requests

All endpoints return JSON. Use curl -s and pipe through jq for readability.

Define a helper function that takes a full URL:

indexer_get() {
  local url="$1"
  if [ -n "$INDEXER_API_KEY" ]; then
    curl -s -H "x-api-key: $INDEXER_API_KEY" "$url"
  else
    curl -s "$url"
  fi
}

Usage:

indexer_get "${MARKET_INDEXER_URL}/v1/market/requests?limit=10" | jq .
indexer_get "${ZKC_INDEXER_URL}/v1/staking/addresses" | jq .

Pagination

Two pagination styles exist:

Offset pagination (staking, PoVW, delegations -- ZKC indexer)

Uses limit (default 50, max 100) and offset (default 0). Response includes pagination: { count, offset, limit }.

indexer_get "${ZKC_INDEXER_URL}/v1/staking/addresses?limit=50&offset=0" | jq .
indexer_get "${ZKC_INDEXER_URL}/v1/staking/addresses?limit=50&offset=50" | jq .

Cursor pagination (market endpoints -- market indexer)

Uses limit and cursor (Base64 opaque token). Response includes has_more and next_cursor.

RESP=$(indexer_get "${MARKET_INDEXER_URL}/v1/market/requests?limit=50")
echo "$RESP" | jq .
NEXT=$(echo "$RESP" | jq -r '.next_cursor // empty')
if [ -n "$NEXT" ]; then
  sleep 1
  indexer_get "${MARKET_INDEXER_URL}/v1/market/requests?limit=50&cursor=$NEXT" | jq .
fi

To fetch all pages in a loop (with rate limiting):

CURSOR=""
PAGE=0
BASE_URL="${MARKET_INDEXER_URL}/v1/market/requests"
while true; do
  PARAMS="limit=50"
  [ -n "$CURSOR" ] && PARAMS="${PARAMS}&cursor=${CURSOR}"
  RESP=$(indexer_get "${BASE_URL}?${PARAMS}")
  echo "$RESP" | jq '.data | length' 
  CURSOR=$(echo "$RESP" | jq -r '.next_cursor // empty')
  HAS_MORE=$(echo "$RESP" | jq -r '.has_more')
  PAGE=$((PAGE + 1))
  [ "$HAS_MORE" = "false" ] || [ -z "$CURSOR" ] && break
  sleep 1
done
echo "Fetched $PAGE pages"

Filtering by Time Range

Not all endpoints support before/after query parameters. The aggregate and cumulative endpoints do, but request list endpoints (/v1/market/requests, /v1/market/provers/:address/requests, /v1/market/requestors/:address/requests) do not have server-side time filtering.

When you need requests from a specific time window on these endpoints, you must paginate and inspect timestamps client-side. Results are sorted by created_at descending (newest first) by default, so stop paginating once you see a created_at older than your cutoff:

CURSOR=""
CUTOFF="2026-03-25T00:00:00Z"
CUTOFF_UNIX=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$CUTOFF" +%s 2>/dev/null || date -d "$CUTOFF" +%s)
BASE_URL="${MARKET_INDEXER_URL}/v1/market/requests"
while true; do
  PARAMS="limit=50"
  [ -n "$CURSOR" ] && PARAMS="${PARAMS}&cursor=${CURSOR}"
  RESP=$(indexer_get "${BASE_URL}?${PARAMS}")

  OLDEST=$(echo "$RESP" | jq '[.data[].created_at] | min')
  if [ "$OLDEST" != "null" ] && [ "$OLDEST" -lt "$CUTOFF_UNIX" ]; then
    echo "Reached cutoff, stopping."
    echo "$RESP" | jq --argjson cutoff "$CUTOFF_UNIX" '.data | map(select(.created_at >= $cutoff))'
    break
  fi

  echo "$RESP" | jq '.data | length'
  CURSOR=$(echo "$RESP" | jq -r '.next_cursor // empty')
  HAS_MORE=$(echo "$RESP" | jq -r '.has_more')
  [ "$HAS_MORE" = "false" ] || [ -z "$CURSOR" ] && break
  sleep 1
done

Endpoints that do support before/after (Unix timestamps):

• /v1/market/aggregates
• /v1/market/cumulatives
• /v1/market/requestors/:address/aggregates
• /v1/market/requestors/:address/cumulatives
• /v1/market/provers/:address/aggregates
• /v1/market/provers/:address/cumulatives
• /v1/market/efficiency/aggregates
• /v1/market/efficiency/requests

Endpoints that require client-side time filtering:

• /v1/market/requests
• /v1/market/requestors/:address/requests
• /v1/market/provers/:address/requests
• All staking, PoVW, and delegation endpoints

Endpoint Reference

For the full list of endpoints, query parameters, and response schemas, read references/endpoints.md.

Quick Reference

Market Indexer endpoints (L2 chains: Base, Taiko, Base Sepolia):

ZKC Indexer endpoints (Ethereum L1: Eth Mainnet, Eth Sepolia):

Common Tasks

Look up a specific request (market indexer)

indexer_get "${MARKET_INDEXER_URL}/v1/market/requests/0xABC123" | jq .

Get recent requests (market indexer)

indexer_get "${MARKET_INDEXER_URL}/v1/market/requests?limit=20" | jq .

Get requests for a specific requestor (market indexer)

indexer_get "${MARKET_INDEXER_URL}/v1/market/requestors/0xADDRESS/requests?limit=20" | jq .

Get daily market stats for the last week (market indexer)

indexer_get "${MARKET_INDEXER_URL}/v1/market/aggregates?aggregation=daily&limit=7" | jq .

Get prover leaderboard for last 24h (market indexer)

indexer_get "${MARKET_INDEXER_URL}/v1/market/provers?period=1d" | jq .

Get staking info for an address (ZKC indexer)

indexer_get "${ZKC_INDEXER_URL}/v1/staking/addresses/0xADDRESS" | jq .

Get PoVW rewards for an address (ZKC indexer)

indexer_get "${ZKC_INDEXER_URL}/v1/povw/addresses/0xADDRESS" | jq .

Check market efficiency (market indexer)

indexer_get "${MARKET_INDEXER_URL}/v1/market/efficiency?type=gas_adjusted" | jq .

Error Handling

Error responses return JSON: {"error": "...", "message": "..."}.

OpenAPI Spec

The full OpenAPI spec is available on any indexer at /openapi.yaml or interactively at /docs (Swagger UI). Fetch it if you need detailed field-level schema information:

indexer_get "${MARKET_INDEXER_URL}/openapi.yaml"
indexer_get "${ZKC_INDEXER_URL}/openapi.yaml"