Real-Time Odds Feed via WebSocket

The WebSocket feed delivers the exact same response format as the /odds endpoint, but in real time. Instead of polling, you receive updates instantly whenever odds change. We recommend all clients move to WebSocket for efficiency and lower latency. It reduces request overhead, scales better, and gives you immediate updates for live markets.

Why Use WebSocket?

Real-Time Updates

Receive odds changes instantly without polling

Lower Latency

Sub-150ms updates for live markets

Reduced Overhead

Single persistent connection vs repeated HTTP calls

Better Scaling

Perfect for bots, live dashboards, and in-play betting apps

Access & Pricing

Add-on Feature: WebSocket access is available as an add-on. Subscribe through odds-api.io to enable it for your account.

Pricing: 2x the REST API price Bookmakers: The WebSocket automatically sends updates for all bookmakers you have selected in your account. You can manage your selected bookmakers via the /bookmakers/selected/select endpoint or through the dashboard.

Connection Details

Endpoint:

wss://api.odds-api.io/v3/ws?apiKey=YOUR_API_KEY&markets=ML,Spread,Totals

Authentication:

API key passed as query parameter
Up to two concurrent connections per API key
Opening a third closes the oldest one
Reconnecting within 2 seconds of that is refused with close code 1013, so back off a few seconds and retry
Automatic cleanup keeps your feed stable

Close Codes

When the server ends a connection it sends a close frame with one of these codes and a short reason:

Code	Reason	What to do
`1000`	`closed by server`	Normal close. Reconnect if you still need the feed
`1008`	`connection limit reached, newer connection opened`	A third connection on your API key replaced this one. Reuse connections instead of opening new ones
`1008`	`client too slow, send buffer full`	Your client fell too far behind. Process messages asynchronously, then reconnect with `lastSeq`
`1011`	`internal error`	The server could not complete your catch-up. Reconnect with backoff
`1012`	`server restart`	A deploy or restart. Reconnect after a second or two with `lastSeq` to resume without gaps
`1013`	`reconnect cooldown, retry in a few seconds`	You reconnected within 2 seconds of a limit close. Wait a few seconds

A close without a frame (1006 in most clients) means the network dropped or the connection stopped answering pings. Reconnect with backoff and lastSeq.

Compression (Required)

Your client must negotiate permessage-deflate compression when it connects. Compressed feeds use 3-5x less bandwidth. Connections that do not offer it are refused with HTTP 426 Upgrade Required. Most clients do this for you. Check the table before you pick a library:

Platform	Library	Compression
Node.js	`ws`	On by default
Browser	native `WebSocket`	On by default
Python	`websockets`	On by default
Python	`websocket-client`	Not supported. Use `websockets` instead
PHP	`amphp/websocket-client`	On by default (needs the `zlib` extension)
PHP	`textalk/websocket`	Not supported. Use `amphp/websocket-client`
Go	`gorilla/websocket`	Set `Dialer.EnableCompression = true`
Java	Java-WebSocket	Add `PerMessageDeflateExtension` to the draft
.NET	`ClientWebSocket`	Add `Options.DangerousDeflateOptions` (.NET 6+)

To confirm, check the handshake request your client sends. It must include:

Sec-WebSocket-Extensions: permessage-deflate

Filter Parameters

The markets parameter is required for the odds channel (the default). It is not needed when subscribing only to scores/status. Check valid names with GET /v3/markets?sport=<sport>.

Parameter	Type	Max	Description
`markets`	comma-separated	40	Required for the odds channel. Market names (e.g., `ML,Spread,Totals`)
`channels`	comma-separated	-	`odds`, `scores`, `status`. Defaults to `odds`.
`sport`	comma-separated	10	Filter by sport names or slugs (e.g., `football,basketball`)
`leagues`	comma-separated	20	Filter by league slugs (e.g., `england-premier-league`)
`eventIds`	comma-separated	50	Filter by specific event IDs
`status`	single value	-	`live` or `prematch`. When an event starts, or is settled or cancelled before it starts, a `prematch` connection gets a `no_markets` for each of your bookmakers on that event, so its pre-match odds close. These carry a `seq` and are replayed when you reconnect with `lastSeq`; on a reconnect that gets neither a replay nor pushed current state, the ones after your `lastSeq` are resent without a `seq`. With the `status` channel it also receives the `status` messages. Odds messages for a linked event carry the event’s own kickoff in `date` (the bookmaker’s listed start only when no link exists), and the `status` filter uses that date.

Using leagues or eventIds is recommended to reduce bandwidth. You cannot use both together.

Channels

Subscribe to one or more streams with channels. Omitting it keeps the default odds stream, so existing connections are unchanged. Add scores and/or status for live event state:

channels is an allowlist: you receive only the channels you list. To keep odds, include odds (e.g. channels=odds,scores,status); channels=scores,status alone stops odds delivery.

odds (default): created, updated, deleted, no_markets
scores: score messages on every score change
status: status messages on pending (new match added), live, settled, cancelled (carries the current scores, so you get the final result on settle)

Live score/status messages also carry an optional clock snapshot (same shape as GET /events/live) so you can re-anchor a match-clock ticker on every event without polling. See the Live Events guide. score/status are event-level (no bookie/markets), best-effort (no seq, not replayed). When you reconnect with lastSeq and subscribe to status, the server resends the current status of every live event, and of events settled or cancelled in the last 12 hours, that match your filters. They arrive after the replay and before replay_complete, so a transition you missed while away still reaches you. See the WebSocket API reference for full details.

# Odds + scores + status
wss://api.odds-api.io/v3/ws?apiKey=xxx&channels=odds,scores,status&markets=ML
# Scoreboard only
wss://api.odds-api.io/v3/ws?apiKey=xxx&channels=scores,status&sport=football

Example Connection URLs

# All live football events with main markets only
wss://api.odds-api.io/v3/ws?apiKey=xxx&sport=football&status=live&markets=ML,Spread,Totals

# Specific leagues
wss://api.odds-api.io/v3/ws?apiKey=xxx&leagues=england-premier-league,spain-la-liga&markets=ML

# Specific events
wss://api.odds-api.io/v3/ws?apiKey=xxx&eventIds=12345,67890,11111&markets=ML,Spread,Totals

# Multiple sports, prematch only
wss://api.odds-api.io/v3/ws?apiKey=xxx&sport=football,basketball,tennis&status=prematch&markets=ML,Spread,Totals

Welcome Message

Upon successful connection, you’ll receive a welcome message confirming your active filters:

{
  "type": "welcome",
  "message": "Connected to OddsAPI WebSocket",
  "user_id": "user123",
  "bookmakers": ["Bet365", "SingBet"],
  "sport_filter": ["Football"],
  "leagues_filter": ["england-premier-league"],
  "event_id_filter": [],
  "status_filter": "live",
  "market_filter": ["ML", "SPREAD", "TOTALS"],
  "channels": ["odds", "scores", "status"],
  "connected_at": "2026-01-15T21:00:00Z",
  "warning": "..."
}

Error Responses

If your connection parameters are invalid, you’ll receive a 400 Bad Request with one of these errors:

Error Message	Cause
`Too many sports. Maximum 10 allowed.`	Exceeded sport limit
`Too many leagues. Maximum 20 allowed.`	Exceeded league limit
`Too many event IDs. Maximum 50 allowed.`	Exceeded eventIds limit
`Too many markets. Maximum 40 allowed.`	Exceeded market limit
`Cannot use both 'leagues' and 'eventIds' filters together.`	Mutual exclusion violated
`Invalid status filter. Use 'prematch' or 'live'`	Invalid status value
`Invalid channel: X. Allowed: odds, scores, status`	Unknown channel

Update Types

Messages come in as JSON objects. Each has a type field:

Type	Channel	Description
`created`	odds	New match added
`updated`	odds	Match or market changed
`deleted`	odds	Match removed, or its bookmaker went `down` (see Bookmaker Status)
`no_markets`	odds	Match exists but has no markets available, or none in your `markets=` list
`score`	scores	Live score changed. Payload `{ id, type, scores, timestamp }` (no status field)
`status`	status	Status changed to `pending` (new match added), `live`, `settled`, or `cancelled` (carries scores)

The scores object in score and status messages has the same shape and period keys as /events; see Period Scores. deleted and no_markets messages carry an empty markets array and are always delivered, even when you subscribe with a markets= filter, so filtered clients still learn when a match goes off the board. They do respect your status=, sport= and leagues= filters, and carry the event’s date, so a removal for a pre-match fixture is not delivered on a status=live connection. no_markets means the bookmaker has nothing for that event in your subscription: either no active markets at all, or none left in your markets= list. If the bookmaker still prices the event but has pulled every market you subscribe to, you get a no_markets for that event and bookmaker, so clear what you hold for it. It carries the seq of the update it stands in for. You get it once when your markets disappear. Later updates that still carry none of your markets are not repeated, and the next updated brings them back when they return. A no_markets can also arrive for an event you have not seen yet on the connection; there is simply nothing to show for it.

Replace, don’t merge. Every updated message carries the complete set of markets we currently have for that bookmaker and event, not only the ones that changed. Replace your stored markets for that event with what arrives.If you merge incoming markets into what you already hold, a market that gets suspended or withdrawn disappears from the feed but never disappears from your copy. Suspended markets are removed from the payload rather than flagged, so absence is the signal. Merging leaves you quoting prices that are no longer offered.This applies to individual lines too. When a total is decided in play (say the 0.5 line once a goal is scored), there is no per-line “suspended” event: the line is simply missing from the next message for that event and bookmaker. A replace-based client drops it automatically; no timeout heuristics are needed.

Message Format

Each message includes a seq field: a global sequence number. On a connection, updates arrive in seq order and seq never decreases. The same update sent for several bookmakers shares one seq, so identify a frame by id, bookie and seq together, and don’t drop a frame just because its seq equals the previous one. The highest seq you received is the one to resume from (see Reconnection with Replay below). Seqs are shared by all subscribers, so yours are increasing but not consecutive: a jump between two updates is not a gap. Rarely, during a brief server-side interruption, an odds update arrives without seq. Apply it as normal and leave your stored lastSeq unchanged. A reconnect from before that point gets current state instead of a replay, so nothing is lost.

{
  "type": "updated",
  "seq": 482917,
  "timestamp": 1723992773,
  "id": "63017989",
  "bookie": "SingBet",
  "url": "https://www.singbet.com/sports/football/match/63017989",
  "markets": [
    {
      "name": "ML",
      "updatedAt": "2024-01-15T10:30:00Z",
      "odds": [
        {
          "home": "1.85",
          "draw": "3.25",
          "away": "2.10",
          "max": 500
        }
      ]
    },
    {
      "name": "Totals",
      "updatedAt": "2024-01-15T10:30:00Z",
      "odds": [
        {
          "hdp": 2.5,
          "over": "1.85",
          "under": "2.10",
          "max": 500
        }
      ]
    }
  ]
}

Quick Start

JavaScript Example

const WebSocket = require('ws');

const apiKey = process.env.ODDS_API_KEY;

// Build connection URL with filters
const params = new URLSearchParams({
  apiKey,
  markets: 'ML,Spread,Totals',
  sport: 'football',
  status: 'live'
});

const ws = new WebSocket(`wss://api.odds-api.io/v3/ws?${params}`);

ws.onopen = () => {
  console.log("Connected to Odds-API WebSocket");
};

ws.onclose = () => {
  console.log("Disconnected from WebSocket");
};

ws.onerror = (err) => {
  console.error("WebSocket error:", err);
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === "welcome") {
    console.log("Connected:", data.message);
    console.log("Active filters:", {
      sports: data.sport_filter,
      leagues: data.leagues_filter,
      status: data.status_filter,
      markets: data.market_filter
    });
  } else if (data.type === "updated") {
    console.log(`Match ID: ${data.id}`);
    console.log(`Bookmaker: ${data.bookie}`);
    console.log(`Markets: ${data.markets.length}`);

    // Process each market
    data.markets.forEach(market => {
      console.log(`  ${market.name}:`, market.odds[0]);
    });
  }
};

const apiKey = 'YOUR_API_KEY';

// Build connection URL with filters
const params = new URLSearchParams({
  apiKey,
  markets: 'ML,Spread,Totals',
  leagues: 'england-premier-league,spain-la-liga'
});

const ws = new WebSocket(`wss://api.odds-api.io/v3/ws?${params}`);

ws.onopen = () => console.log("Connected");
ws.onclose = () => console.log("Disconnected");
ws.onerror = (err) => console.error("Error:", err);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === "updated") {
    console.log(`Match: ${data.id}`);
    console.log(`Bookie: ${data.bookie}`);
    console.log(`Markets: ${data.markets.length}`);
  }
};

Python Example

Use the websockets library (pip install websockets). It negotiates the required permessage-deflate compression by default. websocket-client does not support compression, so its connections are refused with HTTP 426.

import asyncio
import json
import os
from urllib.parse import urlencode

import websockets

api_key = os.environ['ODDS_API_KEY']

# Build connection URL with filters
params = urlencode({
    'apiKey': api_key,
    'markets': 'ML,Spread,Totals',
    'sport': 'football',
    'status': 'live'
})

async def main():
    async with websockets.connect(
        f"wss://api.odds-api.io/v3/ws?{params}",
        ping_interval=30,
        ping_timeout=10,
    ) as ws:
        print("Connected to Odds-API WebSocket")

        async for message in ws:
            data = json.loads(message)

            if data['type'] == 'welcome':
                print(f"Connected: {data['message']}")
                print(f"Active filters: sports={data['sport_filter']}, "
                      f"status={data['status_filter']}, markets={data['market_filter']}")

            elif data['type'] == 'updated':
                print(f"Match ID: {data['id']}")
                print(f"Bookmaker: {data['bookie']}")
                print(f"Markets: {len(data['markets'])}")

                # Process each market
                for market in data['markets']:
                    print(f"  {market['name']}: {market['odds'][0]}")

asyncio.run(main())

PHP Example

This sample needs permessage-deflate, which is why it uses amphp/websocket-client v2 (composer require amphp/websocket-client). It negotiates compression by default when PHP’s zlib extension is loaded. textalk/websocket cannot compress, so its connections are refused with HTTP 426.

<?php
require __DIR__ . '/vendor/autoload.php';

use function Amp\Websocket\Client\connect;

$apiKey = getenv('ODDS_API_KEY');
$params = http_build_query([
    'apiKey' => $apiKey,
    'markets' => 'ML,Spread,Totals',
    'sport' => 'football',
    'status' => 'live'
]);

$connection = connect("wss://api.odds-api.io/v3/ws?{$params}");

foreach ($connection as $message) {
    $data = json_decode($message->buffer(), true);

    if ($data['type'] === 'welcome') {
        echo "Connected! Filters: " . implode(', ', $data['sport_filter']) . "\n";
    } elseif ($data['type'] === 'updated') {
        echo "Match ID: {$data['id']} at {$data['bookie']}\n";
        foreach ($data['markets'] as $market) {
            echo "  {$market['name']}: " . json_encode($market['odds'][0]) . "\n";
        }
    }
}

Handling Different Update Types

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'welcome':
      console.log(`Connected: ${data.message}`);
      console.log(`User ID: ${data.user_id}`);
      console.log(`Bookmakers: ${data.bookmakers.join(', ')}`);
      console.log(`Filters: sports=${data.sport_filter}, status=${data.status_filter}`);
      if (data.warning) {
        console.warn(`Warning: ${data.warning}`);
      }
      break;

    case 'created':
      console.log(`New match created: ${data.id} at ${data.bookie}`);
      // Add match to your database/UI
      break;

    case 'updated':
      console.log(`Match updated: ${data.id} at ${data.bookie}`);
      // Update existing match odds
      updateMatchOdds(data.id, data.bookie, data.markets);
      break;

    case 'deleted':
      console.log(`Match deleted: ${data.id} at ${data.bookie}`);
      // Remove match from your database/UI
      break;

    case 'no_markets':
      console.log(`No markets available for match: ${data.id}`);
      // Handle temporarily unavailable markets
      break;

    default:
      console.log('Unknown message type:', data.type);
  }
};

function updateMatchOdds(matchId, bookmaker, markets) {
  markets.forEach(market => {
    console.log(`${market.name} updated at ${market.updatedAt}:`, market.odds[0]);

    // Update your UI or database here
    // Example: store latest odds for comparison
    const odds = market.odds[0];
    if (market.name === 'ML') {
      console.log(`  Home: ${odds.home}, Draw: ${odds.draw}, Away: ${odds.away}`);
    } else if (market.name === 'Totals') {
      console.log(`  Over ${odds.hdp}: ${odds.over}, Under: ${odds.under}`);
    }
  });
}

Advanced Implementation: Live Odds Tracker

class LiveOddsTracker {
  constructor(apiKey, options = {}) {
    this.apiKey = apiKey;
    this.options = {
      markets: 'ML,Spread,Totals',
      sport: null,
      leagues: null,
      eventIds: null,
      status: null,
      ...options
    };
    this.ws = null;
    this.matches = new Map();
    this.lastSeq = 0;
    this.reconnectAttempts = 0;
    this.maxReconnectAttempts = 5;
  }

  buildUrl() {
    const params = new URLSearchParams({ apiKey: this.apiKey });
    if (this.options.markets) params.set('markets', this.options.markets);
    if (this.options.sport) params.set('sport', this.options.sport);
    if (this.options.leagues) params.set('leagues', this.options.leagues);
    if (this.options.eventIds) params.set('eventIds', this.options.eventIds);
    if (this.options.status) params.set('status', this.options.status);
    if (this.lastSeq > 0) params.set('lastSeq', String(this.lastSeq));
    return `wss://api.odds-api.io/v3/ws?${params}`;
  }

  connect() {
    this.ws = new WebSocket(this.buildUrl());

    this.ws.onopen = () => {
      this.reconnectAttempts = 0;
    };

    this.ws.onmessage = (event) => {
      this.handleMessage(JSON.parse(event.data));
    };

    this.ws.onclose = () => {
      console.log('WebSocket connection closed');
      this.reconnect();
    };

    this.ws.onerror = (error) => {
      console.error('WebSocket error:', error);
    };
  }

  handleMessage(data) {
    if (data.type === 'welcome') {
      this.onWelcome(data);
      return;
    }

    if (data.type === 'resync_required') {
      console.log('Resync required:', data.reason);
      // Rebuild state from REST snapshot, then reconnect
      return;
    }

    // Track sequence number for gap-free reconnection
    if (data.seq > this.lastSeq) {
      this.lastSeq = data.seq;
    }

    const key = `${data.id}-${data.bookie}`;

    switch (data.type) {
      case 'created':
        this.matches.set(key, {
          id: data.id,
          bookmaker: data.bookie,
          markets: data.markets,
          timestamp: data.timestamp
        });
        this.onMatchCreated(data);
        break;

      case 'updated':
        const existing = this.matches.get(key);
        if (existing) {
          existing.markets = data.markets;
          existing.timestamp = data.timestamp;
          this.onMatchUpdated(data, existing);
        }
        break;

      case 'deleted':
        this.matches.delete(key);
        this.onMatchDeleted(data);
        break;

      case 'no_markets':
        this.onNoMarkets(data);
        break;
    }
  }

  // Override these methods in your implementation
  onWelcome(data) {
    console.log(`Connected: ${data.message}`);
    console.log(`Filters: sports=${data.sport_filter}, status=${data.status_filter}`);
  }

  onMatchCreated(data) {
    console.log(`New match: ${data.id} at ${data.bookie}`);
  }

  onMatchUpdated(data, previousData) {
    console.log(`Updated: ${data.id} at ${data.bookie}`);
  }

  onMatchDeleted(data) {
    console.log(`Deleted: ${data.id} at ${data.bookie}`);
  }

  onNoMarkets(data) {
    console.log(`No markets: ${data.id}`);
  }

  reconnect() {
    if (this.reconnectAttempts < this.maxReconnectAttempts) {
      this.reconnectAttempts++;
      const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000);

      console.log(`Reconnecting in ${delay}ms... (Attempt ${this.reconnectAttempts})`);

      setTimeout(() => this.connect(), delay);
    } else {
      console.error('Max reconnection attempts reached');
    }
  }

  getMatchOdds(matchId, bookmaker) {
    return this.matches.get(`${matchId}-${bookmaker}`);
  }

  getAllMatches() {
    return Array.from(this.matches.values());
  }

  disconnect() {
    if (this.ws) {
      this.ws.close();
    }
  }
}

// Usage
const tracker = new LiveOddsTracker(process.env.ODDS_API_KEY, {
  markets: 'ML,Spread,Totals',
  sport: 'football',
  status: 'live'
});
tracker.connect();

React Integration

import { useEffect, useState, useRef } from 'react';

function useLiveOdds(apiKey, options = {}) {
  const [odds, setOdds] = useState({});
  const [connected, setConnected] = useState(false);
  const ws = useRef(null);

  useEffect(() => {
    const params = new URLSearchParams({ apiKey });
    if (options.markets) params.set('markets', options.markets);
    if (options.sport) params.set('sport', options.sport);
    if (options.leagues) params.set('leagues', options.leagues);
    if (options.status) params.set('status', options.status);

    ws.current = new WebSocket(`wss://api.odds-api.io/v3/ws?${params}`);

    ws.current.onmessage = (event) => {
      const data = JSON.parse(event.data);

      if (data.type === 'welcome') {
        setConnected(true);
      } else if (data.type === 'updated' || data.type === 'created') {
        setOdds(prev => ({
          ...prev,
          [`${data.id}-${data.bookie}`]: {
            id: data.id,
            bookmaker: data.bookie,
            markets: data.markets
          }
        }));
      } else if (data.type === 'deleted') {
        setOdds(prev => {
          const next = { ...prev };
          delete next[`${data.id}-${data.bookie}`];
          return next;
        });
      }
    };

    ws.current.onclose = () => setConnected(false);

    return () => ws.current?.close();
  }, [apiKey, options.markets, options.sport, options.leagues, options.status]);

  return { odds, connected };
}

// Component
function LiveOddsDisplay() {
  const { odds, connected } = useLiveOdds(process.env.REACT_APP_ODDS_API_KEY, {
    markets: 'ML,Spread,Totals',
    sport: 'football',
    status: 'live'
  });

  return (
    <div>
      <div className={connected ? 'connected' : 'disconnected'}>
        {connected ? 'Connected' : 'Disconnected'}
      </div>
      <div className="matches">
        {Object.values(odds).map(match => (
          <div key={`${match.id}-${match.bookmaker}`}>
            <h3>Match #{match.id} - {match.bookmaker}</h3>
            {match.markets.map(market => (
              <div key={market.name}>
                <strong>{market.name}:</strong> {JSON.stringify(market.odds[0])}
              </div>
            ))}
          </div>
        ))}
      </div>
    </div>
  );
}

Reconnection with Replay

When your client disconnects and reconnects, you can resume from where you left off using the lastSeq parameter. The server will replay any messages you missed during the disconnection.

How It Works

Track the seq field from every live message that has one (live seqs only go up, so the last one is also the highest)
When reconnecting, pass the last seq you received as a query parameter: lastSeq=482917
The server sends a burst of missed messages before resuming the live stream
After the replay burst, live updates continue as normal with no gap

Connection URL with Replay

wss://api.odds-api.io/v3/ws?apiKey=xxx&markets=ML,Spread,Totals&lastSeq=482917

Replay Behavior

Compacted latest-state replay: You receive the most recent state for each eventId:bookie combination, not every intermediate tick. If odds changed multiple times while you were disconnected, you get the final value only. This is correct for state sync; trading clients who need every tick should use /odds/movements per event.
The replay burst is delivered as a batch of messages immediately after the welcome message
Messages are filtered through your active filters (sport, leagues, markets, etc.), so you only receive updates relevant to your session
deleted and no_markets updates are replayed as latest state. If an event was deleted while you were disconnected, you will receive the deletion during replay
On a status=prematch connection, events that started while you were away arrive as no_markets for each of your bookmakers, in the replay or in the pushed current state, so their pre-match odds close. When neither is sent (you reconnect again shortly after being sent current state, or get resync_required), these closes are still sent for events that started after your lastSeq, without a seq, before replay_complete; the rest of the board continues live. If they do not fit the per-connection limit, resync_required (reason: "snapshot_truncated") follows instead
With the status channel, the current status of live and recently finished events follows the replay (see Channels)
Replay data is retained for up to 24 hours. A lastSeq older than that gets your current state instead of a replay (see below)
Right after a server restart or deploy, the replay can also include the latest state of a few seconds of updates from just before your lastSeq, carrying a seq at or below it. They are current state, so apply them as normal; it guards against an update the previous server instance sent you no copy of. Keep your stored lastSeq at the highest seq you have seen
Updates already covered by the replay are not sent again live; live updates after the replay all have a seq above the replay’s range

Knowing When Replay Is Done

Add replayComplete=true to the connection URL to get one control message once the catch-up phase is over:

{
  "type": "replay_complete",
  "outcome": "replayed",
  "last_seq": 482917,
  "through_seq": 483350
}

Everything after it is live. outcome is replayed, snapshot (current state was pushed instead, see below), resync_required (rebuild from REST), or live (no lastSeq was given, or you reconnected again shortly after being sent current state: only the pre-match closes and statuses above are caught up, then everything is live). through_seq is the highest seq the catch-up covered. The message is opt-in so that clients which do not expect new message types are unaffected.

Each message is delivered as its own WebSocket frame - parse every frame with JSON.parse(event.data), exactly like live updates - and the burst is sent as fast as the connection allows

Replay Limits and Resync

If the replay cannot be served reliably, the server will not silently truncate. Instead, it sends a resync_required message. This happens when:

Too many replay candidates (reason: "replay_limit_exceeded"): the gap between your lastSeq and the current seq produced more updates than the server will process
Expired replay data (reason: "replay_window_expired"): one or more replay payloads have aged out of the retention window, which would leave gaps in the catch-up
Dirty replay window (reason: "replay_window_dirty"): the server had to drop or skip seqs after your lastSeq, or sent updates without seq, so a clean replay cannot be guaranteed

{
  "type": "resync_required",
  "reason": "replay_limit_exceeded",
  "last_seq": 48291000,
  "current_seq": 48295000
}

When your last_seq is outside the replay window, the server first pushes the current state of your subscription as ordinary created updates, then continues streaming live on the same connection. No REST refetch or reconnect is needed - your existing message handler applies them like any other update. resync_required is sent when complete state cannot be guaranteed: there was nothing cached to send, or the snapshot exceeded the per-connection limit (reason: "snapshot_truncated"). In those cases refetch from REST and discard the last_seq you stored so the next reconnect starts fresh. It is also sent with reason: "snapshot_cooldown" when you keep reconnecting with the same last_seq you were already served a snapshot for. No snapshot or replay is sent then, so treat it like any other resync_required: rebuild from REST and discard the stored last_seq. Do not simply adopt current_seq; the updates between the two would be lost. When you receive resync_required, rebuild your state from REST:

Fetch a fresh snapshot from /odds or /odds/multi with includeSeq=true
Read the X-OddsAPI-Seq response header
Reconnect to the WebSocket with lastSeq set to that value
You are now caught up with no gap

Example: Reconnect with Replay

class ReconnectingClient {
  constructor(apiKey, options = {}) {
    this.apiKey = apiKey;
    this.options = options;
    this.lastSeq = 0;
  }

  buildUrl() {
    const params = new URLSearchParams({ apiKey: this.apiKey });
    if (this.options.markets) params.set('markets', this.options.markets);
    if (this.options.sport) params.set('sport', this.options.sport);
    if (this.lastSeq > 0) params.set('lastSeq', String(this.lastSeq));
    return `wss://api.odds-api.io/v3/ws?${params}`;
  }

  connect() {
    this.ws = new WebSocket(this.buildUrl());

    this.ws.onmessage = (event) => {
      const data = JSON.parse(event.data);

      // Handle resync_required: rebuild from REST snapshot
      if (data.type === 'resync_required') {
        console.log('Resync required:', data.reason);
        this.resyncFromRest();
        return;
      }

      // Track seq from every update
      if (data.seq > this.lastSeq) {
        this.lastSeq = data.seq;
      }

      // Process the message
      this.handleMessage(data);
    };

    this.ws.onclose = () => {
      // Reconnect with lastSeq to get missed messages
      setTimeout(() => this.connect(), 1000);
    };
  }

  async resyncFromRest() {
    // Fetch fresh snapshot with seq cursor
    const res = await fetch(
      `https://api.odds-api.io/v3/odds/multi?apiKey=${this.apiKey}&includeSeq=true`
    );
    const seq = res.headers.get('X-OddsAPI-Seq');
    if (seq) {
      this.lastSeq = parseInt(seq, 10);
    }
    // Rebuild local state from response...
    const data = await res.json();
    this.rebuildState(data);
    // Reconnect with the snapshot seq
    setTimeout(() => this.connect(), 100);
  }
}

REST to WebSocket Handoff

You can obtain a seq cursor from REST API responses by adding includeSeq=true to the snapshot odds endpoints (/odds, /odds/multi). The current sequence number is returned in the X-OddsAPI-Seq response header.

curl -H "Accept: application/json" \
  "https://api.odds-api.io/v3/odds?apiKey=xxx&eventId=123&bookmakers=Bet365&includeSeq=true"

# Response header: X-OddsAPI-Seq: 482900

Use this seq value as lastSeq when opening your WebSocket connection to ensure no updates are missed between the REST snapshot and the live stream.

Best Practices

Use a Client That Compresses

permessage-deflate is required. Node ws, browsers and Python websockets negotiate it automatically; Python websocket-client and PHP textalk/websocket cannot, and are refused with HTTP 426. See Compression (Required).

Use Filters to Reduce Bandwidth

Use leagues or eventIds filters when you only need specific data. This significantly reduces bandwidth and improves performance.

Implement Reconnection Logic

Use lastSeq for gap-free reconnection. Always implement exponential backoff as a fallback. The connection is stable, but networks can drop.

Handle All Message Types

Handle welcome, created, updated, deleted, and no_markets to keep your data in sync.

Replace Markets, Never Merge Them

Each updated message contains the full current market set for that event and bookmaker, so overwrite what you have stored rather than merging into it.Merging is the most common integration mistake we see. A suspended market is dropped from the payload rather than marked, so if you merge, it stays in your data forever and you keep showing a price that is no longer available.

// Correct: the incoming set is the truth
state[`${data.id}-${data.bookie}`] = data.markets

// Wrong: suspended markets never go away
Object.assign(state[`${data.id}-${data.bookie}`], data.markets)

Two Connections Per API Key

Each API key can hold two connections at once, for example a primary and a standby. Opening a third closes the oldest, so reuse your connections instead of opening a new one per request. A new connection within 2 seconds of that is refused with close code 1013 (try again later), so wait a few seconds before reconnecting.

Process Updates Asynchronously

If receiving many updates, process them asynchronously to avoid blocking your main thread.

Benefits Over REST API

Feature	REST API	WebSocket
Latency	100-500ms (polling)	<150ms (push)
Request overhead	Multiple HTTP requests	Single persistent connection
Real-time updates	Manual polling	Automatic push
Bandwidth	Higher (repeated headers)	Lower (single connection)
Server load	Higher	Lower
Best for	Batch requests	Live updates

Get Access

Enable WebSocket Access

Subscribe to WebSocket as an add-on through your odds-api.io account

Next Steps

Fetching Odds

Learn about REST API odds fetching

Best Practices

Optimize your implementation

Value Bets

Prices above a fair-odds estimate

API Reference

Explore all API endpoints

​Why Use WebSocket?

Real-Time Updates

Lower Latency

Reduced Overhead

Better Scaling

​Access & Pricing

​Connection Details

​Close Codes

​Compression (Required)

​Filter Parameters

​Channels

​Example Connection URLs

​Welcome Message

​Error Responses

​Update Types

​Message Format

​Quick Start

​JavaScript Example

​Python Example

​PHP Example

​Handling Different Update Types

​Advanced Implementation: Live Odds Tracker

​React Integration

​Reconnection with Replay

​How It Works

​Connection URL with Replay

​Replay Behavior

​Knowing When Replay Is Done

​Replay Limits and Resync

​Example: Reconnect with Replay

​REST to WebSocket Handoff

​Best Practices

​Benefits Over REST API

​Get Access

Enable WebSocket Access

​Next Steps

Fetching Odds

Best Practices

Value Bets

API Reference

Why Use WebSocket?

Access & Pricing

Connection Details

Close Codes

Compression (Required)

Filter Parameters

Channels

Example Connection URLs

Welcome Message

Error Responses

Update Types

Message Format

Quick Start

JavaScript Example

Python Example

PHP Example

Handling Different Update Types

Advanced Implementation: Live Odds Tracker

React Integration

Reconnection with Replay

How It Works

Connection URL with Replay

Replay Behavior

Knowing When Replay Is Done

Replay Limits and Resync

Example: Reconnect with Replay

REST to WebSocket Handoff

Best Practices

Benefits Over REST API

Get Access

Next Steps