WebSocket API Overview - Realtime Sports Data Streaming

​

Endpoint

wss://v5.oddspapi.io/ws

​

Recommended Integration Flow (Production)

1. Fetch an initial snapshot via REST (e.g. /fixtures, /fixtures/odds)
2. Connect to the WebSocket and send login with filters
3. Start processing updates after receiving login_ok
4. Persist serverEpoch and per-channel lastSeenId (from entryId)
5. On reconnect, send serverEpoch + lastSeenId to resume
6. If you receive snapshot_required, re-fetch the snapshot via REST

​

Login Mode

​

Message Envelope

{
  "channel": "scores",
  "type": "UPDATE",
  "payload": { "...": "..." },
  "ts": 1765497902846,
  "entryId": "1765497902846-3221"
}

• channel – stream name (e.g. odds, fixtures)
• type – message type (currently always UPDATE)
• payload – channel-specific data
• ts – UTC timestamp (milliseconds)
• entryId – cursor for replay/resume

entryId is not guaranteed to be contiguous. See Resume & Replay for full explanation.

​

Encoding: JSON, Binary, or zstd

• "json" (default) — all messages arrive as UTF-8 JSON
• "binary" — data frames use MessagePack; control frames remain JSON
• "zstd" — dictless zstd-compressed JSON (~5–6× smaller on odds); decode in one line, no dictionary handling. Control frames remain JSON.
• "zstd-dict" — zstd with trained per-channel dictionaries (~7–9× on odds); the server pushes the dictionaries at connect. Self-describing per-frame, no per-channel logic. See Compression.

import msgpack from "@msgpack/msgpack";

const obj = typeof raw === "string"
  ? JSON.parse(raw)
  : msgpack.decode(new Uint8Array(raw));

Control messages like login_ok, snapshot_required, and resume_complete are always JSON, even in binary mode.

​

Channel Types

• Fixture-scoped: fixtures, scores, odds, bookmakers. — payloads include fixtureId
• Future-scoped: futures, bookmakersFutures, oddsFutures — include futureId
• Global: currencies — no ID

See /websocket/channels/* for per-channel schemas.

​

Throughput Guidance

• Prefer receiveType: "zstd" (or "zstd-dict" for the best ratio) on high-volume channels like odds — far smaller frames than binary
• Use filters (sportIds, bookmakers) to reduce noise
• odds should be treated as latest state, not a tick ledger

Need full price movement or closing line value? Use the REST Historical Odds & CLV endpoints.

​

WebSocket Limits

​

💬 Ask an AI Assistant

• Ask ChatGPT
• Ask Claude
• Ask Perplexity
• Ask Gemini