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.

For large or wide historical pulls — a full market's raw L2 tape, or many markets over months — use the async /v1/exports flow instead of a direct download: it builds the file in the background and hands you a re-usable link, so nothing hits a request timeout. A big export takes a few minutes to build — submit it, poll /v1/exports/{job_id}, then fetch the link when it is ready. That is normal, not a hang.

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

300 / hour

/v1/download/* on Professional (+ 20 / min burst); Free 10 / hour. Orders + checkout 5 / min.

Download limits scale with your plan — the burst cap protects the service, not your allowance; your monthly volume is governed by fair use, not the request rate. Exceeding a limit returns 429 Too Many Requests with Retry-After and X-RateLimit-* headers; a failed (5xx) request is refunded, so it never costs you a slot.

Market identifiers

market_id means three different things depending on where it appears. Only the first is a request id.

Where	What it is	Looks like
A request parameter, and `id` on a market	The numeric `markets.id`	1254468
`market_id` in trade rows	An outcome token id: one per outcome	a 70+ digit decimal
`market_id` in orderbook snapshot rows	The market's condition id	a 0x hash

A hex condition id is not accepted in a request. To tell which outcome a token id is, read outcome_token_ids from GET /v1/markets/{id}: it lists the market's tokens in the order of outcomes. See Trade History.

Endpoints

GET/v1/markets

List markets (filters: active, closed, resolved, category, has_data, data_type, search, series_id, ending_after, ending_before, sort_by, limit, offset)

GET/v1/markets/{market_id}

Get a single market by its numeric id, including outcome_token_ids: its outcome tokens, in the order of outcomes

POST/v1/markets/{market_id}/estimate

Size preview for one market over a date window: rows, bytes and what the pull means on your plan

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

Size preview for an entire series over a date window

GET/v1/trades

A market's trades from the full archive, up to 24 h per call (params: market_id or outcome token id, start, end, outcome, side, limit, offset)

GET/v1/trades/ohlcv

OHLCV candles for one outcome (params: market_id, outcome, timeframe=1m|5m|15m|1h|4h|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, limit). Both outcome tokens arrive in one file, told apart only by market_id

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/top_of_book

Free preview: best bid, best ask, midpoint and spread, delayed 24 h, last 30 days (params: market_id, start, end — all three required — format, limit)

GET/v1/download/raw/datasets

List the raw capture streams, with the data_type to pass to /v1/download/raw

GET/v1/download/raw/estimate

Size preview for a raw pull (params: data_type, start, end, limit)

GET/v1/download/raw

Download the raw, event-granular L2 order-book delta tape — the flagship, point-in-time, unbackfillable dataset (params: data_type, start, end, format, shape, limit). start and end are both required

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, data_type, 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/exports

Start an async export job for a large pull — returns 202 + a job id (params: kind=trades|raw, market_id for trades or series_id for raw, start, end, format, idempotency_key). Builds in the background so a wide window never times out. Reusing an idempotency_key returns the same job instead of building it twice.

GET/v1/exports

List your export jobs, newest first (param: limit, up to 200)

GET/v1/exports/{job_id}

Poll a job's status (queued → running → succeeded, failed or expired) with its row count and size

GET/v1/exports/{job_id}/url

Fetch a short-lived signed download URL for a finished export (param: ttl, 60 to 3600 seconds) — free and re-issuable until the export expires

POST/v1/orders

Create an order for datasets your plan covers and issue 7-day download entitlements. An order that would cost money answers 402 (subscription_required or upgrade_required) and debits nothing

GET/v1/orders

List your past orders

GET/v1/orders/estimate

The metering constants behind size estimates (rate_per_mb, bytes_per_row). Reference values, not prices you pay on a subscription

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/subscription

Your plan: tier (free when you have none), billing period, status and period end

POST/v1/billing/subscription/checkout

Start a Paddle checkout for the Professional plan (params: tier, billing_period, success_url, cancel_url)

POST/v1/billing/subscription/redeem

Pay for a plan from an existing credit balance (params: tier, billing_period). Needs the download permission

POST/v1/billing/subscription/cancel

Cancel at the end of the current period

GET/v1/billing/balance

Legacy credit balance, redeemable toward a plan, plus your plan

GET/v1/billing/transactions

Transaction history

GET/v1/billing/pricing

Pricing mode (payg_enabled is false: subscription only) and the metering constants behind size estimates

POST/v1/billing/checkout

Retired. One-time credit top-ups are no longer sold and this answers 410 payg_retired

Response Format

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

// GET /v1/markets — returns array
// (outcomes, outcome_prices and outcome_token_ids are parallel lists)
[
  {
    "id": "1254468",
    "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],
    "outcome_token_ids": ["713210...", "521143..."],
    "active": true,
    "closed": false,
    "resolved": false,
    "winning_outcome": null,
    "resolution_date": 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",
    "category": "crypto"
  }
]

// GET /v1/trades?market_id=1254468&limit=2 — returns array.
// market_id in trade rows is the outcome token id, not the numeric markets.id;
// outcome and outcome_label say which outcome that token is.
[
  {
    "id": "0xfeed...-212",
    "market_id": "713210...",
    "timestamp": "2025-11-05T14:32:15Z",
    "block_number": 65123456,
    "transaction_hash": "0xfeed...",
    "outcome": 0,
    "outcome_label": "Yes",
    "side": "buy",
    "price": 0.67,
    "size": 1033.48,
    "usd_value": 1033.48,
    "maker": "0xabc...",
    "taker": "0xdef...",
    "fee": 0.0,
    "collateral": "pUSD"
  }
]

// POST /v1/markets/{market_id}/estimate — windowed size preview
// Body: { "data_type": "trades", "start": null, "end": null }
// estimated_cost_usd is a per-MB reference, not a price: the pull is included in
// the plan, and the last four fields say how much of it.
{
  "market_id": "1254468",
  "data_type": "trades",
  "estimated_rows": 11500000,
  "estimated_size_bytes": 2645000000,
  "estimated_size_mb": 2522.47,
  "rate_per_mb": 3.0,
  "estimated_cost_usd": 7567.41,
  "in_range": true,
  "pricing_model": "subscription",
  "included_in_plan": "professional",
  "fair_use_share": 0.0493,
  "pricing_note": "Included in the Professional plan: about 4.9% of its 50 GB monthly fair-use allowance. Pay-as-you-go is retired; estimated_cost_usd is a per-MB reference, not a price."
}

Error Handling

Errors return appropriate HTTP status codes with a JSON body:

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

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

// 429 Too Many Requests: the rate limiter. Wait for Retry-After seconds.
{"detail": "Rate limit exceeded"}

// 429 with an object: your plan's monthly fair-use allowance is used up.
// Retrying cannot clear it; it resets on your next billing date.
{"detail": {"code": "fair_use_cap", "message": "Monthly fair-use volume cap reached for your plan. ..."}}

// 402 Payment Required: the data needs a plan. A plan that does not cover
// the dataset gets "upgrade_required" instead.
{"detail": {"code": "subscription_required", "message": "This dataset requires an active subscription. Subscribe at /pricing to access it."}}

Pagination

List endpoints support pagination with limit and offset query parameters:

limit — Number of results to return. /v1/markets: default 100, max 1,000. /v1/trades: default 100, max 10,000.
offset — Number of results to skip (default: 0, max: 1,000,000)

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

Ready to start?

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

Quick Start Get Started