Getting started

Odds337 API

Live prices from every book we carry, lined up by event, market and selection, over REST and WebSocket.

Vibe coding?

Building with Claude Code, Cursor or another AI assistant? Paste this at the top of your CLAUDE.md, AGENTS.md or .cursorrules and your assistant will call the API the right way from the first prompt.

CLAUDE.md

## Odds337 API

Live sports odds from every bookmaker and exchange Odds337 carries, lined up by event, market and selection.

- Base URL: https://api.b337.ai/odds/v1
- Auth: send `X-API-Key: <key>` on every request (`demo` = the Free plan, for trying it: tier-1 books, main markets, 10 requests/min).
- WebSocket: wss://api.b337.ai/odds/v1/ws (key in the header or `?api_key=`).
- Docs: https://www.b337.bet/odds-api/docs
- OpenAPI 3.1: https://api.b337.ai/odds/v1/openapi.json and AsyncAPI 3.0 (WebSocket): https://api.b337.ai/odds/v1/asyncapi.json. No key needed; read them or generate a typed client from them instead of guessing shapes.

Endpoints
- GET /sports and GET /books: what we cover (free).
- GET /teams?sport=&league= and GET /players?sport=|league=&team=&q=: reference data with logos and headshots (free). `team_id` = `<sport>:<slug>`, `player_id` = `<roster>:<source>:<id>`; store them. Image URLs (`logo_url`, `headshot_url`, under /media/) need no key and may be null.
- GET /events?sport=&league=&date=&status=: list events, finished ones too (give date or since/until, up to 31 days). Use the returned `event_id` as is; never build one yourself. Each event carries `competitors` (`id`, `name`, `side`, `logo_url`).
- GET /odds?event_id=&markets=&books=&format=decimal|american|fractional: prices per market, per selection, per book. A finished event returns its closing card (`close_odds`, `closed_at`, `fair_odds`).
- GET /scores?event_id=: one event's score (1 token; Business and up). NBA, NHL, MLB, NFL, AFL, NRL, MLS, A-League, EPL, LaLiga, Serie A, Bundesliga, Ligue 1, UCL, UEL only; any other league answers `score: null` with a `reason`. `score` also rides /events and /odds, and finished /odds selections carry `result` (won/lost/push, or absent when not graded).
- GET /history?event_id=&market=&book=: one market's price moves per book (book required, up to 5; 2 tokens; not on the demo key).
- GET /clv?event_id=&selection_key=&book=&odds=: closing line value of a price taken (1 token; not on the demo key). POST /clv takes up to 100 bets (1 token per distinct event; no demo). `clv_pct` = (taken/close - 1) * 100; null plus a `close_reason`/`fair_reason` when it cannot be computed.
- GET /racing/meetings?date=&country=&race_type=: one race day's meetings and races (1 token; demo key ok: next 3 races to go). Use the returned `race_id` as is.
- GET /racing/race?race_id=&books=: every book's fixed win/place price per runner (each with `changed_at`), Betfair back/lay, and the result once TAB has one (1 token; the demo key gets the next 3 races, tier-1 win prices only). Race status is Betfair's (`betfair_status`, `in_play`), never the clock. Runners carry TAB tote approximates (`tote.nsw`/`tote.vic` win and place), the race has `tote_pools`, and the result has `dividends`, each present once TAB has published them. 
- GET /racing/history?race_id=&book=: each book's win/place moves for a race (book required, up to 5; 2 tokens; not on the demo key).
- GET /usage: tokens used and left this month.

Rules
- JSON is snake_case and every time is UTC ISO-8601. Odds are decimal unless you ask for `format`.
- A selection is identified by `selection_key`, never by its name; it is the same on /odds and /history, live or finished.
- A missing price means that book does not price it right now. Never fill it in.
- Every metered call costs tokens: read the `X-Tokens-*` headers. 402 = out of tokens, 429 = slow down and obey `Retry-After`. WebSocket streaming spends no tokens (included on Business: up to 50 live events, 3 connections; Enterprise: 500 / 20).
- Each price carries `updated_at`; books refresh at different speeds, so check its age before you act on it. A book with `stale: true` has stopped refreshing that event: its prices are still served, but treat them with care.
- WebSocket: keep the last `seq` per event and the `server_epoch` from `hello`; after a drop, subscribe again with `resume` (a `snapshot_required` frame means replace your state). Enable permessage-deflate: snapshots shrink to about 13%.
- On Business and up, /odds adds `model_odds` and `model_source` per selection and `edge_pct` per book price: the 337 model price. Pinnacle's de-vigged price, else Sportsbet's. Absent (never null) where neither prices a complete market; handicaps never have one.
- `open_odds` is the first price we recorded, `close_odds` the last before the off (`fair_odds`: pinnacle's close, margin removed); `books[book].url` opens that book's event page.

What you get

One request returns a single event priced by every book that lists it: bookmakers and exchanges side by side, each price lined up under the same market key and selection key, with when we last read that book.

A catalogue of sports, leagues and events (/sports, /events).
Per-book prices per market and selection (/odds), with the opening and closing price and a link to the book's own event page.
History: finished events, their closing prices and per-book price moves back to August 2026.
Horse, greyhound and harness racing: meetings, every book's fixed prices, Betfair and the result on /racing/race, and per-book price moves.
Closing line value for any price you took, and OpenAPI and AsyncAPI specs to generate a typed client.
A WebSocket that pushes each price change as soon as we see it.

Base URL

Every REST path in these docs is relative to:

https://api.b337.ai/odds/v1

The WebSocket is wss://api.b337.ai/odds/v1/ws. Try it now without signing up, using the public demo key:

curl -s "https://api.b337.ai/odds/v1/sports" -H "X-API-Key: demo"

Conventions

Format: JSON, snake_case, UTF-8. Responses over 1KB are gzipped when you send Accept-Encoding: gzip.
Times: ISO-8601 UTC, seconds precision, Z suffix (2026-10-04T09:30:00Z).
Odds: decimal, stake included (2.10 returns 2.10 per 1 staked), unless you ask for American or fractional.
Stability: fields documented here are stable within v1. New fields may be added; ignore fields you do not know. schema_version on odds bodies and the WebSocket hello changes only for a breaking change.

Next steps

Quickstart: a live price comparison in three calls.
Tokens & pricing: what each call costs.
Create an account to get your own key.

Vibe coding?

CLAUDE.md

## Odds337 API

Live sports odds from every bookmaker and exchange Odds337 carries, lined up by event, market and selection.

- Base URL: https://api.b337.ai/odds/v1
- Auth: send `X-API-Key: <key>` on every request (`demo` = the Free plan, for trying it: tier-1 books, main markets, 10 requests/min).
- WebSocket: wss://api.b337.ai/odds/v1/ws (key in the header or `?api_key=`).
- Docs: https://www.b337.bet/odds-api/docs
- OpenAPI 3.1: https://api.b337.ai/odds/v1/openapi.json and AsyncAPI 3.0 (WebSocket): https://api.b337.ai/odds/v1/asyncapi.json. No key needed; read them or generate a typed client from them instead of guessing shapes.

Endpoints
- GET /sports and GET /books: what we cover (free).
- GET /teams?sport=&league= and GET /players?sport=|league=&team=&q=: reference data with logos and headshots (free). `team_id` = `<sport>:<slug>`, `player_id` = `<roster>:<source>:<id>`; store them. Image URLs (`logo_url`, `headshot_url`, under /media/) need no key and may be null.
- GET /events?sport=&league=&date=&status=: list events, finished ones too (give date or since/until, up to 31 days). Use the returned `event_id` as is; never build one yourself. Each event carries `competitors` (`id`, `name`, `side`, `logo_url`).
- GET /odds?event_id=&markets=&books=&format=decimal|american|fractional: prices per market, per selection, per book. A finished event returns its closing card (`close_odds`, `closed_at`, `fair_odds`).
- GET /scores?event_id=: one event's score (1 token; Business and up). NBA, NHL, MLB, NFL, AFL, NRL, MLS, A-League, EPL, LaLiga, Serie A, Bundesliga, Ligue 1, UCL, UEL only; any other league answers `score: null` with a `reason`. `score` also rides /events and /odds, and finished /odds selections carry `result` (won/lost/push, or absent when not graded).
- GET /history?event_id=&market=&book=: one market's price moves per book (book required, up to 5; 2 tokens; not on the demo key).
- GET /clv?event_id=&selection_key=&book=&odds=: closing line value of a price taken (1 token; not on the demo key). POST /clv takes up to 100 bets (1 token per distinct event; no demo). `clv_pct` = (taken/close - 1) * 100; null plus a `close_reason`/`fair_reason` when it cannot be computed.
- GET /racing/meetings?date=&country=&race_type=: one race day's meetings and races (1 token; demo key ok: next 3 races to go). Use the returned `race_id` as is.
- GET /racing/race?race_id=&books=: every book's fixed win/place price per runner (each with `changed_at`), Betfair back/lay, and the result once TAB has one (1 token; the demo key gets the next 3 races, tier-1 win prices only). Race status is Betfair's (`betfair_status`, `in_play`), never the clock. Runners carry TAB tote approximates (`tote.nsw`/`tote.vic` win and place), the race has `tote_pools`, and the result has `dividends`, each present once TAB has published them. 
- GET /racing/history?race_id=&book=: each book's win/place moves for a race (book required, up to 5; 2 tokens; not on the demo key).
- GET /usage: tokens used and left this month.

Rules
- JSON is snake_case and every time is UTC ISO-8601. Odds are decimal unless you ask for `format`.
- A selection is identified by `selection_key`, never by its name; it is the same on /odds and /history, live or finished.
- A missing price means that book does not price it right now. Never fill it in.
- Every metered call costs tokens: read the `X-Tokens-*` headers. 402 = out of tokens, 429 = slow down and obey `Retry-After`. WebSocket streaming spends no tokens (included on Business: up to 50 live events, 3 connections; Enterprise: 500 / 20).
- Each price carries `updated_at`; books refresh at different speeds, so check its age before you act on it. A book with `stale: true` has stopped refreshing that event: its prices are still served, but treat them with care.
- WebSocket: keep the last `seq` per event and the `server_epoch` from `hello`; after a drop, subscribe again with `resume` (a `snapshot_required` frame means replace your state). Enable permessage-deflate: snapshots shrink to about 13%.
- On Business and up, /odds adds `model_odds` and `model_source` per selection and `edge_pct` per book price: the 337 model price. Pinnacle's de-vigged price, else Sportsbet's. Absent (never null) where neither prices a complete market; handicaps never have one.
- `open_odds` is the first price we recorded, `close_odds` the last before the off (`fair_odds`: pinnacle's close, margin removed); `books[book].url` opens that book's event page.

What you get

A catalogue of sports, leagues and events (/sports, /events).

Per-book prices per market and selection (/odds), with the opening and closing price and a link to the book's own event page.

History: finished events, their closing prices and per-book price moves back to August 2026.

Horse, greyhound and harness racing: meetings, every book's fixed prices, Betfair and the result on /racing/race, and per-book price moves.

Closing line value for any price you took, and OpenAPI and AsyncAPI specs to generate a typed client.

A WebSocket that pushes each price change as soon as we see it.

Conventions

Format: JSON, snake_case, UTF-8. Responses over 1KB are gzipped when you send Accept-Encoding: gzip.

Times: ISO-8601 UTC, seconds precision, Z suffix (2026-10-04T09:30:00Z).

Odds: decimal, stake included (2.10 returns 2.10 per 1 staked), unless you ask for American or fractional.

Stability: fields documented here are stable within v1. New fields may be added; ignore fields you do not know. schema_version on odds bodies and the WebSocket hello changes only for a breaking change.