llms.txt
Compare with other sites' llms.txt files →# 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"
```
### 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": {...}
}
```