Live odds WebSocket architecture: build a dependable real-time stream

1. The reference architecture for a live odds stream

A WebSocket is a transport, not an odds database. The connection delivers a baseline and changes; your application must turn those messages into a coherent current state. Put that responsibility in one backend consumer and let product surfaces read from your local book.

The consumer owns connection lifecycle, subscriptions, snapshot loading, update ordering and reconnects. The odds book owns the current event and market state. A separate fan-out layer can serve dashboards, line-movement calculations, storage or internal events without making every browser open its own paid socket.

Design boundaries that keep the system understandable

• Transport boundary: parse frames, respond to ping, track close codes and never put business rules in the socket callback.
• State boundary: merge records by event ID and market identity; expose immutable or copied views to downstream code.
• Decision boundary: run alerts, no-vig calculations and model triggers from committed state, not from a half-applied frame.
• Presentation boundary: browsers read your compact API or server-pushed UI stream; they do not receive your PinnWire key.

2. Choose REST, SSE or the raw WebSocket intentionally

All three PinnWire surfaces are useful, but they answer different questions. A reliable architecture chooses the smallest surface that satisfies the feature.

Use REST to render the first page or recover a single event. Use SSE when the requirement is “tell me when a price falls.” Choose the raw WebSocket when the requirement is “keep this set of markets current and react to every subscribed update.” PinnWire lets one product use all three without forcing a WebSocket-sized architecture onto a simple lookup.

3. Understand the PinnWire Pinnacle WebSocket API lifecycle

The protocol is deliberately small. A client should be able to explain every phase: authenticate, subscribe, load a baseline, apply updates, maintain the heartbeat, and reconnect when the server closes the connection.

// Header form for a server-side client
new WebSocket("wss://pinnwire.com/ws", {
  headers: { "x-api-key": process.env.PINNWIRE_KEY }
});

// Query form, useful for browsers and simple tools
wss://pinnwire.com/ws?key=YOUR_KEY

{
  "type": "subscribe",
  "streams": ["live", "prematch"],
  "sport_ids": [1, 2],
  "event_ids": [1631005165]
}

{
  "type": "snapshot",
  "stream": "live",
  "sport_id": 1,
  "seq": 0,
  "final": true,
  "ts": 1766788800000,
  "events": [ /* current event records */ ]
}

{ "type": "unsubscribe", "streams": ["live"], "sport_ids": [2] }
{ "type": "unsubscribe", "streams": ["prematch"], "event_ids": [1631005165] }

4. Build a version-aware odds book

The most common WebSocket bug is treating a stream as a sequence of complete, perfectly ordered objects. Build state explicitly. A good reducer has three rules:

1. Identify the event by rec.id. Never use team names as identity; names can be normalized, abbreviated or changed.
2. Identify a market by its stable key. Prefer m.key. If a market key is absent, use a deterministic fallback such as type|period|side|points.
3. Dedupe per market version. Compare markets[i].version, not a record-level version. Ignore an update that is not newer than the copy already committed.

const events = new Map();

function marketIdentity(m) {
  return m.key ?? [m.type, m.period, m.side, m.points].join("|");
}

function mergeRecord(rec) {
  if (!rec || rec.id == null) return;

  const prior = events.get(rec.id) ?? { id: rec.id, markets: [] };
  const byMarket = new Map((prior.markets ?? []).map((m) => [marketIdentity(m), m]));

  for (const market of rec.markets ?? []) {
    const key = marketIdentity(market);
    const old = byMarket.get(key);
    // The market version is the ordering signal, not rec.version.
    if (old?.version != null && market.version != null
        && market.version <= old.version) continue;

    if (market.status !== "open") byMarket.delete(key);
    else byMarket.set(key, market);
  }

  events.set(rec.id, {
    ...prior,
    ...rec,
    id: rec.id,
    markets: [...byMarket.values()]
  });
}

function deleteRecord(id) {
  events.delete(id);
}

The exact record shape can contain more fields than this reducer needs. Preserve those fields when you pass an event to downstream code, but keep the merge key small and deterministic.

Make snapshot application atomic

For a chunked snapshot, collect chunks by subscription and sequence, then commit the complete baseline as one generation. Do not let a dashboard see half of a large baseline while it is being assembled. A simple generation counter works:

const snapshotBuffer = new Map();

function acceptSnapshot(frame) {
  const key = `${frame.stream}:${frame.sport_id ?? frame.event_ids?.join(",")}`;
  const bucket = snapshotBuffer.get(key) ?? [];
  bucket[frame.seq ?? 0] = frame.events ?? [];
  snapshotBuffer.set(key, bucket);

  // A single-frame snapshot has no final/seq markers.
  if (frame.final === true || (frame.seq == null && frame.final == null)) {
    const allEvents = bucket.flat();
    for (const event of allEvents) mergeRecord(event);
    snapshotBuffer.delete(key);
  }
}

In a production reducer, namespace the buffer with a subscription generation so a reconnect cannot mix an old chunk with a new snapshot. When a reconnect starts, discard all incomplete snapshot buffers first.

5. A reconnecting Node.js consumer

The following skeleton uses the popular Node ws client. It keeps one connection, sends a subscription immediately, answers pings, applies snapshots and updates, and reconnects with exponential backoff plus jitter. Keep this process on your backend, where PINNWIRE_KEY is not exposed to a browser.

import WebSocket from "ws";

const KEY = process.env.PINNWIRE_KEY;
const ENDPOINT = `wss://pinnwire.com/ws?key=${encodeURIComponent(KEY)}`;
const subscription = {
  type: "subscribe",
  streams: ["live", "prematch"],
  sport_ids: [1, 2]
};

let socket;
let retry = 0;
let stopping = false;

function connect() {
  if (stopping) return;
  socket = new WebSocket(ENDPOINT, { perMessageDeflate: true });

  socket.on("open", () => {
    retry = 0;
    socket.send(JSON.stringify(subscription));
  });

  socket.on("message", (raw) => {
    let frame;
    try { frame = JSON.parse(raw.toString()); }
    catch { return; }

    if (frame.type === "ping") {
      socket.send(JSON.stringify({ type: "pong" }));
      observeBacklog(frame.buffered_max_bytes);
      return;
    }
    if (frame.type === "snapshot") return acceptSnapshot(frame);
    if (frame.type === "live") {
      if (frame.op === "del") deleteRecord(frame.rec?.id);
      else mergeRecord(frame.rec);
      return;
    }
    if (["prematch_ws", "prematch_matchups", "prematch_markets"].includes(frame.type)) {
      mergeRecord(frame.rec);
      return;
    }
    if (frame.type === "error") console.error("PinnWire WebSocket error", frame);
  });

  socket.on("close", (code, reasonBuffer) => {
    const reason = reasonBuffer.toString();
    if (code === 1008 && /invalid key|plan lacks ws/i.test(reason)) {
      console.error("Configuration error; will not reconnect", code, reason);
      return;
    }
    resetIncompleteSnapshots();
    scheduleReconnect();
  });

  socket.on("error", (error) => console.error("socket", error.message));
}

function scheduleReconnect() {
  const base = Math.min(30_000, 1_000 * 2 ** retry++);
  const jitter = Math.floor(Math.random() * 500);
  setTimeout(connect, base + jitter);
}

connect();

The handlers above call the reducer from the previous section. In your implementation, reset the local book or mark it “resyncing” before accepting the next snapshot. A reconnect is a new synchronization point, not a continuation of the old session.

Browser fan-out pattern

If a dashboard needs browser updates, keep the PinnWire socket in the backend and expose a small internal SSE or WebSocket endpoint from your application. Send only the compact event fields the UI needs. This keeps the API key private, prevents every user tab from consuming the one-connection allowance, and gives you a place to rate-limit UI clients.

browser  ←  your /ui-stream  ←  local odds book  ←  PinnWire /ws

// Example compact browser event
{
  "event_id": 1631005165,
  "market": "moneyline|num_0|home|",
  "price": 1.94,
  "version": 9281,
  "stream": "live"
}

6. Backpressure, compression and operational safety

Live sports data arrives in bursts. A consumer that parses correctly but cannot drain its socket is still unhealthy. PinnWire exposes a useful operational signal and a clear failure mode so you can handle that condition rather than silently falling behind.

Backpressure is part of the contract

Every server ping includes buffered_max_bytes, the high-water send backlog observed since the previous ping. Record it as a time series. If it trends upward, reduce the number of subscriptions, move parsing to a dedicated process, optimize downstream work, or scale the consumer horizontally by key. Do not open a second connection with the same key: a newer connection evicts the older one.

PinnWire closes a socket whose buffered amount exceeds 32 MB with code 1011 and reason deregistered: slow_consumer. That is a recoverable synchronization event. Drop stale queued work, reconnect, resubscribe and rebuild from the snapshot. A queue that keeps every old price is usually worse than a clean resync.

Compression is a measured choice

permessage-deflate is negotiated per connection. It can reduce bandwidth on a distant or narrow link, but compression and decompression add CPU and can add a latency tail during bursts. Start with it enabled for a constrained link, measure parse-to-commit latency and memory, and disable it when CPU—not bandwidth—is the bottleneck.

Subscription scope is a performance control

• Use event IDs for an event page, bet-slip validator or focused model.
• Use sport IDs for a broad scanner, then fan out decisions from one backend book.
• Split different workloads across separate API keys when they need independent lifecycle or throughput; never split one key across competing workers.
• Unsubscribe events after they close or leave the product's active scope.

Reconnect without creating a storm

Back off from roughly one second toward 30 seconds with jitter. Reset the backoff after a stable open. Treat authentication and entitlement errors as configuration failures, not transient failures. For stale, eviction and slow-consumer closes, reconnect. Add logs for connection generation, subscription acknowledgement, snapshot completion, last pong, close code/reason and the latest buffered high-water mark.

7. Production checklist

Before you call a real-time odds stream production-ready, verify the whole lifecycle—not just that a few frames appeared in a terminal.

1. Keep the PinnWire key in a server-side secret store. Browser code receives only your compact API.
2. Send a valid subscription immediately after open, and assert that every requested scope receives a subscribed acknowledgement.
3. Do not publish state until the snapshot is complete; handle both one-frame and chunked snapshots.
4. Merge by rec.id and market key, compare markets[i].version, and remove closed markets.
5. Answer every 30-second ping with pong and alarm before the 75-second stale threshold.
6. Record close codes and implement backoff; never reconnect indefinitely on invalid credentials or a missing add-on.
7. Test a slow parser and a deliberately blocked downstream queue so slow_consumer recovery is real.
8. Measure your own network and processing latency. PinnWire removes the polling interval; end-to-end latency still depends on region, link, parsing and your downstream work.