WebSocket API

Connect from your server

Use wss://YOUR_SITE_HOST/ws/v1/odds with the header Authorization: Bearer YOUR_API_KEY.

Never put API keys in a URL or browser code. Browser-origin connections are rejected.

import WebSocket from 'ws';
const ws = new WebSocket(process.env.VANTAGE_WS_URL, {
  headers: { Authorization: `Bearer ${process.env.VANTAGE_API_KEY}` }
});
ws.on('message', raw => {
  const snapshot = JSON.parse(raw.toString());
  // Replace your previous rows, including when rows is empty.
  // Only use rows when snapshot.status === 'live'.
});

Messages contain type, version, status, rows and available timestamps. Each message is a complete replacement snapshot. A reconnect receives the current snapshot; historical replay is not provided.

bookmakerHeartbeat contains status, ageSeconds and observedAt (Unix milliseconds). Live means “0s ago”. For down, add elapsed seconds since observedAt to ageSeconds. Unknown must never display zero. Treat a heartbeat older than 15 seconds as unknown. Process heartbeat updates even when the odds version is unchanged; bookmakerUpdatedAt is only a price-change timestamp. Odds-feed status and bookmaker health are separate signals.

Allow two simultaneous connections per account. Respond to WebSocket pings; standard Node ws clients do this automatically. Retry failures with exponential backoff and jitter, up to 30 seconds. Do not immediately retry authentication failures.

Slow consumers disconnect with 1013. Key revocation or lost membership closes connections within 15 seconds with 1008. Server restarts use 1012.

Rows include fixtureId, id, home, away, competition, kickoff, selection, bookmakerOdds, fairOdds, ftaProbability (0–1), edgePercent (percentage points), bookmakerUpdatedAt and referenceUpdatedAt.