Live Odds

Stream real-time odds updates via WebSocket.

Overview

The live odds WebSocket provides real-time win and place odds for all runners during a race meeting. Odds are pushed every time the server receives an update — typically every 30-60 seconds on race days.

Requires Ultimate plan.

Connect to All Races

WS/ws/live/odds

Streams odds updates for all races in the current meeting.

const ws = new WebSocket(
  "wss://api.hkjc-api.com/ws/live/odds?api_key=YOUR_KEY"
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Race " + data.race_number + ":", data.runners);
};

ws.onerror = (err) => console.error("WS error:", err);
ws.onclose = () => console.log("Connection closed");

Connect to a Single Race

WS/ws/live/odds/{race_number}

Streams odds updates for a specific race only.

Message Format

Each message is a JSON object with the following shape:

{
  "event": "odds_update",
  "race_number": 3,
  "recorded_at": "2025-10-01T14:32:00+08:00",
  "runners": [
    { "horse_no": "4", "horse_name": "Example Horse", "win": 3.5, "place": 1.4 },
    { "horse_no": "1", "horse_name": "Speed King", "win": 8.0, "place": 2.8 }
  ]
}

Connection Lifecycle

  1. Connect — WebSocket handshake with API key
  2. Receive — Server pushes odds updates as they arrive
  3. Heartbeat — Server sends a ping every 30 seconds; respond with pong to keep the connection alive
  4. Close — Connection closes when the meeting ends or client disconnects