Skip to content
OddsHouse.io

Documentation

Three calls to a live board.

The full reference is generated from the API's own contract and served by the API, so it cannot drift from the code. This page is the quick start, the limits, and how the account works.

Before the first call

Get a key.

  1. 1

    Sign up

    An email address and a password. Free during the beta, no card.

  2. 2

    Create a key

    Dashboard → API keys → Create. The key is shown exactly once: copy it then. A label tells keys apart.

  3. 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. 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 oddshouse.io/app after signing in.

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.

Quick start

Authenticate, read, follow.

STEP 1

Authenticate

Every call starts with https://api.oddshouse.io/v1. Send the key in a header; the ?key= form exists for WebSocket clients that cannot set headers. Keep keys out of shared URLs.

terminal
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"

/v1/me answers with your plan, which is exactly what the feed will let you see:

response
{
  "customer": "cus_3f9a1c27b84e5d60",
  "usage": "/v1/account/usage",
  "plan": {
    "id": "beta",
    "leagues": "*",
    "books": "*",
    "props": true,
    "rateLimitPerMin": 1200,
    "maxAltLines": null
  }
}

STEP 2

Read the board

List events for a league, then fetch one event's odds map. Every snapshot carries asOf and the stream cursor it reflects.

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

STEP 3

Follow the stream

Open the socket, optionally subscribe to a narrower scope, and apply every frame whose cursor is after your snapshot's. Remember the last cursor: sockets are recycled every 10 minutes, and a reconnect with it resumes exactly where you were.

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();

Reading a price

Three rules that prevent most integration bugs.

  1. 1

    price is decimal

    american is the same price as a string. price: null means no usable price. It is never 0.

  2. 2

    status is separate

    OPEN, SUSPENDED or CLOSED. A price on a suspended selection is display-only.

  3. 3

    the line is per book

    byBookmaker.<book>.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.

Identity

The odd id.

points
statID
the stat, or the market
-
all
statEntityID
home · away · all · a player id
-
game
periodID
full game, a half, a map
-
ou
betTypeID
ml · ml3way · sp · ou · yn
-
over
sideID
home · away · draw · over · under

The same id on every book. The line is deliberately not part of it: it lives in each book's cell as overUnder or spread, because two books can sit on different lines for the same odd, and the ladder beneath a main line belongs to that book alone.

Endpoints

Everything under /v1.

MethodPathReturns
GET/v1/meYour key's customer and the plan it is checked against.
GET/v1/account/usageToday's requests by key and endpoint, the rate-limit bucket, the sockets open on the serving process.
GET/v1/eventsThe board: one summary row per event, cursor-paginated, filterable by league, book, phase, date.
GET/v1/events/:idOne event's flat odds map and its players: every odd, each book's main line; the ladders with includeAltLines=true.
GET/v1/oddsOdds 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/propsThe 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/schedulesUpcoming events without prices, with the books already pricing them.
GET/v1/changesThe change log over HTTP, from a cursor, for clients that poll instead of holding a socket.
GET/v1/leagues · /v1/books · /v1/stats · /v1/marketsReference: 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 · /eventsOur ids to external ones (balldontlie, ESPN, Sportradar …) and back with external=source:id. Player ids embed the balldontlie id: nfl_p_738.
WS/v1/updatesThe stream: hello, subscribe, one frame per change, resume by cursor and epoch.
GET/v1/docsThe reference itself: OpenAPI, llms.txt, guides and real example responses. Public, no key.

The stream

Every frame the socket sends.

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.

Limits

What a client runs into.

The numbers are the beta's, the same for every account; your dashboard shows the plan your key is checked against.

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.

Errors

Every status, and what to do.

A plain JSON body with an error string. A plan never answers 403: what it does not include is left out.

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.

For AI agents

Point your coding agent here.

Two plain-text files on this site follow the llms.txt convention: a short index, and the whole integration guide in one file (the key, the base URL, the limits, the price rules, the endpoints, the stream and its reconnect model, the coverage, working samples). Paste either into an agent, or give it the URL.

Status

When something breaks.

There is no public status page yet; incidents are reported by email to every account. Something looks wrong on your side? Write to support@oddshouse.io with 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.

Join the beta. Tell us what to fix.

Every league, every sportsbook, player props and the stream, free for every account while we polish the feed. The key you get today is the key you keep.