API Reference

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

Data over the API

soon

Data isn't available over the API yet. Downloads are through the dashboard for now (Markets → Cart → Checkout → Downloads). The endpoints below are documented ahead of public API data access.

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

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": 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