> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise.predexon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sports Live WebSocket

> WebSocket contract for live sports score and game-state updates

## Endpoint

```text theme={null}
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:

```text theme={null}
wss://wss.predexon.com/v1/YOUR_DATA_KEY
```

On successful connection:

```json theme={null}
{
  "type": "connected",
  "message": "Connected to Predexon WebSocket"
}
```

## Subscribe

Subscribe to all matched sports games Predexon currently covers:

```json theme={null}
{
  "action": "subscribe",
  "platform": "predexon",
  "version": 1,
  "type": "sports_live",
  "filters": {
    "game_ids": ["*"]
  }
}
```

Subscribe by league:

```json theme={null}
{
  "action": "subscribe",
  "platform": "predexon",
  "version": 1,
  "type": "sports_live",
  "filters": {
    "leagues": ["mlb"]
  }
}
```

Subscribe by game IDs:

```json theme={null}
{
  "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

```json theme={null}
{
  "action": "unsubscribe",
  "subscription_id": "sub_01"
}
```

## Server Messages

### ack

```json theme={null}
{
  "type": "ack",
  "subscription_id": "sub_01",
  "channel": "sports_live"
}
```

### event

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```text theme={null}
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`.

```text theme={null}
game_id       -> broad real-world game
event_id      -> canonical market/question
predexon_id   -> canonical tradable outcome
```