# GetOdds WebSocket: live odds changes from six books

Connect to wss://stream.getoddsapi.com/v1/stream with your GetOdds key and receive every moneyline, spread and total change from DraftKings, FanDuel, BetRivers, Pinnacle, Novig and bet365 as it is stored. Messages, filters, resume, limits, Node and Python.

Canonical page: https://getoddsapi.com/docs/websocket

## Free API key

Get a free GetOdds API key: **100 requests per UTC day and 60 per minute, no card**. One key covers REST and the hosted MCP server.

Sign up: https://getoddsapi.com/sign-up?ref=ai-claudebot

## Quickstart

1. Create an account at https://getoddsapi.com/sign-up?ref=ai-claudebot, open https://getoddsapi.com/dashboard and issue a key with the sources you need (draftkings, fanduel, betrivers, prizepicks or underdog). Keep it in a server environment variable named GETODDS_API_KEY.
2. Read current DraftKings NBA spreads with curl:

```bash
curl --fail-with-body "https://getoddsapi.com/api/v1/odds?sport=NBA&market=spread&fresh_only=true&limit=50" \
  -H "Authorization: Bearer $GETODDS_API_KEY"
```

3. The same request in Python (standard library only):

```python
import json, os, urllib.request

req = urllib.request.Request(
    "https://getoddsapi.com/api/v1/odds?sport=NBA&market=spread&fresh_only=true&limit=50",
    headers={"Authorization": "Bearer " + os.environ["GETODDS_API_KEY"]},
)
with urllib.request.urlopen(req) as res:
    rows = json.load(res)["data"]
for row in rows:
    print(row["away"], "at", row["home"], row["side"], row["line"], row["american"], row["observed_at"])
```

4. Check `observed_at`, `age_seconds` and `stale` on every row before using a price. Full reference: https://getoddsapi.com/docs

## Use with Claude (MCP)

```bash
claude mcp add --transport http getodds https://getoddsapi.com/api/mcp \
  --header "Authorization: Bearer $GETODDS_API_KEY"
```

The MCP tools follow the key's source grants and share its allowance. Setup guide: https://getoddsapi.com/use-with-claude

SDKs: `pip install getodds` (PyPI) · `npm install getoddsapi` (npm) · `npx -y getodds-mcp` (local MCP server) · R: `remotes::install_github("getoddsapi/getodds-r")`. Source: https://github.com/getoddsapi · https://getoddsapi.com/docs/sdks

## Pricing

| Plan | Allowance | Price |
| --- | --- | --- |
| Free key | 100 requests a day, 60 a minute | $0, no card |
| Starter | 100,000 credits a month, 120 a minute | $49 a month |
| Pro | 750,000 credits a month, 300 a minute | $113 a month |
| Business | 3,000,000 credits a month, 600 a minute | $219 a month |
| Scale | 15,000,000 credits a month, 1,200 a minute | $279 a month |

Each plan is priced just under the matching odds-api.io tier (Solo £49, about $65; Starter £99, about $131; Growth £179, about $236; Pro £229, about $302 a month, checked 2026-11-17); odds-api.io allows more requests a month on every tier (5,000 an hour) and covers far more bookmakers.

Free evaluation allowance: 100 requests per UTC day and 60 per minute per account, with no payment step. Paid plans $49 to $279 a month for 100K to 15M credits, self-serve at /pricing.
Paid plans keep running past their monthly credits: extra credits are billed at $0.1 per 1,000 on Starter, $0.05 per 1,000 on Pro, $0.025 per 1,000 on Business, $0.012 per 1,000 on Scale, invoiced with the subscription, up to a default monthly cap ($10 on Starter, $38 on Pro, $78 on Business, $198 on Scale) that you can change or set to $0 to turn overage off.
Details: https://getoddsapi.com/pricing

## Guide


Canonical: https://getoddsapi.com/docs/websocket
Reviewed: 2026-11-20 UTC

**Answer:** GetOdds streams odds changes over a persistent WebSocket at wss://stream.getoddsapi.com/v1/stream: connect with your API key in the Authorization header, get a snapshot of current lines, then an odds.changed message each time a moneyline, spread or total moves at DraftKings, FanDuel, BetRivers, Pinnacle, Novig and bet365. It works on every plan, including the free key, and costs one credit per connected minute.

Connect to wss://stream.getoddsapi.com/v1/stream with your GetOdds key and receive every moneyline, spread and total change from DraftKings, FanDuel, BetRivers, Pinnacle, Novig and bet365 as it is stored. Messages, filters, resume, limits, Node and Python.

| Fact | Value |
| --- | --- |
| URL | wss://stream.getoddsapi.com/v1/stream |
| Auth | Authorization: Bearer <key>, or first message {"type":"auth","key":"go_live_..."} |
| Books | DraftKings, FanDuel, BetRivers, Pinnacle, Novig and bet365 |
| Markets | h2h (moneyline), spreads, totals; pregame; the same lines as /v4/sports/{sport}/odds |
| Latency | each sport you watch is re-read every 15 seconds; a change goes out within about 15 seconds of GetOdds storing it |
| Cost | 1 credit (Free: 1 request of the daily allowance) per connected minute |
| Connections | 2 open at once per account (shared with the legacy /api/v1/odds/stream) |
| Health | https://stream.getoddsapi.com/healthz |

## Connect

Open wss://stream.getoddsapi.com/v1/stream with Authorization: Bearer <your key> in the upgrade headers. Browsers cannot set headers on a WebSocket, so a browser client may instead send {"type":"auth","key":"go_live_..."} as its first message within 5 seconds. A key in the URL is refused (URLs end up in logs). Any GetOdds key works, including a free key: get one at /sign-up or with POST /api/v1/agent/signup.

Optional query parameters narrow what you receive: sports (The Odds API sport keys such as basketball_nba, americanfootball_nfl, soccer_epl), bookmakers (draftkings, fanduel, betrivers, pinnacle, novig, bet365), markets (h2h, spreads, totals), event_ids (GetOdds event ids from /v4/sports/{sport}/events), after (resume, below) and snapshot=false (skip the initial snapshot). Omit a parameter to receive everything.

## Messages

Every message is one JSON text frame with a type. connected: your filters, the books and markets carried, credits per minute and the latest event id. snapshot: one per sport, the current lines grouped like a /v4/sports/{sport}/odds response (events, each with bookmakers and markets). snapshot_complete: the snapshot is done; changes follow. odds.changed: one market at one book moved (new price or new line), with outcomes and previous_outcomes. odds.removed: a book stopped quoting a market (pulled, suspended, or the game started), outcomes is null. heartbeat: every 30 seconds with last_id. error: sent just before a close, with a code and message. reconnect: the gateway is restarting; reconnect with after=last_id.

Outcomes carry name (team, Draw, Over or Under), american, decimal and, for spreads and totals, point. event_id is the same id /v4/sports/{sport}/odds and /v4/sports/{sport}/events return, so a stream message updates the event you already hold.

```json
{
  "id": "mwoezcqt-37",
  "type": "odds.changed",
  "sport_key": "basketball_nba",
  "sport_title": "NBA",
  "event_id": "espn-draftkings:espn:NBA:401810123",
  "commence_time": "2026-11-21T00:30:00.000Z",
  "home_team": "Boston Celtics",
  "away_team": "New York Knicks",
  "bookmaker": "fanduel",
  "bookmaker_title": "FanDuel",
  "market": "spreads",
  "last_update": "2026-11-20T03:20:53.461Z",
  "outcomes": [
    {
      "name": "New York Knicks",
      "american": -108,
      "decimal": 1.9259,
      "point": 4.5
    },
    {
      "name": "Boston Celtics",
      "american": -112,
      "decimal": 1.8929,
      "point": -4.5
    }
  ],
  "previous_outcomes": [
    {
      "name": "New York Knicks",
      "american": -110,
      "decimal": 1.9091,
      "point": 4.5
    },
    {
      "name": "Boston Celtics",
      "american": -110,
      "decimal": 1.9091,
      "point": -4.5
    }
  ],
  "observed_at": "2026-11-20T03:21:02.114Z"
}
```

## Resume after a disconnect

Keep the id of the last odds.* message you processed (heartbeats also carry last_id). Reconnect with after=<that id> and the gateway replays what you missed, then sends replay_complete. It keeps 15 minutes of changes in memory. If your id is older than that, or the gateway restarted, you get resync_required followed by a fresh snapshot: replace your local state with it rather than patching.

Reconnect with exponential backoff and jitter (1 s doubling to 30 s). The server pings every 20 seconds and closes a connection that stops answering; most clients answer pings automatically. You can also send {"type":"ping"} and get a pong.

## Limits, plans and credits

Opening a connection and every minute it stays open each count as one metered request: one credit on a paid plan, or one request of the Free key's 100 a day. So a stream costs 60 credits an hour, while it delivers every change across every sport you subscribe to. The same checks as any API call run each minute: a revoked key closes with 4401, a used-up allowance with 4402.

At most two streaming connections per account may be open at once; a third is refused with 4429 CONNECTION_LIMIT. A connection that drops without closing frees its slot within 270 seconds. Use one connection with no sports filter, or two filtered ones, rather than one per sport.

| Close code | Meaning | What to do |
| --- | --- | --- |
| 4400 | Bad query (unknown sport, book, market, malformed after) or key sent in the URL | Fix the request |
| 4401 | Missing, invalid or revoked key | Use a valid key; do not retry unchanged |
| 4402 | Daily allowance (Free) or monthly credits used up | Upgrade at /pricing or wait for the reset |
| 4403 | The key is not allowed this data | Check the key in the dashboard |
| 4408 | No auth message within 5 seconds | Send the key in the header or first message |
| 4409 | Client too slow; more than 4 MB waiting | Read faster, then reconnect with after |
| 4429 | Third connection, or too many unauthenticated connections | Close one; reuse a single connection |
| 4503 / 1012 | Gateway unavailable or restarting | Reconnect with backoff and after=last_id |

## Node.js client

A complete client with reconnect, resume and stop-on-account-error. It runs on a server; never ship your key to a browser.

```javascript
// npm install ws    (Node 18+). Save as stream.mjs and run: GETODDS_API_KEY=go_live_... node stream.mjs
import WebSocket from "ws";

const URL = "wss://stream.getoddsapi.com/v1/stream?sports=basketball_nba,americanfootball_nfl&markets=h2h,spreads,totals";
let lastId = null;           // persist this if you want to resume after a restart
let backoff = 1000;

function connect() {
  const url = lastId ? `${URL}&after=${lastId}` : URL;
  const ws = new WebSocket(url, { headers: { Authorization: `Bearer ${process.env.GETODDS_API_KEY}` } });

  ws.on("open", () => { backoff = 1000; });
  ws.on("message", (raw) => {
    const msg = JSON.parse(raw);
    switch (msg.type) {
      case "connected":        console.log("connected", msg.filters, "credits/min:", msg.credits_per_minute); break;
      case "snapshot":         console.log("snapshot", msg.sport_key, msg.events.length, "events"); break;   // replace local state
      case "odds.changed":
      case "odds.removed":
        lastId = msg.id;
        console.log(msg.type, msg.bookmaker, msg.market, msg.home_team, "vs", msg.away_team, JSON.stringify(msg.outcomes));
        break;
      case "heartbeat":        lastId = msg.last_id ?? lastId; break;
      case "error":            console.error(msg.code, msg.message); break;
    }
  });
  ws.on("close", (code) => {
    // 4401 bad key, 4402 allowance used up, 4403 not allowed: fix the account, do not retry blindly.
    if ([4400, 4401, 4402, 4403].includes(code)) return console.error("stopped with", code);
    setTimeout(connect, backoff + Math.random() * 500);
    backoff = Math.min(backoff * 2, 30000);
  });
}
connect();

```

## Python client

The same client with the websockets package.

```python
# pip install websockets    (Python 3.9+). Run: GETODDS_API_KEY=go_live_... python stream.py
import asyncio, json, os, random
import websockets

URL = "wss://stream.getoddsapi.com/v1/stream?sports=basketball_nba&markets=h2h,spreads"
HEADERS = {"Authorization": f"Bearer {os.environ['GETODDS_API_KEY']}"}
STOP = {4400, 4401, 4402, 4403}   # bad request, bad key, allowance used up, not allowed

async def main():
    last_id, backoff = None, 1
    while True:
        url = URL + (f"&after={last_id}" if last_id else "")
        try:
            # websockets >= 14: additional_headers=; older versions call it extra_headers=
            async with websockets.connect(url, additional_headers=HEADERS, ping_interval=20) as ws:
                backoff = 1
                async for raw in ws:
                    msg = json.loads(raw)
                    if msg["type"] in ("odds.changed", "odds.removed"):
                        last_id = msg["id"]
                        print(msg["type"], msg["bookmaker"], msg["market"], msg["home_team"], msg["outcomes"])
                    elif msg["type"] == "snapshot":
                        print("snapshot", msg["sport_key"], len(msg["events"]), "events")
                    elif msg["type"] == "heartbeat":
                        last_id = msg.get("last_id") or last_id
                    elif msg["type"] == "error":
                        print("error", msg["code"], msg["message"])
        except websockets.ConnectionClosed as closed:
            if closed.rcvd and closed.rcvd.code in STOP:
                raise SystemExit(f"stopped: {closed.rcvd.code} {closed.rcvd.reason}")
        except OSError:
            pass
        await asyncio.sleep(backoff + random.random())
        backoff = min(backoff * 2, 30)

asyncio.run(main())

```

## What it is and is not

The stream pushes the pregame game lines GetOdds stores for DraftKings, FanDuel, BetRivers, Pinnacle, Novig and bet365. It does not make the books update faster: each change appears once GetOdds has captured it and the gateway's next read of that sport (every 15 seconds while someone is watching) sees it. Player props, DFS lines and prediction markets are not on the stream yet; read them over REST. BetRivers is on the stream for game lines; its other native markets stay on /api/v1/betrivers/markets. Gateway health, per sport, is public at https://stream.getoddsapi.com/healthz and on /status.

The earlier wss://getoddsapi.com/api/v1/odds/stream (DraftKings retained-change pages, 4-minute sessions, one credit per 5-second poll) still works for existing clients and is documented at /docs/odds-stream, but new integrations should use this stream.

## Questions

### Does GetOdds have a WebSocket API?

Yes. wss://stream.getoddsapi.com/v1/stream pushes moneyline, spread and total changes from DraftKings, FanDuel, BetRivers, Pinnacle, Novig and bet365 over one persistent connection, on every plan including the free key.

### How do I authenticate the GetOdds WebSocket?

Send Authorization: Bearer <your key> in the upgrade headers. In a browser, send {"type":"auth","key":"go_live_..."} as the first message instead. Never put the key in the URL.

### How much does the WebSocket cost?

One credit per connected minute (on Free, one of the 100 daily requests). There is no separate add-on.

### How many WebSocket connections can I open?

Two at once per account. Filter by sports, bookmakers, markets or event_ids instead of opening one connection per sport.

### How do I avoid missing changes after a disconnect?

Reconnect with after=<last id>. The gateway replays up to 15 minutes from memory; older than that, or after a gateway restart, it sends resync_required and a fresh snapshot.

### Is it Server-Sent Events or a real WebSocket?

A real WebSocket (RFC 6455) with server pings every 20 seconds and an application heartbeat every 30 seconds. A plain HTTPS GET to the URL answers 426.

## Sources

- [Gateway health](https://stream.getoddsapi.com/healthz)
- [The Odds API compatible odds endpoint](https://getoddsapi.com/the-odds-api-compatible)
- [OpenAPI](https://getoddsapi.com/openapi.json)

GetOdds (getoddsapi.com) is an independent product, not affiliated with the operators named and separate from The Odds API and Odds-API.io. No picks or predicted profits.

---

GetOdds (getoddsapi.com) is an independent developer product and is not affiliated with any sportsbook or pick’em operator. GetOdds is a separate product from The Odds API (the-odds-api.com) and from Odds-API.io (odds-api.io), and is not affiliated with either. Prices describe data, not betting advice.

GetOdds is operated by Stunning Couches LLC, a Delaware limited liability company. Terms: https://getoddsapi.com/terms · Privacy: https://getoddsapi.com/privacy
