Skip to main content

​
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

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:
FieldTypeDefaultDescription
game_idsstring[]-Subscribe to specific games. Use ["*"] for all matched games.
leaguesstring[]-Subscribe to all games in one or more leagues.
sportsstring[]-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