Stream APIBeta

Overview

Delta streams are the low-bandwidth alternative to the WebSocket feed: one socket, as many bookmakers and sports as your plan allows, prematch and live. Each stream sends its full board once (in ~1 MB pages) and then, once per second, only what changed — keyed by market and selection, so a client keeps an exact copy of every board with a few KB/s instead of hundreds. Available on PRO, MAX and ULTRA.

Connect

Declare the whole subscription in the URL; the server checks it against your plan before the upgrade and subscribes every bookmaker × sport × kind that exists:

wss://api.pulsescore.net/api/stream/ws?key=YOUR_API_KEY&bookmakers=bet365,onexbet&sports=soccer,tennis&kinds=live,prematch
# bookmakers=all for every bookmaker; kinds defaults to both
# optional, prematch only: &markets=MATCH_RESULT,TOTALS &from=2026-09-12T00:00:00Z&to=2026-09-13T00:00:00Z

For per-stream league filters or to resume streams after a drop, connect with only key and send one JSON message within 5 seconds:

{"streams":[
  {"bookmaker":"bet365","kind":"prematch","sport":"soccer","league":"United Kingdom||England Premier League"},
  {"bookmaker":"onexbet","kind":"live","sport":"soccer","since":7684229893122425111}
]}

Capabilities

GET /api/stream/capabilities (no key needed) is the source of truth for what you can declare: the socket path, the protocol version, the limits of every plan, and each bookmaker with the sports it streams live and prematch. Sport lists follow what each bookmaker publishes and are refreshed every 10 minutes.

{ "protocol": 2, "endpoint": "/api/stream/ws", "discoveredAt": "…",
  "plans": { "pro":   { "connections": 1, "sports": 1,    "bookmakers": 1000 },
             "max":   { "connections": 2, "sports": 3,    "bookmakers": 1000 },
             "ultra": { "connections": 3, "sports": 1000, "bookmakers": 1000 } },        // 1000 = all
  "bookmakers": [ { "id": "bet365", "label": "Bet365", "prematchSports": ["soccer", …], "liveSports": ["soccer", …] }, … ] }

Plan Limits

Counted per account across all your connections; live and prematch of the same sport count once.

Refusals before the upgrade

Anything that can never stream is refused during the HTTP handshake, before a socket exists, with a JSON body {"error", "message"}. Browsers surface these as a 1006 close; every other client sees the status.

Frames

Every frame that belongs to a stream carries stream (bookmaker/kind/sport). Events inside snapshots and upserts are exactly the documents the REST API serves.

{"t":"connected","plan":"ultra","protocol":2,"limits":{"connections":3,"sports":1000,"bookmakers":1000},"streams":[…]}   // 1000 = all
{"t":"snapshot","stream":"bet365/prematch/soccer","seq":…,"part":1,"of":224,"events":[…]}   // pages of ~1 MB
{"t":"snapshot_end","stream":"bet365/prematch/soccer","seq":…,"count":1781}
{"t":"resumed","stream":"onexbet/live/soccer","seq":<your since>}          // instead of a snapshot when since was honoured
{"t":"delta","stream":"onexbet/live/soccer","seq":…,"ts":"…","changes":[
  {"eventId":"E1","op":"upsert","event":{…}},
  {"eventId":"E2","op":"remove","reason":"expired"},                         // expired | removed | filtered
  {"eventId":"E3","op":"patch","set":{"score":{…}},"mSet":[{"k":"<marketId>","isActive":false}],
   "sel":[{"m":"<marketId>","k":"<selectionId>","odds":2.1,…}],"selDel":[{"m":"<marketId>","k":"<selectionId>"}]}]}
{"t":"hb"}                                                                   // every 10 s when idle
{"t":"error","stream":"bet365/live/curling","code":4004,"message":"…","validSports":[…]}   // per stream, socket stays open
{"t":"error","stream":"onexbet/live/soccer","code":4031,"message":"…"}      // per stream: a fresh snapshot follows
{"t":"error","code":1012,"message":"Service restarting, reconnect with since="}          // socket-level: a close frame follows

Apply a patch in the order set → unset → mDel → mAdd → mSet → selDel → sel; markets are keyed by marketId and selections by selectionId. Every value is absolute, so re-applying a frame is harmless. Changes that happen while your snapshot pages are still arriving are sent as one catch-up delta afterwards — a slow reader never misses anything. Keep the last seq per stream and pass it as since on reconnect to resume without a new snapshot (120 s window).

Applying deltas

Keep one board per stream: a map of events by eventId; inside an event keep markets as an ordered map by market key and each market's selections by selection key.

• Market key = marketId when present and non-empty, else canonicalMarket|period|line|rawName (missing parts are empty strings). Selection key = selectionId, else canonicalOutcome|rawName|line. Numbers in keys have no exponent and no trailing .0, booleans are true/false, ObjectIDs are 24-hex; a numeric eventId is rendered the same way.
• Apply a patch in the order set → unset → mDel → mAdd → mSet → selDel → sel. set assigns whole top-level values (a value may be null); unset deletes; mDel deletes markets by key; mAdd inserts full markets (an existing key is replaced in place); mSet merges scalars into the market without touching selections, a null value removes that scalar; selDel deletes selections; sel replaces the whole selection object (m and k are addressing only).
• upsert replaces the event, remove deletes it, a snapshot with part: 1 resets the board. Every value is absolute, so re-applying a frame is idempotent.
• Never sent, never diffed: _id, createdAt, updatedAt, markets[].updatedAt, markets[].oddsSig. Market and selection order on the wire is not significant. Numeric ids above 2^53 cannot be parsed exactly by JavaScript; the bookmakers streamed today send such ids as strings.

The reference clients below implement exactly these rules and are tested against the server's own diff engine.

Resuming with since

seq is the Mongo cluster time of the newest change on that stream, so it is identical across our servers and only ever grows on a socket. After a drop, reconnect with the payload form and since = the last seq you applied, per stream. Within the 120-second ring buffer you get resumed plus only the deltas you missed; otherwise a full snapshot whose part 1 resets that board. Three cases always start with a snapshot: filtered prematch streams, a stream that reports seq: 0 (no change since it was activated), and a since older than the ring. Redeclare exactly the streams connected listed (bookmaker, kind, sport, filters) so your plan counters do not change.

What happens when we deploy

Our deploys never cost you your board. The new process loads the live state, catches up and starts accepting before the old one lets go, then every socket receives one error frame and close with code 1012. Reconnect immediately with since per stream: the server answers resumed and the handful of deltas you missed. Measured end to end: reconnected in about 0.35 s, no snapshot, no interval between two deltas longer than the stream's normal one second. A client that does not reconnect on 1012 stays disconnected.

Reconnect rules

• Reconnect with exponential backoff (0.5 s doubling to 30 s, jittered) on 1012, 1006, 4029, 4429, 4030 and 1009, and on a 502 / 503 / 429 handshake refusal. Honour retryAfterSec when the error frame carries one.
• Stop on 4001, 4003, 4010, 4011, 4012, 4013, 4032, 4034 and 4035 — a retry cannot fix those. 4012 in particular means another of your own clients took the slot.
• Keep your boards across the reconnect; only a snapshot with part: 1 resets one. Treat 4031 and 1013 as per-stream notices the server handles by itself.
• Before the upgrade, refusals are plain HTTP with a JSON body: 401 key, 402 plan / subscription / declaration over your caps, 403 blocked, 429 cooldown, 400 bad declaration, 503 auth temporarily unavailable.

Close codes

Filters (prematch streams)

• league: exact, case-insensitive match on the event's league, spelled the way that bookmaker spells it (bet365: United Kingdom||England Premier League); payload form only.
• from / to: inclusive RFC 3339 bounds on startTime; events without a start time are excluded when a bound is set.
• markets: keeps only markets whose canonicalMarket or marketId is listed (case-sensitive, at most 256); events keep streaming even when none of their markets match.
• An event entering your view arrives as upsert, one leaving it as remove with reason: "filtered"; patches are cut to the allowed markets. Live streams accept no filters, and filtered streams always start with a snapshot.

Keeping the socket alive

The server sends hb when nothing else went out for 10 seconds and pings every 30 seconds; a client that does not answer pings for about 65 seconds is dropped (browsers and every mainstream library answer them for you). Send nothing after the declaration. Your key is re-checked every 5 minutes: a revoked key, a blocked account or a lapsed subscription closes the socket with 4010 or 4013, a plan change applies the new limits and closes the connections that no longer fit with 4011, oldest kept first.

Limits

Sports and bookmaker names

Bookmaker ids and sport keys are exactly the strings /api/stream/capabilities lists per bookmaker and kind — kebab-case sports such as table-tennis or ice-hockey; esports and e-sports are the same sport on every bookmaker (the legacy live feed's validSports keeps each bookmaker's own spelling, bet365's being e-sports). Every frame's stream id uses the bookmaker's own spelling. The lists follow what each bookmaker publishes and are refreshed every 10 minutes; a sport a bookmaker no longer has answers 4004 on your next connect. Event, market and selection ids are per bookmaker.

Latency and bandwidth

Changes are batched once per second per stream, so a delta typically arrives 1–2 seconds after the bookmaker's write; this is not a sub-second feed. Frames are compressed with permessage-deflate when your client offers it (6–9× smaller on the wire): a live soccer stream of one bookmaker is roughly 50–150 KB/s uncompressed, and a full prematch soccer board of a large bookmaker is 20–450 MB for its snapshot. Each stream's snapshot pages interleave fairly with the other streams' deltas, so a big board never holds the others back.

Reference clients

Two dependency-free files implement everything above — the board applier, the per-stream router and a connection keeper that reconnects, redeclares with since and stops on the fatal codes: apply.js (ES module, browser or Node ≥ 22) and apply.py (Python ≥ 3.8; the connection keeper uses the websockets package).

import { StreamConnection } from "./apply.js";

const conn = new StreamConnection({
  url: "wss://api.pulsescore.net/api/stream/ws",
  key: "YOUR_API_KEY",
  streams: [                                     // or put bookmakers=&sports= in the url instead
    { bookmaker: "bet365", kind: "live", sport: "soccer" },
    { bookmaker: "bet365", kind: "prematch", sport: "soccer", markets: ["MATCH_RESULT"] },
  ],
  onFrame: ({ stream, type }, client) => {
    if (type === "delta" || type === "snapshot_end") render(stream, client.board(stream).toArray());
  },
  onState: (state, info) => console.log(state, info),   // connecting | open | reconnecting | closed
});
conn.connect();
// conn.close() when done

import asyncio
from apply import StreamConnection                 # pip install websockets

conn = StreamConnection(
    "wss://api.pulsescore.net/api/stream/ws", key="YOUR_API_KEY",
    streams=[{"bookmaker": "bet365", "kind": "live", "sport": "soccer"}],
    on_frame=lambda stream, kind, client, raw: kind == "delta" and render(stream, client.board(stream).to_list()),
    on_state=lambda state, info: print(state, info),
)
asyncio.run(conn.run())                            # returns on a fatal close or conn.close()

Without the keeper, feed frames to StreamClient.apply() and reconnect yourself with the payload form and client.since().

FAQ

• I reconnected with since and got a snapshot. The stream was filtered, had seq: 0, or your since was older than the 120-second ring. The snapshot resets that board.
• I keep getting 4012. Another client of your own account took the slot: the stream connection cap, or the per-bookmaker socket budget shared with the legacy WebSocket. Close the other client instead of retrying.
• 402 on sports although I declared few. Sports and bookmakers are counted across all your open connections; the message names the total the declaration would reach.
• Can I add a stream without reconnecting? No — the declaration is fixed for the life of the socket; open another connection or reconnect with the new set.
• Can the deploy lose changes? No. Every change is delivered at least once; re-applying a frame is harmless because every value is absolute.

The full wire contract — key derivation, filters, close codes, the resume rules and reference appliers for JavaScript and Python — is published by the stream service itself: /api/stream/doc.