# 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"}`

## 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"
```