API Overview

The Runner Protocol indexer provides a REST API and WebSocket endpoint for querying on-chain auction and launch data. The indexer watches both the CCA V2 and Launchpad programs via Solana WebSocket subscriptions and stores decoded account state in PostgreSQL.

Base URL

Environment	URL
Devnet	https://cca-indexer-production.up.railway.app

All endpoints are prefixed with /api/ (e.g., GET /api/auctions).

Authentication

No authentication is required for read endpoints. The API is publicly accessible.

The POST /api/launches/:pubkey/metadata endpoint requires wallet signature authentication (Ed25519 signature verification).

Pagination

List endpoints use cursor-based pagination. Each paginated response has the following shape:

{
  "data": [ ... ],
  "next_cursor": "eyJzbG90IjozMTIzNDU2LCJwdWJrZXkiOiJBYmMxMjMifQ==",
  "has_more": true
}

Query Parameters

Parameter	Type	Default	Description
cursor	string	none	Opaque cursor from a previous response's next_cursor field
limit	number	20	Number of items per page (max varies by endpoint)

Usage

// First page
const page1 = await fetch(`${BASE_URL}/api/auctions?limit=10`).then(r => r.json());

// Next page (if has_more is true)
if (page1.has_more) {
  const page2 = await fetch(
    `${BASE_URL}/api/auctions?limit=10&cursor=${page1.next_cursor}`
  ).then(r => r.json());
}

Some endpoints (checkpoints, events) use offset-based pagination with offset and limit parameters instead of cursors.

Rate Limits

The API does not currently enforce explicit rate limits, but excessive request rates may be throttled by the infrastructure provider. For real-time data, use the WebSocket endpoint instead of polling.

Health Check

GET /api/health

Returns indexer health status, slot lag, and uptime:

{
  "status": "healthy",
  "lag_slots": 12,
  "lag_seconds": 4.8,
  "current_slot": 312345678,
  "last_confirmed_slot": 312345666,
  "last_finalized_slot": 312345640,
  "last_event_slot": 312345660,
  "last_live_event_slot": 312345665,
  "max_event_slot": 312345665,
  "bootstrap_complete": true,
  "uptime_seconds": 86400
}

Status	Meaning
healthy	Slot lag < 100 and bootstrap complete
degraded	Slot lag 100-500 or bootstrap not complete
unhealthy	Slot lag > 500

Protocol Stats

GET /api/stats

Returns aggregate protocol statistics:

{
  "total_auctions": 4,
  "active_auctions": 1,
  "graduated_auctions": 0,
  "total_bids": 12,
  "total_launches": 5,
  "total_volume_quote": "5000000000",
  "total_bid_volume": "8000000000"
}

Error Responses

Errors follow a consistent format:

{
  "error": "Auction not found"
}

Status Code	Meaning
400	Bad request (invalid parameters)
404	Resource not found
500	Internal server error
503	Service unavailable (health check failure)