# Oddpool API

Base URL: https://api.oddpool.com
Auth: X-API-Key header (pass your API key in the X-API-Key request header)

## Tiers
| Endpoint Group | Required Plan | Price |
|----------------|--------------|-------|
| Whale Tracking | Pro | $30/mo |
| Arbitrage | Premium | $100/mo |
| Price Spreads | Premium | $100/mo |
| Search | Premium | $100/mo |

## Rate Limits
- 10 requests/second burst
- 1,000 requests/minute sustained

## Error Codes
| Code | Description |
|------|-------------|
| 200 | Success |
| 400 | Bad request — Invalid parameters |
| 401 | Unauthorized — Invalid API key |
| 403 | Forbidden — No active subscription or insufficient tier |
| 404 | Not found — Resource does not exist |
| 429 | Rate limit exceeded |
| 500 | Server error |

Error response format: `{"detail": "Error message"}`

## WebSocket Feeds

### Connection

Stream real-time, normalized prediction market data over WebSocket. One connection gives you cross-venue orderbooks, trades, and probability distributions from both Kalshi and Polymarket -- no venue-specific code needed.

Data is addressed by **what**, not where. You subscribe to `dist:fomc-2026-04-29`, not a venue-specific ticker. Both venues arrive on the same channel, tagged by `venue` field.

```
wss://feeds.oddpool.com/ws
```

### Authentication

Send an auth message with your API key after connecting. The server responds with your tier and limits.

```json
// Send
{"action": "auth", "api_key": "oddpool_abc123..."}

// Response
{
  "type": "auth",
  "status": "ok",
  "user_id": 42,
  "tier": "pro",
  "limits": {
    "max_events": 10,
    "max_connections": 3,
    "channels": ["dist", "book", "trade", "snapshot"]
  }
}
```

### Subscribe & Unsubscribe

Subscribe to channels by event. Events count as concurrent subscriptions -- unsubscribing frees up slots.

| Format | Example | Scope |
|--------|---------|-------|
| `{type}:{event_key}` | dist:fomc-2026-04-29 | All outcomes for that event |
| `{type}:{event_key}:{outcome}` | book:fomc-2026-04-29:hold | Single outcome |

```json
// Subscribe to multiple channels at once
{"action": "subscribe", "channels": ["dist:fomc-2026-04-29", "book:fomc-2026-04-29:hold"]}

// Response
{"type": "subscribed", "channels": ["dist:fomc-2026-04-29", "book:fomc-2026-04-29:hold"]}

// Unsubscribe
{"action": "unsubscribe", "channels": ["book:fomc-2026-04-29:hold"]}
```

### Macro Feed

Cross-venue matched macro economic events from Kalshi and Polymarket. Real-time orderbooks, trade executions, and liquidity-weighted probability distributions for FOMC, CPI, NFP, GDP, unemployment, rate expectations, equities, and commodities.

| Category | Events |
|----------|--------|
| FOMC Rate Decisions | April 2026, June 2026, total rate cuts 2026 |
| Inflation (CPI) | Year-over-year, month-over-month |
| Jobs | Nonfarm payrolls, unemployment rate |
| GDP | Q1 2026 real GDP, annual GDP growth |
| Equities & Commodities | S&P 500, Nasdaq 100, gold, silver |

**Use cases:**

- **Arbitrage.** See cross-venue price divergence in real-time. Each message includes `venue_id` with the venue-specific identifiers (Kalshi market ticker, Polymarket condition/token IDs) needed to execute immediately.
- **Signal generation.** The `dist` channel computes a liquidity-weighted cross-venue probability on every book update -- a better signal than either venue alone.
- **Macro monitoring.** One WebSocket covers FOMC, CPI, NFP, GDP, unemployment, and rate expectations. Subscribe to `dist:*` events and build a real-time macro probability surface.
- **Trading agents.** Normalized schema means your agent code is venue-agnostic. Parse once, trade anywhere.

### Message Reference

Four channel types, one schema. Every message arrives wrapped in an envelope:

```json
{"type": "data", "channel": "dist:fomc-2026-04-29", "data": { ... }}
```

| Channel | Subscribe to | Description | Tier |
|---------|-------------|-------------|------|
| dist | dist:fomc-2026-04-29 | Cross-venue probability distribution for all outcomes | Free |
| book | book:fomc-2026-04-29:hold | Normalized orderbook updates for one outcome | Pro |
| trade | trade:fomc-2026-04-29:hold | Trade executions for one outcome | Pro |
| snapshot | snapshot:fomc-2026-04-29 | Full state reset every 60s for all outcomes | Pro |

#### Distribution

Shows the market-implied probability for every outcome in an event, combining data from both venues.

```json
{
  "event_key": "fomc-2026-04-29",
  "seq": 312,
  "published_ts": 1773892530947,
  "outcomes": [
    {
      "outcome": "hold",
      "label": "Fed maintains rate",
      "kalshi_prob": 0.945,
      "poly_prob": 0.955,
      "prob": 0.9479,
      "kalshi_depth_usd": 4714197.04,
      "poly_depth_usd": 1965879.48
    }
  ],
  "total_kalshi_depth_usd": 4784397.57,
  "total_poly_depth_usd": 2104564.65
}
```

| Field | Description |
|-------|-------------|
| prob | Combined probability, weighted by each venue's liquidity. Kalshi at 94.5% with $4.7M depth + Polymarket at 95.5% with $2.0M depth = 94.79% |
| kalshi_prob / poly_prob | Each venue's YES mid-price (best bid + best ask) / 2. Null if that venue has no data. |
| kalshi_depth_usd / poly_depth_usd | Total USD within +/-5c of mid on each venue. Shows how much liquidity backs each probability. |

#### Book Update

Normalized orderbook updates from both venues. Prices are contract prices (0-1), sizes are absolute quantities. Derived fields like best bid/ask, mid, spread, and depth are pre-computed on every update.

```json
{
  "event_key": "fomc-2026-04-29",
  "outcome": "hold",
  "venue": "polymarket",
  "token": "yes",
  "venue_id": {
    "condition_id": "0x36e8ca2...",
    "token_id": "63586620628..."
  },
  "seq": 4217,
  "exchange_ts": 1773892530351,
  "received_ts": 1773892530360,
  "published_ts": 1773892530363,
  "update_type": "delta",
  "levels": [
    {"side": "bid", "price": "0.955", "size": 8300.00},
    {"side": "ask", "price": "0.965", "size": 0}
  ],
  "best_bid": "0.955",
  "best_ask": "0.965",
  "mid": "0.960",
  "spread": "0.010",
  "bid_depth_usd": 47141.97,
  "ask_depth_usd": 23456.78
}
```

| Field | Description |
|-------|-------------|
| venue_id | Identifiers to execute on the venue. Kalshi: market ticker. Polymarket: condition ID + token ID. |
| update_type | "snapshot" = full book replacement. "delta" = only changed levels. Size of 0 = level removed. |
| levels | Price levels with side (bid/ask), price (0-1), and size (absolute quantity after this update). |
| best_bid / best_ask / mid / spread | Pre-computed from full cross-token book state, not just the levels in this update. |
| bid_depth_usd / ask_depth_usd | Total USD within +/-5c of mid on bid and ask sides. |

#### Trade

Every trade execution from both venues, including the specific contract traded, price, quantity, and a venue-provided trade ID.

```json
{
  "event_key": "fomc-2026-04-29",
  "outcome": "hold",
  "venue": "kalshi",
  "token": "no",
  "action": "buy",
  "venue_id": {"market_ticker": "KXFEDDECISION-26APR-H0"},
  "seq": 89,
  "exchange_ts": 1773892530000,
  "received_ts": 1773892530008,
  "published_ts": 1773892530010,
  "price": "0.06",
  "qty": 136.00,
  "trade_id": "a4d77927-dafe-5bde-53ed-80f6129cfd19"
}
```

#### Timestamps

Every book and trade message carries four timestamps (Unix ms) for end-to-end latency decomposition.

| Field | Description |
|-------|-------------|
| exchange_ts | When the exchange says the event occurred. Null if not provided by the venue. |
| received_ts | When we read the raw message off the venue WebSocket. |
| published_ts | When the normalized message was published internally. |
| gateway_ts | When the gateway sent the message to your WebSocket. |

### Feed Catalog

## GET /feeds/catalog
List all available feed events, grouped by feed vertical. Returns event keys, venues, outcome counts, and pre-built channel names.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| feed | string | no | Filter by feed vertical. Default: all |

### Example
```bash
curl -H "X-API-Key: oddpool_..." \
  "https://api.oddpool.com/feeds/catalog?feed=macro"
```

### Response
```json
{
  "feeds": {
    "macro": {
      "description": "Cross-venue macro economic prediction markets",
      "events": [
        {
          "event_key": "fomc-2026-04-29",
          "title": "FOMC April 2026",
          "type": "fomc",
          "event_date": "2026-04-29",
          "status": "upcoming",
          "venues": ["kalshi", "polymarket"],
          "outcomes": 5,
          "channels": {
            "dist": "dist:fomc-2026-04-29",
            "book": "book:fomc-2026-04-29:{outcome_key}",
            "trade": "trade:fomc-2026-04-29:{outcome_key}",
            "snapshot": "snapshot:fomc-2026-04-29"
          }
        }
      ]
    }
  }
}
```

## GET /feeds/catalog/{event_key}
Get a single event with its full outcome list and per-outcome channel names. Use this to find the outcome_key values for book and trade subscriptions.

### Example
```bash
curl -H "X-API-Key: oddpool_..." \
  "https://api.oddpool.com/feeds/catalog/fomc-2026-04-29"
```

### Response
```json
{
  "event_key": "fomc-2026-04-29",
  "title": "FOMC April 2026",
  "type": "fomc",
  "feed": "macro",
  "event_date": "2026-04-29",
  "status": "upcoming",
  "outcomes": [
    {
      "outcome_key": "hold",
      "label": "Fed maintains rate",
      "venues": ["kalshi", "polymarket"],
      "channels": {
        "book": "book:fomc-2026-04-29:hold",
        "trade": "trade:fomc-2026-04-29:hold"
      }
    },
    {
      "outcome_key": "cut_25",
      "label": "Cut 25bps",
      "venues": ["kalshi", "polymarket"],
      "channels": {
        "book": "book:fomc-2026-04-29:cut_25",
        "trade": "trade:fomc-2026-04-29:cut_25"
      }
    }
  ],
  "channels": {
    "dist": "dist:fomc-2026-04-29",
    "snapshot": "snapshot:fomc-2026-04-29"
  }
}
```

### WebSocket Limits

| Tier | Connections | Events | Channels | Snapshots |
|------|-------------|--------|----------|-----------|
| Free | 1 | 2 | dist only | No |
| Pro | 3 | 10 | All | Yes |
| Premium | 10 | Unlimited | All | Yes |
| Enterprise | Unlimited | Unlimited | All | Yes |

### WebSocket Error Codes

| Code | Description |
|------|-------------|
| CHANNEL_NOT_ALLOWED | Your tier does not have access to this channel type. Free tier only supports `dist:` channels. |
| EVENT_LIMIT | Concurrent event subscription limit reached. Unsubscribe from an event to free up a slot. |
| CONNECTION_LIMIT | Maximum concurrent connections reached. Close an existing connection first. |

## Endpoints

### Whale Tracking (Pro)

## GET /whales/user/events
List all events you are currently tracking.

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/whales/user/events"
```

### Response
```json
{
  "tracked_events": [
    {
      "id": 65,
      "event_id": 65,
      "event_ticker": "KXBUNDESLIGAGAME-26JAN14KOEBMU",
      "event_title": "1. FC Cologne vs Bayern Munich",
      "platform": "kalshi",
      "whale_threshold_usd": 1000,
      "notify_on_whale_trade": true,
      "whale_count_24h": 12
    }
  ]
}
```

## GET /whales/user/feed
Get whale trades for all your tracked events.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| limit | integer | no | Max results (1-500). Default: 50 |
| offset | integer | no | Pagination offset. Default: 0 |
| start_date | datetime | no | Filter by start date (ISO 8601) |
| end_date | datetime | no | Filter by end date (ISO 8601) |
| min_trade_size | float | no | Minimum trade size in USD |
| platform | string | no | Filter by platform: kalshi, polymarket |
| event_id | integer | no | Filter to specific event |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/whales/user/feed?limit=10&platform=kalshi"
```

### Response
```json
{
  "trades": [
    {
      "id": 12345,
      "platform": "kalshi",
      "event_title": "1. FC Cologne vs Bayern Munich",
      "market_title": "Winner: Bayern Munich",
      "market_ticker": "KXBUNDESLIGAGAME-26JAN14KOEBMU-BMU",
      "outcome": "Bayern Munich",
      "timestamp": "2026-01-14T21:24:25Z",
      "taker_side": "yes",
      "trade_size_usd": 15000.00,
      "price": 0.78,
      "count": 1
    }
  ],
  "stats": {
    "total_volume_24h": 185195.0,
    "total_trades_24h": 151,
    "avg_trade_size": 1226.46
  },
  "pagination": {"limit": 10, "offset": 0, "total": 151}
}
```

## GET /whales/user/stats
Get aggregated statistics for all tracked events.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| period | string | no | Time period: 24h, 7d, all. Default: 24h |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/whales/user/stats?period=7d"
```

### Response
```json
{
  "period": "7d",
  "events": [
    {
      "event_id": 65,
      "event_ticker": "KXBUNDESLIGAGAME-26JAN14KOEBMU",
      "event_title": "1. FC Cologne vs Bayern Munich",
      "platform": "kalshi",
      "stats": {
        "trade_count": 151,
        "total_volume": 185195.0,
        "avg_trade_size": 1226.46,
        "market_count": 3
      },
      "markets": [...]
    }
  ]
}
```

## GET /whales/user/event/{event_id}
Get whale trades for a specific tracked event.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| event_id | integer | yes | Event ID (path) |
| limit | integer | no | Max results (1-500). Default: 50 |
| offset | integer | no | Pagination offset. Default: 0 |
| min_trade_size | float | no | Minimum trade size in USD |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/whales/user/event/65?limit=20"
```

## GET /whales/user/event/{event_id}/stats
Get statistics for a specific tracked event.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| event_id | integer | yes | Event ID (path) |
| period | string | no | Time period: 24h, 7d, all. Default: 24h |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/whales/user/event/65/stats?period=all"
```

### Response
```json
{
  "event_id": 65,
  "event_ticker": "KXBUNDESLIGAGAME-26JAN14KOEBMU",
  "event_title": "1. FC Cologne vs Bayern Munich",
  "platform": "kalshi",
  "period": "all",
  "stats": {
    "trade_count": 151,
    "total_volume": 185195.0,
    "avg_trade_size": 1226.46,
    "market_count": 3,
    "first_trade_at": "2026-01-14T19:51:59Z",
    "last_trade_at": "2026-01-14T21:24:25Z"
  },
  "markets": [
    {
      "market_ticker": "KXBUNDESLIGAGAME-26JAN14KOEBMU-BMU",
      "platform": "kalshi",
      "trade_count": 124,
      "total_volume": 156445.15,
      "avg_trade_size": 1261.65
    }
  ]
}
```

## GET /whales/user/markets
List all markets for your tracked events.

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/whales/user/markets"
```

### Response
```json
{
  "markets": [
    {
      "market_id": 370,
      "market_ticker": "KXBUNDESLIGAGAME-26JAN14KOEBMU-BMU",
      "market_title": "Winner: Bayern Munich",
      "event_id": 65,
      "event_title": "1. FC Cologne vs Bayern Munich",
      "platform": "kalshi",
      "whale_count_24h": 45
    }
  ],
  "total_markets": 3
}
```

## GET /whales/user/market/{market_id}/stats
Get statistics for a specific market.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| market_id | integer | yes | Market ID (path) |
| period | string | no | Time period: 24h, 7d, all. Default: 24h |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/whales/user/market/370/stats?period=all"
```

### Response
```json
{
  "market_id": 370,
  "market_ticker": "KXBUNDESLIGAGAME-26JAN14KOEBMU-BMU",
  "market_title": "Winner: Bayern Munich",
  "platform": "kalshi",
  "period": "all",
  "stats": {
    "period": "all",
    "trade_count": 124,
    "total_volume": 156445.15,
    "avg_trade_size": 1261.65,
    "first_trade_at": "2026-01-14T19:51:59Z",
    "last_trade_at": "2026-01-14T21:24:25Z"
  }
}
```

## GET /whales/user/market/{market_id}/trades
Get whale trades for a specific market.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| market_id | integer | yes | Market ID (path) |
| limit | integer | no | Max results (1-500). Default: 50 |
| offset | integer | no | Pagination offset. Default: 0 |
| min_trade_size | float | no | Minimum trade size in USD |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/whales/user/market/370/trades?limit=10"
```

### Arbitrage (Premium)

## GET /arbitrage/current
Find markets where buying YES on one venue and NO on another costs less than $1 combined. The gap is risk-free profit.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| min_net_cents | float | no | Minimum net profit after fees, in cents. Default: 0 |
| minutes | integer | no | Lookback window in minutes. Default: 10000 |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/arbitrage/current?min_net_cents=0.5&minutes=10"
```

### Response
```json
[
  {
    "event_id": 42,
    "event_title": "Fed rate decision March",
    "kalshi_event_ticker": "KXFEDDECISION-26MAR",
    "polymarket_event_slug": "fed-rate-march",
    "market_type": "binary",
    "outcome_key": "yes",
    "label": "25bps cut",
    "timestamp": "2026-03-11T14:30:00",
    "resolution_time": "2026-03-19T18:00:00",
    "kalshi": {
      "yes_ask": 0.42, "no_ask": 0.60,
      "volume": 150000, "volume_24h": 12000,
      "open_interest": 80000
    },
    "polymarket": {
      "yes_ask": 0.39, "no_ask": 0.63,
      "volume": 200000.0, "volume_24h": 15000.0,
      "liquidity": 50000.0
    },
    "buy_yes_market": "polymarket",
    "buy_no_market": "kalshi",
    "gross_cents": 1.0,
    "fee_cents": 0,
    "net_cents": 1.0
  }
]
```

## GET /arbitrage/current/difference
Find where venues disagree on the same outcome's price. A large spread signals potential mispricing.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| minutes | integer | no | Lookback window in minutes. Default: 10000 |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/arbitrage/current/difference?minutes=10"
```

### Response
```json
[
  {
    "event_id": 42,
    "event_title": "Fed rate decision March",
    "kalshi_event_ticker": "KXFEDDECISION-26MAR",
    "polymarket_event_slug": "fed-rate-march",
    "market_type": "binary",
    "outcome_key": "yes",
    "label": "25bps cut",
    "timestamp": "2026-03-11T14:30:00",
    "resolution_time": "2026-03-19T18:00:00",
    "side": "YES",
    "side1": "Kalshi",
    "side2": "Polymarket",
    "side1_price": 0.42,
    "side2_price": 0.39,
    "diff": 0.03
  }
]
```

### Search (Premium)

## GET /search/markets
Full-text search across all prediction markets with filtering and sorting.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| q | string | yes | Search query |
| exchange | string | no | Filter: kalshi or polymarket |
| status | string | no | Filter: active or closed. Default: active |
| category | string | no | Filter by category |
| min_volume | integer | no | Minimum volume |
| min_liquidity | integer | no | Minimum liquidity |
| sort_by | string | no | relevance, newest, volume, or liquidity. Default: relevance |
| discovered_after | string | no | ISO timestamp filter. Tip: use this to poll for new market listings |
| limit | integer | no | Max results (1-100). Default: 20 |
| offset | integer | no | Pagination offset. Default: 0 |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/search/markets?q=fed+rate&exchange=kalshi&sort_by=volume"
```

### Response
```json
[
  {
    "market_id": "KXFEDDECISION-26MAR-T4.75",
    "exchange": "kalshi",
    "question": "Will the Fed cut rates by 25bps in March?",
    "category": "economics",
    "status": "active",
    "volume": 150000,
    "liquidity": 80000,
    "last_yes_price": "0.42",
    "last_no_price": "0.60",
    "has_orderbook": true,
    "event_id": "KXFEDDECISION-26MAR",
    "event_title": "Fed Rate Decision March 2026",
    "slug": null,
    "discovered_at": "2026-02-15T10:00:00"
  }
]
```

## GET /search/events
Search across prediction market events. An event like 'Fed Rate Decision March' contains markets for each possible outcome.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| q | string | yes | Search query |
| exchange | string | no | Filter: kalshi or polymarket |
| status | string | no | Filter: active or closed. Default: active |
| category | string | no | Filter by category |
| sort_by | string | no | relevance, newest, markets, volume, or liquidity. Default: relevance |
| discovered_after | string | no | ISO timestamp filter |
| limit | integer | no | Max results (1-100). Default: 20 |
| offset | integer | no | Pagination offset. Default: 0 |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/search/events?q=election&sort_by=volume"
```

### Response
```json
[
  {
    "event_id": "KXPRESIDENTIAL-28NOV",
    "exchange": "kalshi",
    "title": "2028 Presidential Election",
    "category": "politics",
    "status": "active",
    "discovered_at": "2026-01-10T08:00:00",
    "market_count": 12,
    "total_volume": 5000000,
    "total_liquidity": 1200000,
    "market_questions": [
      "Will the Democratic nominee win?",
      "Will the Republican nominee win?"
    ]
  }
]
```

## GET /search/recent/markets
Latest market listings. Useful for new-listing alerts without a search query.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| exchange | string | no | Filter: kalshi or polymarket |
| limit | integer | no | Max results (1-100). Default: 30 |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/search/recent/markets?limit=10"
```

## GET /search/recent/events
Latest event listings. Useful for new-listing alerts without a search query.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| exchange | string | no | Filter: kalshi or polymarket |
| limit | integer | no | Max results (1-100). Default: 30 |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/search/recent/events?exchange=polymarket"
```

## GET /search/events/{event_id}/markets
List all markets under one event. Use after finding an event via search to see every tradeable outcome.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| event_id | string | yes | Event ID (path) |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/search/events/KXFEDDECISION-26MAR/markets"
```

### Kalshi Historical (Free)

## GET /historical/kalshi/orderbook
Full orderbook snapshots with YES bids, NO bids, and derived best bid/ask. Data available from March 19, 2026. ~1hr lag from real-time.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| market_id | string | yes | Kalshi market ticker (e.g. KXFEDDECISION-26APR-H0) |
| start_time | integer | no | Start time in Unix ms. Omit with end_time for latest. |
| end_time | integer | no | End time in Unix ms. Omit with start_time for latest. |
| granularity | string | no | 1m (default) or 5m |
| limit | integer | no | Max rows per page (1-200). Default: 100 |
| pagination_key | string | no | Cursor from previous response |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/historical/kalshi/orderbook?market_id=KXFEDDECISION-26APR-H0&start_time=1774015200000&end_time=1774018800000&limit=5"
```

### Response
```json
{
  "snapshots": [
    {
      "market_id": "KXFEDDECISION-26APR-H0",
      "timestamp": 1774015256106,
      "yes_bids": [{"price": "0.9400", "size": 12500.0}],
      "no_bids": [{"price": "0.0600", "size": 21.0}],
      "best_yes_bid": 0.94,
      "best_yes_ask": 0.94,
      "mid": 0.94,
      "spread": 0.0
    }
  ],
  "pagination": {"limit": 5, "count": 5, "has_more": true, "pagination_key": "eyJo..."}
}
```

## GET /historical/kalshi/top-of-book
Best bid/ask timeseries without full level arrays. Ideal for charting price history. Data from March 19, 2026.

### Parameters
Same as /historical/kalshi/orderbook.

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/historical/kalshi/top-of-book?market_id=KXFEDDECISION-26APR-H0&start_time=1774015200000&end_time=1774018800000&granularity=5m"
```

### Response
```json
{
  "snapshots": [
    {
      "market_id": "KXFEDDECISION-26APR-H0",
      "timestamp": 1774015256106,
      "best_yes_bid": 0.94,
      "best_yes_ask": 0.94,
      "mid": 0.94,
      "spread": 0.0
    }
  ],
  "pagination": {...}
}
```

## GET /historical/kalshi/trades
Every trade execution on a Kalshi market. Kalshi only surfaces taker buys. Data from March 19, 2026.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| market_id | string | yes | Kalshi market ticker |
| start_time | integer | no | Start time in Unix ms |
| end_time | integer | no | End time in Unix ms |
| limit | integer | no | Max rows per page (1-200). Default: 100 |
| pagination_key | string | no | Cursor from previous response |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/historical/kalshi/trades?market_id=KXFEDDECISION-26APR-H0&start_time=1774015200000&end_time=1774018800000"
```

### Response
```json
{
  "trades": [
    {
      "market_id": "KXFEDDECISION-26APR-H0",
      "timestamp": 1774015436710,
      "taker_side": "yes",
      "price": "0.9500",
      "size": 105.0,
      "trade_id": "4bd8859f-eeaf-685e-e4b5-e9f17516b89c"
    }
  ],
  "pagination": {...}
}
```

### Polymarket Historical (Free)

## GET /historical/polymarket/orderbook
Full orderbook snapshots with bids/asks per token. Data available from March 20, 2026. ~1hr lag from real-time. Returns both YES and NO tokens unless filtered by asset_id.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| market_id | string | yes | Polymarket condition ID (0x...) |
| asset_id | string | no | Filter by token ID. Omit for both YES and NO. |
| start_time | integer | no | Start time in Unix ms. Omit with end_time for latest. |
| end_time | integer | no | End time in Unix ms. Omit with start_time for latest. |
| granularity | string | no | 1m (default) or 5m |
| limit | integer | no | Max rows per page (1-200). Default: 100 |
| pagination_key | string | no | Cursor from previous response |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/historical/polymarket/orderbook?market_id=0x36e8ca24...&start_time=1774015200000&end_time=1774018800000&limit=5"
```

### Response
```json
{
  "snapshots": [
    {
      "asset_id": "56914066788195652124...",
      "market_id": "0x00000977017fa72fb6b1...",
      "timestamp": 1774026026396,
      "bids": [{"price": "0.987", "size": 5000.0}],
      "asks": [{"price": "0.990", "size": 2100.0}],
      "best_bid": 0.987,
      "best_ask": 0.99,
      "mid": 0.9885,
      "spread": 0.003
    }
  ],
  "pagination": {"limit": 5, "count": 5, "has_more": true, "pagination_key": "eyJo..."}
}
```

## GET /historical/polymarket/top-of-book
Best bid/ask timeseries per token without full level arrays. Data from March 20, 2026.

### Parameters
Same as /historical/polymarket/orderbook.

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/historical/polymarket/top-of-book?market_id=0x36e8ca24...&asset_id=56914066...&granularity=5m"
```

### Response
```json
{
  "snapshots": [
    {
      "asset_id": "56914066788195652124...",
      "market_id": "0x00000977017fa72fb6b1...",
      "timestamp": 1774026026396,
      "best_bid": 0.987,
      "best_ask": 0.99,
      "mid": 0.9885,
      "spread": 0.003
    }
  ],
  "pagination": {...}
}
```

## GET /historical/polymarket/trades
Trade executions on a Polymarket market. Can be BUY or SELL. Use asset_id to filter to a specific token. Data from March 20, 2026.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| market_id | string | yes | Polymarket condition ID (0x...) |
| asset_id | string | no | Filter by token ID |
| start_time | integer | no | Start time in Unix ms |
| end_time | integer | no | End time in Unix ms |
| limit | integer | no | Max rows per page (1-200). Default: 100 |
| pagination_key | string | no | Cursor from previous response |

### Example
```bash
curl -H "X-API-Key: your_api_key" \
  "https://api.oddpool.com/historical/polymarket/trades?market_id=0x36e8ca24...&start_time=1774015200000&end_time=1774018800000"
```

### Response
```json
{
  "trades": [
    {
      "asset_id": "56914066788195652124...",
      "market_id": "0x00000977017fa72fb6b1...",
      "timestamp": 1774020951044,
      "side": "BUY",
      "price": "0.987",
      "size": 1.317,
      "transaction_hash": "0x554c0b25544baa5f...",
      "fee_rate_bps": "0"
    }
  ],
  "pagination": {...}
}
```