API Reference

Complete reference for the SupaGamma REST API. Data endpoints require authentication via API key; the public series catalogue (GET /v1/series) and aggregate stats are readable without one.

Data over the API

live

Data is available programmatically. Create an API key in the dashboard, then pull files from the /v1/download/* endpoints — everything your plan covers, as often as you need — or connect through the MCP connector to query it inside Claude. The dashboard browses the same catalogue if you would rather point and click.

Base URL

https://api.supagamma.com/v1

Authentication

Include your API key in the X-API-Key header

X-API-Key: sg_your_key_here

API keys are created from your dashboard under the API Keys section. Keys use the format sg_ followed by 32 hex characters.

Rate Limits

Default

60 / min

Per API key (or per IP if anonymous)

Downloads & orders

10 / hour

/v1/download/*; orders + checkout 5 / min

Exceeding a limit returns 429 Too Many Requests with Retry-After and X-RateLimit-* headers. Wait and retry.

Endpoints

GET/v1/markets

List markets (filters: active, has_data, data_type, search, sort_by, limit, offset)

GET/v1/markets/{market_id}

Get a single market by ID

POST/v1/markets/{market_id}/estimate

Cost preview for one market over a date window

GET/v1/markets/{market_id}/stats

Aggregate trade statistics for a market

GET/v1/series

List datasets grouped by broker (Polymarket, etc.) with coverage stats

GET/v1/series/{series_id}

Get one series with detailed coverage info

POST/v1/series/{series_id}/estimate

Cost preview for an entire series over a date window

GET/v1/trades

Query historical trades (params: market_id, start, end, outcome, side, limit, offset)

GET/v1/trades/ohlcv

OHLCV candles (params: market_id, timeframe=1m|1h|1d, start, end)

GET/v1/trades/recent

Most recent trades across all markets

GET/v1/download/trades

Download trades as CSV/Parquet/JSON (params: market_id, start, end, format)

GET/v1/download/ohlcv

Download OHLCV as CSV/Parquet/JSON (params: market_id, timeframe, start, end, format)

GET/v1/download/orderbook

Download orderbook snapshots as CSV/Parquet/JSON (params: market_id, start, end, format)

GET/v1/download/raw

Download the raw, event-granular L2 order-book delta tape — the flagship, point-in-time, unbackfillable dataset (params: dataset, start, end, format)

GET/v1/download/options

Download crypto-options trades + Black-76 greeks from the retained archive (params: series_id, data_type, start, end, format)

GET/v1/download/series

Download a whole venue/product series in one file (params: series_id, start, end, format)

POST/v1/download/bulk

Bulk multi-series download — up to 25 items priced as one order, returned as a single ZIP

POST/v1/orders

Create a paid order for one or more datasets — debits balance, issues 7-day download entitlements

GET/v1/orders

List your past orders

GET/v1/orders/estimate

Estimate total cost of a cart before checkout

GET/v1/user/me

Current user profile

GET/v1/user/keys

List your API keys

POST/v1/user/keys

Create a new API key

DELETE/v1/user/keys/{key_id}

Revoke an API key

GET/v1/user/usage

API call + download usage statistics

GET/v1/user/downloads

Your download history

GET/v1/billing/balance

Current credit balance

POST/v1/billing/checkout

Create a Paddle checkout session to top up credits

GET/v1/billing/transactions

Transaction history

GET/v1/billing/pricing

Public pricing info — per-data-type rates and minimum order

Response Format

Successful responses return JSON. List endpoints return arrays, detail endpoints return objects:

// GET /v1/markets — returns array
[
  {
    "id": "0x1234...",
    "event_id": "evt_...",
    "question": "Will BTC reach $100k by Dec 2025?",
    "description": "Market resolves YES if ...",
    "outcomes": ["Yes", "No"],
    "outcome_prices": [0.67, 0.33],
    "active": true,
    "closed": false,
    "resolved": false,
    "winning_outcome": null,
    "volume": 1542000,
    "volume_24h": 12500,
    "liquidity": 8900,
    "start_date": "2025-06-15T10:00:00Z",
    "end_date": "2025-12-31T23:59:59Z",
    "trade_count": 4231,
    "orderbook_count": 87412,
    "data_from": "2025-06-15T10:00:00Z",
    "data_to": "2026-05-11T12:00:00Z",
    "tags": ["crypto", "bitcoin"],
    "category": "crypto"
  }
]

// GET /v1/trades?market_id=...&limit=2 — returns array.
// market_id in trades rows is the outcome token id (YES or NO),
// not the same as the parent markets.id from /v1/markets.
[
  {
    "id": "trade_abc123",
    "market_id": "0xtoken_yes...",
    "timestamp": "2025-11-05T14:32:15Z",
    "block_number": 65123456,
    "transaction_hash": "0xfeed...",
    "outcome": 0,
    "side": "buy",
    "price": 0.67,
    "size": 1542.50,
    "usd_value": 1033.48,
    "maker": "0xabc...",
    "taker": "0xdef...",
    "fee": 0.0
  }
]

// POST /v1/markets/{market_id}/estimate — windowed cost preview
// Body: { "data_type": "trades", "start": null, "end": null }
{
  "market_id": "0x1234...",
  "data_type": "trades",
  "estimated_rows": 4231,
  "estimated_size_bytes": 973130,
  "estimated_size_mb": 0.9281,
  "rate_per_mb": 3.0,
  "estimated_cost_usd": 2.78,
  "in_range": true
}

Error Handling

Errors return appropriate HTTP status codes with a JSON body:

// 401 Unauthorized
{"detail": "Invalid API key"}

// 429 Too Many Requests
{"detail": "Rate limit exceeded"}

// 404 Not Found
{"detail": "Market not found"}

// 402 Payment Required
{"detail": "Insufficient credits"}

Pagination

List endpoints support pagination with limit and offset query parameters:

limit — Number of results to return (default: 50, max: 1000)
offset — Number of results to skip (default: 0)

GET /v1/trades?market_id=0x1234&limit=100&offset=200

Ready to start?

Create an account and get your API key in under 2 minutes.

Quick Start Get Started