Sports Live WebSocket

Endpoint

wss://wss.predexon.com/v1/<API_KEY>

The websocket streams aggregate live-state changes keyed by game_id. It does not stream raw upstream provider messages by default.

Authentication

Pass your data key in the websocket URL:

wss://wss.predexon.com/v1/YOUR_DATA_KEY

On successful connection:

{
  "type": "connected",
  "message": "Connected to Predexon WebSocket"
}

Subscribe to all matched sports games Predexon currently covers:

{
  "action": "subscribe",
  "platform": "predexon",
  "version": 1,
  "type": "sports_live",
  "filters": {
    "game_ids": ["*"]
  }
}

Subscribe by league:

{
  "action": "subscribe",
  "platform": "predexon",
  "version": 1,
  "type": "sports_live",
  "filters": {
    "leagues": ["mlb"]
  }
}

Subscribe by game IDs:

{
  "action": "subscribe",
  "platform": "predexon",
  "version": 1,
  "type": "sports_live",
  "filters": {
    "game_ids": ["mlb-ari-pit-2026-05-07"]
  }
}

Filters:

Field	Type	Default	Description
`game_ids`	string[]	-	Subscribe to specific games. Use `["*"]` for all matched games.
`leagues`	string[]	-	Subscribe to all games in one or more leagues.
`sports`	string[]	-	Subscribe to all games in one or more sports.

Exactly one of game_ids, leagues, or sports is required. game_ids: ["*"] is the all-games subscription.

Unsubscribe

{
  "action": "unsubscribe",
  "subscription_id": "sub_01"
}

Server Messages

ack

{
  "type": "ack",
  "subscription_id": "sub_01",
  "channel": "sports_live"
}

event

{
  "type": "event",
  "subscription_id": "sub_01",
  "data": {
    "event_type": "sports_live_state",
    "sequence": 1842,
    "game_id": "mlb-ari-pit-2026-05-07",
    "league": "mlb",
    "sport": "baseball",
    "home_team": {
      "code": "pit",
      "name": "Pittsburgh Pirates"
    },
    "away_team": {
      "code": "ari",
      "name": "Arizona Diamondbacks"
    },
    "updated_at": "2026-05-07T23:42:10Z",
    "status": "InProgress",
    "live": true,
    "ended": false,
    "period": "Top 5",
    "clock": null,
    "score": {
      "home": 2,
      "away": 4,
      "display": "2-4"
    },
    "winner": null,
    "reliability": {
      "state": "single_source",
      "source_count": 1,
      "sources": ["polymarket"],
      "conflict": false,
      "stale": false
    }
  }
}

error

{
  "type": "error",
  "code": "INVALID_FILTERS",
  "message": "Sports live subscriptions require exactly one of game_ids, leagues, or sports"
}

Heartbeats

The gateway uses websocket ping/pong frames for connection liveness. Clients should respond to ping frames according to their websocket library’s normal behavior.

Reconnect Behavior

If the connection drops, reconnect and resubscribe. Use REST to rehydrate current state after reconnect:

GET /v2/sports/live?league=mlb

The websocket contract does not require replay cursors. A later version may add a since_sequence field.

Update Policy

The websocket emits an update when the aggregate changes materially:

Score changed
Period changed
Clock changed
Key incidents changed
live or ended changed
Winner changed
Reliability changed
Source conflict appeared or resolved
Stale state appeared or resolved

It does not emit every upstream heartbeat or duplicate source message.

Identifier Rules

Websocket updates are keyed by game_id. Trading and routing still use canonical outcome-level predexon_id.

game_id       -> broad real-world game
event_id      -> canonical market/question
predexon_id   -> canonical tradable outcome

Overview

Concepts

Sports Discovery API

Order Router

Endpoint

Authentication

Unsubscribe

Server Messages

ack

event

error

Heartbeats

Reconnect Behavior

Update Policy

Identifier Rules

​Endpoint

​Authentication

​Subscribe

​Unsubscribe

​Server Messages

​ack

​event

​error

​Heartbeats

​Reconnect Behavior

​Update Policy

​Identifier Rules

Endpoint

Authentication

Subscribe

Unsubscribe

Server Messages

ack

event

error

Heartbeats

Reconnect Behavior

Update Policy

Identifier Rules