WebSocket Real-Time API

Connection

wss://api.sportsapipro.com/v2/football/ws?x-api-key=YOUR_API_KEY

Authentication

Pass your API key via:

Query string (recommended for browser clients): ?x-api-key=YOUR_API_KEY
Header: x-api-key: YOUR_API_KEY

Sport Selection

Optionally set the x-sport header during connection to scope live-scores to a specific sport (default: football).

x-sport must be sent as a connection header — it is not read from the query string. Passing ?x-sport=... in the URL is ignored and the connection stays scoped to football (the welcome frame echoes the applied sport, so check it). If your client cannot set headers, subscribe to match:{matchId} instead — that channel is sport-agnostic and works for any sport.

Supported values: football, basketball, ice-hockey, tennis, rugby, handball, volleyball, baseball, american-football, cricket, futsal, mma, motorsport, darts, snooker, badminton, table-tennis, beach-volley, cycling, esports, bandy, aussie-rules, floorball, minifootball, waterpolo.

Message Format

All messages are JSON. Send actions to subscribe/unsubscribe from channels:

{ "action": "subscribe", "channel": "live-scores" }
{ "action": "subscribe", "channel": "match:14109842" }
{ "action": "subscribe", "channel": "match:14109842:incidents" }
{ "action": "unsubscribe", "channel": "match:14109842" }
{ "action": "ping", "channel": "live-scores" }

Available Channels

Channel	Description	Delivery
`live-scores`	All live match scores & status changes (auto-scoped to your `x-sport`)	NATS push — sub-second
`live-scores:{sport}`	Live scores for a specific sport (e.g. `live-scores:basketball`)	NATS push — sub-second
`match:{matchId}`	Score & status updates for a single match	NATS push — sub-second
`match:{matchId}:incidents`	Goals, cards, substitutions, VAR, period markers	NATS-triggered fetch (~300ms) + 15s safety-net poll
`match:{matchId}:stats`	Match statistics (possession, shots, passes, fouls, corners)	NATS-triggered fetch (~300ms) + 30s safety-net poll
`match:{matchId}:odds`	Live odds for a single match — bet365 (provider 1) only	NATS-triggered fetch on match events (~300ms) + change-gated ~30s poll
`match:{matchId}:lineups`	Team lineups (typically available pre-match)	Polling — 60s interval
`match:{matchId}:point-by-point`	Point-by-point / play sequence (where the sport supports it)	NATS-triggered fetch

There is no global or sport-wide odds channel. Odds are per-match only — live-odds, odds:{sport}, and live-odds:{sport} are not valid channels and return an error frame. To follow odds across a sport, subscribe to live-scores (or live-scores:{sport}) to track which matches are live, then fan out one match:{matchId}:odds subscription per match on the same connection. A single socket handles many concurrent match subscriptions.

match:{matchId}:odds is a single-provider relay and is not sub-second. Verified in production:

Provider: the channel relays provider 1 (bet365) only — the upstream call is odds/1/all. There is no provider selector, no multi-provider WebSocket stream, and a provider query parameter is ignored. Multi-bookmaker odds are REST-only on the V4 feed (GET /v4/football/match/{matchId}/odds, per-bookmaker offers across a 179-book catalogue).
Market set: the same markets as GET /api/match/{matchId}/odds/all — typically 11–24 markets: Full time 1X2 (live and pre-match variants), Double chance, Draw no bet, Both teams to score, Match goals, Asian handicap, Corners 2-way, Cards in match, Next goal. Player props are not available on WebSocket or REST today.
Frames are complete snapshots, never deltas. Every snapshot and update carries the full { markets[], eventId, liveStreamUrl } state — replace your local state wholesale.
Cadence: ~300ms after a match event (goal, card, period change) via the NATS-triggered fetch; otherwise a change-gated ~30s refresh. Measured inter-frame gaps on live top-tier fixtures: 24s, 27s, 30s, 30s, and 63–149s where prices had not moved. Worst case for a pure price move with no match event is about 30 seconds — treat these odds as reference data, not as a live bet-acceptance gate.
timestamp is our server’s fetch/emit time in epoch milliseconds (receipt skew measured at 11–30ms). It is not a bookmaker-side fetch time; the upstream feed does not expose one.

Suspension and closure have no dedicated frame. Each market object carries suspended: true|false, so a suspension arrives as the next full snapshot with that market flagged. A market that disappears from markets[] is closed. Because of the cadence above, a suspension can reach you up to ~30s late unless a match event triggers the fast path.

Missed-update recovery: there is no sequence number, cursor, or replay buffer — and because every frame is a full snapshot, you don’t need one. On reconnect, resubscribe and you immediately receive a snapshot with current state that supersedes anything you missed. Recommended pattern: track lastFrameAt per match and, if it exceeds ~90s while the match is live, drop and re-establish the subscription rather than waiting. WebSocket traffic is unmetered, so aggressive resubscription is free.

WebSocket traffic does not count against your quota. The handshake and every frame you receive — subscriptions, snapshots, and updates — are unmetered, including the internal NATS-triggered fetches behind :odds, :incidents, and :stats. Only REST calls consume quota.

Delivery Modes

NATS push — Data is pushed directly from the real-time feed with no delay
NATS-triggered fetch — When any match update is detected, detailed data is fetched instantly (no waiting for poll cycle)
Polling — Data is fetched at regular intervals (used for lineups which rarely change)

No updates received?

If the connection opens and the welcome / subscribed frames arrive but no update frames follow, work through this list before assuming an outage:

Confirm the match is actually in progress with GET /v2/{sport}/live. This is the authoritative liveness source. The schedule endpoint lists a whole day of fixtures with a status snapshot, so a fixture you read there may already have finished — a finished match emits nothing on match:{matchId} or on live-scores.
Check the sport in the welcome frame. live-scores is scoped to it. Connecting on /v2/{sport}/ws sets the scope automatically; the subscribed frame confirms it as live-scores:{sport}.
Expect quiet gaps. Frames are emitted on change only. Between deliveries, at a wicket break, at half-time or during a rain delay, a genuinely live match can be silent for a minute or more. Test against a sport-wide live-scores subscription rather than one fixture.
Check natsConnected in the welcome frame. If it is false, push channels fall back to their safety-net poll cadence.
De-duplicate on changes.changeTimestamp. A single change can arrive two to three times on match:{matchId}, plus once more on live-scores — that is expected, not a bug.

Detecting match end

Status changes arrive on live-scores and match:{matchId} as partial updates with dotted keys, e.g. data["status.code"], not data.status.code. A match has finished when data["status.type"] === "finished". In normal time that means status.code 100 (“Ended”); after extra time or penalties the code differs.

Not every live match receives WebSocket frames. Some matches, mostly in lower-tier competitions, can play out with no updates at all, so no finished frame is ever sent for them. Pair the WebSocket with a /v2/football/api/live check every 30-60 seconds: when a match you show as live drops out of that list, call /v2/football/api/match/{id} once and mark it finished.

Fallback signal: match:{matchId}:incidents is also refreshed by a 15-second safety-net fetch, so it reaches you even when score/status frames don’t. Treat an incident with incidentType: "period" and text: "FT" as finished. In matches that go to extra time or penalties, wait for the final "AET" / "AP" marker instead, because FT there only ends normal time.

{"channel":"live-scores","type":"update","data":{"eventId":17228462,"winnerCode":3,"status.code":100,"status.description":"Ended","status.type":"finished","homeScore.current":4,"awayScore.current":4,"statusDescription":"FT","id":17228462},"source":"nats","timestamp":1791444917665}

Missed frames are not replayed. If a match is past 90’ and silent for ~3 minutes, confirm with one GET /v2/football/api/match/{id} call.

Live match minute

The minute is not sent as a number and there is no per-minute tick. You compute it from the period clock, which keeps it accurate to the second. When a period starts (kick-off, 2nd half, extra time), the update for that match carries the clock as dotted keys:

{"channel":"live-scores","type":"update","data":{"eventId":17011608,"status.code":7,"status.description":"2nd half","time.currentPeriodStartTimestamp":1792515784,"time.initial":2700,"time.max":5400,"time.extra":540,"lastPeriod":"period2","changes.changeTimestamp":1792515784,"id":17011608}}

Field	Meaning
`time.currentPeriodStartTimestamp`	Unix seconds when the current period started
`time.initial`	Seconds already played before this period (0, 2700, 5400, 6300)
`time.max`	Normal end of this period in seconds (2700, 5400, 6300, 7200)

Score-only updates do not repeat these fields, so keep the last values you received. For a match already in progress, call GET /v2/football/match/{matchId} once: match.time has the same fields. The /live list does not include them.

const elapsed = Math.floor(Date.now() / 1000) - t.currentPeriodStartTimestamp + t.initial;
const minute = Math.floor(elapsed / 60);
const maxMin = t.max / 60;
const label = minute > maxMin ? `${maxMin}+${minute - maxMin}'` : `${minute}'`;

Show HT when status.description is "Halftime" (stop the clock) and FT when status.type is "finished". Penalty shoot-outs have no running clock. Run a local one-second timer and replace the stored values whenever an update arrives with time.* fields.

What’s delivered on `:incidents`

The match:{matchId}:incidents channel covers every discrete event the live feed emits:

Incident	Delivered	Detail
`goal`	Yes	Scorer, assist, minute
`card` (yellow/red)	Yes	Player, minute, `incidentClass: "yellow"\|"red"`, `reason` (e.g. `"Foul"`)
`substitution`	Yes	Player in/out, minute
`varDecision`	Yes	Decision type, minute
Injury time / period markers	Yes	Added time and phase transitions
Generic fouls (no card)	No	Not tracked as discrete incidents

Non-carded fouls are not emitted as incidents. If you need foul counts, subscribe to match:{matchId}:stats — it carries the aggregate per-team foul count, updated in real time. There is no per-player foul stream.

The welcome payload surfaces "natsConnected": true while the NATS bridge is healthy. If it ever reports false, channels fall back to their safety-net poll cadence (15s for :incidents, 30s for :stats) — your code keeps working without changes.

Response Types

`welcome`

Sent immediately on connection:

{
  "type": "welcome",
  "message": "SportsAPIData WebSocket v3.1 — All Channels Sub-Second",
  "sport": "football",
  "natsConnected": true,
  "channels": ["live-scores", "match:{matchId}", "..."]
}

`subscribed`

Confirms a channel subscription:

{
  "type": "subscribed",
  "channel": "match:14109842:incidents",
  "mode": "realtime (NATS-triggered fetch, 15000ms safety-net poll)"
}

`snapshot`

Last known data sent immediately upon subscribing (if available):

{
  "channel": "match:14109842",
  "type": "snapshot",
  "data": { ... },
  "timestamp": 1710729600000
}

`update`

New data pushed in real-time:

{
  "channel": "match:14109842:incidents",
  "type": "update",
  "data": { ... },
  "source": "nats",
  "timestamp": 1710729600437
}

`pong`

Response to a ping (for keep-alive):

{
  "type": "pong",
  "channel": "live-scores",
  "timestamp": 1710729600000
}

Quick Start Examples

const ws = new WebSocket('wss://api.sportsapipro.com/v2/football/ws?x-api-key=YOUR_API_KEY');

ws.onopen = () => {
  // Subscribe to all live football scores
  ws.send(JSON.stringify({ action: 'subscribe', channel: 'live-scores' }));

  // Subscribe to a specific match's incidents (goals, cards, subs)
  ws.send(JSON.stringify({ action: 'subscribe', channel: 'match:14109842:incidents' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(`[${msg.type}] ${msg.channel}:`, msg.data);
};

import websockets, asyncio, json

async def connect():
    uri = "wss://api.sportsapipro.com/v2/football/ws?x-api-key=YOUR_API_KEY"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({"action": "subscribe", "channel": "live-scores"}))
        async for message in ws:
            data = json.loads(message)
            print(f"[{data['type']}] {data.get('channel', '')}")

asyncio.run(connect())

wscat -c "wss://api.sportsapipro.com/v2/football/ws?x-api-key=YOUR_API_KEY"
> {"action":"subscribe","channel":"live-scores"}
> {"action":"subscribe","channel":"match:14109842:incidents"}
> {"action":"ping","channel":"live-scores"}

Best Practices

Use incidents for real-time match events

Use match:{id}:incidents for real-time match events rather than polling the REST endpoint.

Handle snapshot messages

When you subscribe, you immediately get the last known state so your UI is never blank.

Send periodic pings

Send {"action":"ping","channel":"live-scores"} every 30s to keep the connection alive.

Reconnect with backoff

If disconnected, reconnect with exponential backoff (1s, 2s, 4s, 8s…).

Unsubscribe when done

Unsubscribe from match channels when the user navigates away.

API Reference

Guides

Popular Sports

Team Sports

Racquet & Precision Sports

Specialty Sports

V3 API

V4 Odds API

V6 AiScore API

V1 Legacy

Football V1

Basketball V1

Tennis V1

Hockey V1

Connection

Authentication

Sport Selection

Message Format

Available Channels

Delivery Modes

No updates received?

Detecting match end

Live match minute

What’s delivered on `:incidents`

Response Types

`welcome`

`subscribed`

`snapshot`

`update`

`pong`

Quick Start Examples

Best Practices

​Connection

​Authentication

​Sport Selection

​Message Format

​Available Channels

​Delivery Modes

​No updates received?

​Detecting match end

​Live match minute

​What’s delivered on :incidents

​Response Types

​welcome

​subscribed

​snapshot

​update

​pong

​Quick Start Examples

​Best Practices

Connection

Authentication

Sport Selection

Message Format

Available Channels

Delivery Modes

No updates received?

Detecting match end

Live match minute

What’s delivered on `:incidents`

Response Types

`welcome`

`subscribed`

`snapshot`

`update`

`pong`

Quick Start Examples

Best Practices