Skip to main content

​
Endpoint

Production gateway: 
wss://v5.oddspapi.io/ws
Your account may use a different region or hostname. Use the endpoint shown in your dashboard.
Use REST for snapshots and WebSocket for realtime updates:
  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

WebSocket supports login-only subscriptions. To change filters or channels, reconnect with a new login.

​
Message Envelope

All updates share a common 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

Control at login using receiveType.
  • "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.
Tip for clients: 
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

Limit TypeDescription
Concurrent connectionsEnforced per apiKey group (max: 5). See error 4003.
BackpressureIf your client can’t keep up, connection is closed (4002).
Replay windowSee resumeWindowMs in Resume & Replay
Message rateNot explicitly limited, but filters are recommended for performance

​
💬 Ask an AI Assistant

Want to explore or ask questions about this page using your favorite AI? Click one of the links below — each one opens this page in the selected tool with a pre-filled prompt: