API Reference

REST API and WebSocket documentation for the Seesaw indexer.

Overview

The Seesaw indexer provides:

• REST API for querying market and position data
• WebSocket subscriptions for real-time updates
• Historical data for analytics

Base URL

In This Section

• Endpoints - REST API endpoints
• WebSockets - Real-time subscriptions

Quick Start

Fetch Current Market

curl https://api.seesaw.markets/markets/current

Fetch Order Book

curl https://api.seesaw.markets/orderbook/1234567

WebSocket Connection

const ws = new WebSocket('wss://api.seesaw.markets/ws');

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

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

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "data": { ... },
  "timestamp": 1234567890
}

Error Response

{
  "success": false,
  "error": {
    "code": "MARKET_NOT_FOUND",
    "message": "Market with ID 1234567 not found"
  },
  "timestamp": 1234567890
}

Common Headers

Request Headers

Response Headers

Rate Limits

Error Codes

Data Types

Market

interface Market {
  id: string;
  marketId: string;
  pythFeed: string;
  settlementMint: string;
  tStart: number;
  tEnd: number;
  startPrice: string | null;
  endPrice: string | null;
  outcome: 'UP' | 'DOWN' | null;
  totalYesShares: string;
  totalNoShares: string;
  totalCollateral: string;
  totalVolume: string;
  state: 'CREATED' | 'TRADING' | 'SETTLING' | 'RESOLVED';
  createdAt: string;
  updatedAt: string;
}

Order

interface Order {
  orderId: string;
  owner: string;
  side: 'BuyYes' | 'SellYes' | 'BuyNo' | 'SellNo';
  priceBps: number;
  quantity: string;
  originalQuantity: string;
  timestamp: number;
  isActive: boolean;
}

Position

interface Position {
  market: string;
  owner: string;
  yesShares: string;
  noShares: string;
  lockedYesShares: string;
  lockedNoShares: string;
  collateralLocked: string;
  settled: boolean;
  payout: string;
}

Trade

interface Trade {
  id: string;
  marketId: string;
  takerOrderId: string;
  makerOrderId: string;
  taker: string;
  maker: string;
  side: 'BuyYes' | 'SellYes' | 'BuyNo' | 'SellNo';
  priceBps: number;
  quantity: string;
  timestamp: number;
}

Pagination

List endpoints support cursor-based pagination:

GET /markets?limit=20&cursor=eyJpZCI6MTIzNDU2N30

Response includes pagination info:

{
  "success": true,
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6MTIzNDU2OH0"
  }
}

Next Steps

• See Endpoints for all REST endpoints
• See WebSockets for real-time updates