API Reference

Complete reference for the SupaGamma REST API. All endpoints require authentication via API key.

Base URL

https://api.supagamma.com/v1

Authentication

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

X-API-Key: sg_live_your_key_here

API keys are created from your dashboard under the API Keys section. Keys use the format sg_live_xxxxxxxxxxxx.

Rate Limits

All users

60 requests/min

Per API key

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait and retry after the limit resets.

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)

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": 1.0,
  "estimated_cost_usd": 0.93,
  "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