# OddsHouse API: the integration guide > Real-time sportsbook odds API: normalized prices from 25 sportsbooks across 20 leagues over REST and WebSocket, with player props, alternate ladders and deep links back to the bet slip. OddsHouse is in a free beta. Every account gets, at no cost and with no card: every league, every sportsbook; player props; full alternate ladders; 1,200 requests / min; real-time stream, 3 connections; 15-minute resume window; live (in-play) markets; deep links. This file is the whole guide in one place. The full reference, page by page, is served by the API: https://api.oddshouse.io/v1/llms.txt (public, no key). - Base URL: https://api.oddshouse.io/v1 (REST) and wss://api.oddshouse.io/v1/updates (the stream) - Auth: the header `x-api-key: ` or `Authorization: Bearer `; a WebSocket client may pass `?key=` - Keys: sign up at https://oddshouse.io/sign-up, then Dashboard → API keys → Create; the key is shown once - Prices: `price` is decimal and `american` the same price as a string; `price: null` means no usable price, never 0 ## 1. Get a key 1. **Sign up**: An email address and a password. Free during the beta, no card. 2. **Create a key**: Dashboard → API keys → Create. The key is shown exactly once: copy it then. A label tells keys apart. 3. **Keep it secret**: In an environment variable (ODDSHOUSE_KEY) on a server, never in a browser bundle or a shared URL. Revoke a leaked key in one click. 4. **Call the API**: https://api.oddshouse.io/v1, with the key in x-api-key or Authorization: Bearer. The WebSocket also takes ?key=. The dashboard, at https://oddshouse.io/app: - **Overview**: Your plan as the feed enforces it, your keys, today's requests and the last 24 hours of frames and data. - **API keys**: Create (shown once), label and revoke keys; up to 5 live at a time. Only a key's prefix is shown afterwards. - **Usage**: Requests today by endpoint and by key, and the last 24 hours by the hour. The live bucket and open sockets: GET /v1/account/usage with the key. - **Send feedback**: A link to support@oddshouse.io: what broke, what is missing. The event id, the book and the time in UTC make a report useful. ## 2. Authenticate Authenticate (terminal): ```bash API=https://api.oddshouse.io/v1 # any of the three; the header forms keep the key out of logs curl -H "Authorization: Bearer $ODDSHOUSE_KEY" $API/me curl -H "x-api-key: $ODDSHOUSE_KEY" $API/me curl "$API/me?key=$ODDSHOUSE_KEY" ``` `GET /v1/me` answers with the plan your key is checked against: /v1/me (response): ```json { "customer": "cus_3f9a1c27b84e5d60", "usage": "/v1/account/usage", "plan": { "id": "beta", "leagues": "*", "books": "*", "props": true, "rateLimitPerMin": 1200, "maxAltLines": null } } ``` ## 3. Limits - **Requests**: 1,200 a minute per key during the beta: a token bucket refilled continuously, so a burst can spend it at once. Every response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (seconds); over it, 429 with Retry-After. - **Sockets**: 3 concurrent connections during the beta. One more is refused with 429 before the upgrade; close one you no longer read. - **Socket lifetime**: A socket is closed after at most 10 minutes, without a close frame (1006 on most clients). Reconnect at once with resume_from and epoch: nothing is lost. - **Resume window**: About 15 minutes. An older cursor gets resync_required: take fresh snapshots and apply frames after their cursor. - **Restarts**: While the feed restarts (about 100 s per deploy) REST and the socket upgrade answer 503 with Retry-After: 5. Honour it; a resume across a restart replays exactly what moved. - **Keys**: Up to 5 live keys per account, issued and revoked in the dashboard. A key is shown once; we keep only its hash. ## 4. Reading a price 1. **price is decimal**: american is the same price as a string. price: null means no usable price. It is never 0. 2. **status is separate**: OPEN, SUSPENDED or CLOSED. A price on a suspended selection is display-only. 3. **the line is per book**: byBookmaker..overUnder (or .spread) is that book's main line; its other lines come in altLines with includeAltLines=true. Two books on one odd can sit on different lines. Every odd has one id on every book, `{statID}-{statEntityID}-{periodID}-{betTypeID}-{sideID}`, for example `points-all-game-ou-over`: - `points` is the statID: the stat, or the market - `all` is the statEntityID: home · away · all · a player id - `game` is the periodID: full game, a half, a map - `ou` is the betTypeID: ml · ml3way · sp · ou · yn - `over` is the sideID: home · away · draw · over · under The line is not part of the id: it lives in each book's cell (`overUnder` or `spread`), because two books can price the same odd at different lines. ## 5. Endpoints | method | path | returns | |---|---|---| | GET | `/v1/me` | Your key's customer and the plan it is checked against. | | GET | `/v1/account/usage` | Today's requests by key and endpoint, the rate-limit bucket, the sockets open on the serving process. | | GET | `/v1/events` | The board: one summary row per event, cursor-paginated, filterable by league, book, phase, date. | | GET | `/v1/events/:id` | One event's flat odds map and its players: every odd, each book's main line; the ladders with includeAltLines=true. | | GET | `/v1/odds` | Odds across many events, 50 to a page: the main game lines by default, every market with main=false; by league, day, oddID or book. | | GET | `/v1/props` | The player-prop screener: one row per event, player and stat with each book's main line; stat takes the canonical id (RECEIVING_YARDS); sort by start, gap, moved or books. | | GET | `/v1/schedules` | Upcoming events without prices, with the books already pricing them. | | GET | `/v1/changes` | The change log over HTTP, from a cursor, for clients that poll instead of holding a socket. | | GET | `/v1/leagues · /v1/books · /v1/stats · /v1/markets` | Reference: leagues and their live coverage, the books and what each prices, stat ids, every oddID pattern. Also /v1/sports, /v1/periods, /v1/bet-types, /v1/tournaments. | | GET | `/v1/mappings/players · /teams · /events` | Our ids to external ones (balldontlie, ESPN, Sportradar …) and back with external=source:id. Player ids embed the balldontlie id: nfl_p_738. | | WS | `/v1/updates` | The stream: hello, subscribe, one frame per change, resume by cursor and epoch. | | GET | `/v1/docs` | The reference itself: OpenAPI, llms.txt, guides and real example responses. Public, no key. | Lists share one envelope, `{ asOf, cursor, total, : [...], nextCursor }`: pass `nextCursor` back as the query `cursor` for the next page. `asOf` is Unix milliseconds; `cursor` is the stream position the snapshot reflects. ## 6. Read the board curl (terminal): ```bash # The NFL board: one summary row per event, # stamped with the stream cursor it reflects curl "https://api.oddshouse.io/v1/events?league=nfl&limit=50" \ -H "x-api-key: $ODDSHOUSE_KEY" # One event: the flat odds map keyed by oddID, # every book inside each odd curl "https://api.oddshouse.io/v1/events/evt_2f9c1e" \ -H "x-api-key: $ODDSHOUSE_KEY" # The player-prop screener: one row per (player, stat), # widest gap between books first curl "https://api.oddshouse.io/v1/props?league=nfl&shared=1&sort=gap" \ -H "x-api-key: $ODDSHOUSE_KEY" ``` JavaScript (board.mjs): ```js const API = "https://api.oddshouse.io/v1"; const headers = { "x-api-key": process.env.ODDSHOUSE_KEY }; const get = (p) => fetch(API + p, { headers }).then((r) => r.json()); // 1. Snapshot the board; remember the cursor it reflects const board = await get("/events?league=nfl"); console.log(board.total, "events, cursor", board.cursor); // 2. One event: every book's main line, per odd (the ladders: ?includeAltLines=true) const ev = await get(`/events/${board.events[0].id}`); const total = ev.odds["points-all-game-ou-over"]; // the LINE is per book: two books can sit on different totals for (const [book, cell] of Object.entries(total.byBookmaker)) { console.log(book, cell.overUnder, cell.price, cell.american, cell.status); } ``` Python (screener.py): ```python import os, requests API = "https://api.oddshouse.io/v1" headers = {"x-api-key": os.environ["ODDSHOUSE_KEY"]} # one row per (event, player, stat); each book brings its own main line. # stat is the canonical id (RECEIVING_YARDS); a lowercase one matches nothing params = {"league": "nfl", "stat": "RECEIVING_YARDS", "shared": 1, "sort": "gap"} rows = requests.get(f"{API}/props", headers=headers, params=params).json() for r in rows["rows"][:10]: cells = [(b, c) for b, c in r["byBookmaker"].items() if c["price"]] book, best = max(cells, key=lambda bc: bc[1]["price"]) print(r["player"], r["stat"], best["overUnder"], best["price"], book) ``` ## 7. Follow the stream Connect to `wss://api.oddshouse.io/v1/updates?key=` (or send the key in a header on the upgrade request). The frames: - **hello**: First frame. Your plan, the schema version, the stream epoch and cursor, the connection id, the outcome of any resume. - **subscribed**: Reply to subscribe. The effective scope after intersecting with the plan, and what was dropped. - **subscribe_rejected**: A subscribe sent while a resume or another subscribe was still running. Wait for resumed or subscribed, send it again. - **line_update**: One price or status change: oddID, book, line, prev, price, dir, main, deep link, ts_received, ts_broadcast. - **score_update**: A live score changed: home and away score, period, clock, which book reported it. - **updates**: With batch=1: a burst of frames as one message, every cursor kept, nothing coalesced. - **cursor**: After 10 seconds of silence: the stream is alive and this is the newest cursor. No odds; adopt the cursor. - **resumed**: The replay after resume_from is complete; what follows is live. - **resync_required**: The cursor could not be honoured or continuity was lost. Snapshot again, then apply frames after its cursor. By default the socket carries each book's main line only (`"main": true`). `includeAltLines=true` on the URL, or `"alt_lines": true` in a subscribe, sends every rung of each ladder (alternates arrive with `"main": false`). A connection that never subscribes gets everything the plan permits; a subscribe narrows it, and the reply names what the plan dropped: ```json { "action": "subscribe", "filters": { "leagues": ["nfl", "nba"], "books": ["fanduel", "draftkings"], "market_groups": ["core", "player_props"], "events": ["evt_…"], "alt_lines": false }, "resume_from": "", "epoch": "" } ``` Reconnecting: remember the last `cursor` you applied and the hello's `epoch`, and reconnect with `resume_from` and `epoch` (on the URL, or in the subscribe message so the replay follows the subscription). The hello's `resume` says how it went: `ok: true` replays what you missed and then sends `resumed`; `ok: false` sends `resync_required`, after which you take fresh REST snapshots and apply only frames whose cursor is after theirs. Merging a stream into a snapshot: a frame whose cursor is after the snapshot's is news, one at or before it is already in it. WebSocket (stream.mjs): ```js import WebSocket from "ws"; const URL = "wss://api.oddshouse.io/v1/updates"; let epoch = null, cursor = null; function connect() { const key = process.env.ODDSHOUSE_KEY; const ws = new WebSocket(`${URL}?key=${key}`); ws.on("open", () => ws.send(JSON.stringify({ action: "subscribe", filters: { leagues: ["nfl"], books: ["draftkings", "fanduel"], market_groups: ["player_props"], }, // after a reconnect: replay exactly what was missed ...(cursor && { resume_from: cursor, epoch }), }))); ws.on("message", (raw) => { const frame = JSON.parse(raw); if (frame.action === "hello") epoch = frame.data.epoch; if (frame.cursor) cursor = frame.cursor; if (frame.action === "line_update") { const { book, player, market, prev, price } = frame.data; console.log(book, player ?? market.type, prev, "->", price); } if (frame.action === "resync_required") snapshotAgain(); }); // sockets are recycled every 10 minutes: reconnect and resume ws.on("close", () => setTimeout(connect, 500)); } connect(); ``` A frame (line_update): ```json { "action": "line_update", "cursor": "1788567054564-1", "data": { "oddID": "receiving_yards-nfl_p_13874014-game-ou-over", "event_id": "evt_99d63497f63d", "league": "nfl", "book": "draftkings", "home": "Cincinnati Bengals", "away": "Jacksonville Jaguars", "market": { "type": "PLAYER_PROP", "period": "FULL_GAME", "line": 10.5, "stat": "RECEIVING_YARDS" }, "selection": { "type": "OVER", "line": 10.5 }, "player": "Bhayshul Tuten", "price": 1.87, "prev": 1.91, "dir": "down", "status": "OPEN", "main": true, "deeplink": "https://sportsbook.draftkings.com/...", "ts_received": 1788567054512, "ts_broadcast": 1788567054564 } } ``` ## 8. Errors Errors are plain JSON, `{ "error": "…" }`. A plan never answers 403: what it does not include is left out of the board. - **400**: Invalid query, cursor or input. Fix it from the endpoint's parameter table; do not retry unchanged. - **401**: Missing, unknown, revoked or suspended key. Check where the key is sent and the account's state. - **404**: Unknown route or event, or an event outside your plan. The body's hint names the index. - **405**: Anything but GET or HEAD: every /v1 route is read-only. - **410**: The change history cannot reach your cursor any more. Take a fresh snapshot and resume from its cursor. - **429**: Request rate or socket allowance used up. Honour Retry-After; close a socket you no longer read. - **500**: Unexpected. Retry with backoff; report the route and the time if it persists. - **503**: The feed is restoring after a restart. Honour Retry-After (5 s) and retry. ## 9. Coverage Leagues (20), by sport, as `id` (name): - Football: `nfl` (NFL), `ncaaf` (NCAA Football) - Basketball: `nba` (NBA), `ncaab` (NCAA Basketball), `wnba` (WNBA) - Baseball: `mlb` (MLB) - Hockey: `nhl` (NHL) - Soccer: `epl` (Premier League), `laliga` (La Liga), `seriea` (Serie A), `bundesliga` (Bundesliga), `ligue1` (Ligue 1), `efl` (EFL Championship), `ucl` (Champions League), `uel` (Europa League), `mls` (MLS) - Esports: `cs2` (Counter-Strike 2), `lol` (League of Legends), `dota2` (Dota 2), `valorant` (Valorant) Sportsbooks (25), by region: - United States: `draftkings` (DraftKings), `fanduel` (FanDuel), `betmgm` (BetMGM), `caesars` (Caesars), `fanatics` (Fanatics), `betrivers` (BetRivers), `hardrock` (Hard Rock Bet), `espnbet` (ESPN Bet), `circa` (Circa Sports), `fliff` (Fliff), `underdog` (Underdog), `prizepicks` (PrizePicks), `prophetx` (ProphetX), `kalshi` (Kalshi) - UK & Ireland: `bet365` (bet365), `williamhill` (William Hill), `888sport` (888sport) - Europe: `bwin` (bwin) - Sharp & offshore: `bet105` (Bet105), `betus` (BetUS), `heritage` (Heritage Sports) - Crypto: `stake` (Stake), `cloudbet` (Cloudbet), `sportsbet` (Sportsbet.io), `thunderpick` (Thunderpick) This is what the feed collects; `GET /v1/leagues` and `GET /v1/books` report what is live on the board right now. ## 10. Help Write to support@oddshouse.io. A useful report names the endpoint or the frame, the event id, the book and the time in UTC; for a socket, the connection id from its hello frame. ## 11. Reference - [OpenAPI document](https://api.oddshouse.io/v1/openapi.json): generated from the contract types; the source of truth - [API index for agents](https://api.oddshouse.io/v1/llms.txt): every endpoint page, data type and example, with sizes - [WebSocket guide](https://api.oddshouse.io/v1/docs/endpoints/get-v1-updates.md): frames, subscriptions, the reconnect model, limits - [Odd ids](https://api.oddshouse.io/v1/docs/data-types/odd-ids.md): the five-part grammar and every vocabulary - [Leagues and books](https://api.oddshouse.io/v1/docs/data-types/books.md): every book's id and the leagues it is collected for - [Errors](https://api.oddshouse.io/v1/docs/errors.md): every non-200 body and what to do about it