API Reference#

REST API and WebSocket documentation for the Seesaw indexer.

Trust model. The REST/WebSocket API is a convenience layer: it serves an off-chain database populated by the indexer from on-chain events. It is read-path infrastructure only — it never holds funds and cannot sign transactions — but its responses are only as fresh and as honest as the indexer that produced them (GET /api/v1/status reports freshness). Integrators requiring direct account verification can use the canonical SDK guide with their own Solana RPC and stream provider, keeping the indexer out of the verification path.

Section Map#

Base URL: https://api.seesaw.markets

The OpenAPI and AsyncAPI documents are enforced compatibility contracts. The parsed compatibility suite in packages/api-contracts/src/__tests__/api-spec-compatibility.test.ts checks their structure, internal references, operation inventory, and implemented WebSocket limits.

Integration Contract#

Use the REST and chain-direct parity matrix to choose a supported path for each capability. For a language-neutral event consumer, the binary recorder wire reference specifies the header and every assigned event layout.

Use /api/v1 paths for new integrations. Public market reads do not require authentication; wallet-scoped reads and transaction-building endpoints require the documented wallet-signature flow. Requests that exceed a configured limit return HTTP 429 with Retry-After; clients should back off and retry rather than treating a rate limit as a permanent failure.

REST responses include a data envelope unless the endpoint explicitly documents an unwrapped diagnostic response. Treat unknown fields as forward-compatible, keep token quantities as decimal strings, and use the response's market state and resolution fields rather than inferring settlement from timestamps alone.

For live consumers, WebSocket updates are best reconciled with a fresh REST snapshot after reconnect. Indexed event order, transaction confirmation, and third-party RPC observations can differ temporarily; clients should surface staleness and avoid presenting an unconfirmed update as final settlement.

Partner Access Policy#

During Solana beta, partner access uses the same public API surface as the web and mobile clients. Seesaw does not offer API keys, quota tiers, or outbound partner webhooks for fills, resolutions, or account events. Wallet-scoped reads and writes use signed Solana wallet authentication; public market data remains available without authentication subject to the documented rate limits.

WebSocket is the only hosted push channel for partners. The failed_webhooks database table and /webhook/helius route are internal inbound Helius ingestion infrastructure, not a partner webhook subscription product. Partners should use canonical /api/v1 REST polling for snapshots and the /ws WebSocket endpoint for live updates.

Quick Orientation#

The examples below show the two most common first requests. For full parameter and response details, follow the links above.

# Fetch the current market (no auth required)
curl https://api.seesaw.markets/api/v1/markets/current

# Fetch the top of book
curl https://api.seesaw.markets/api/v1/orderbook/top

// Subscribe to live market updates over WebSocket
const ws = new WebSocket('wss://api.seesaw.markets/ws');

ws.onopen = () => {
  ws.send(
    JSON.stringify({
      type: 'subscribe',
      channel: 'market:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU',
    })
  );
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update:', data);
};

See Also#

• Endpoints — public REST read endpoints
• Exchange Facade — terminal-friendly symbols and read-only market data
• CCXT Read Adapter — CCXT-shaped read adapter over the exchange facade
• Hummingbot Integration Helper — REST snapshots and wallet-signed order intents for a future caller-owned connector
• Full REST Reference — authentication and authenticated endpoints
• WebSockets — real-time updates
• Trustless Stream Consumer Recipes — user-owned stream integration patterns
• SDK Guide — trust-based client SDKs that consume this API
• SDK Guide — direct account reads and transaction building