> ## 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.
# FIFA World Cup WebSocket
> Canonical live game-state websocket for FIFA World Cup games
## Overview
The FIFA World Cup websocket streams canonical live game data for FIFA World Cup games covered by Predexon.
This is a game-state feed, not a market discovery feed. It sends live score, status, period, clock, winner, and key game-event updates when available. Messages are normalized by Predexon and do not expose provider attribution.
This channel is exclusively for FIFA World Cup game data. Use the sports discovery endpoints to discover tradable markets and outcomes; use this websocket to monitor the underlying live game state.
## Endpoint
```text theme={null}
wss://wss.predexon.com/v1/
```
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 FIFA World Cup games covered by Predexon:
```json theme={null}
{
"action": "subscribe",
"platform": "predexon",
"version": 1,
"type": "sports_fifa_world_cup",
"filters": {
"polymarket_event_ids": ["*"]
}
}
```
Subscribe by Polymarket Gamma event ID:
```json theme={null}
{
"action": "subscribe",
"platform": "predexon",
"version": 1,
"type": "sports_fifa_world_cup",
"filters": {
"polymarket_event_ids": ["351718"]
}
}
```
Subscribe by Polymarket sports game ID:
```json theme={null}
{
"action": "subscribe",
"platform": "predexon",
"version": 1,
"type": "sports_fifa_world_cup",
"filters": {
"polymarket_game_ids": ["90086910"]
}
}
```
Subscribe to all covered games but only receive selected key incident pushes:
```json theme={null}
{
"action": "subscribe",
"platform": "predexon",
"version": 1,
"type": "sports_fifa_world_cup",
"filters": {
"polymarket_event_ids": ["*"],
"event_types": ["score_change", "red_card", "yellow_card"]
}
}
```
Subscribe to deterministic mock live data on the same production channel:
```json theme={null}
{
"action": "subscribe",
"platform": "predexon",
"version": 1,
"type": "sports_fifa_world_cup",
"filters": {
"polymarket_event_ids": ["*"],
"mock": "live"
}
}
```
Exactly one primary subscription filter should be supplied.
| Filter | Type | Description |
| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `polymarket_event_ids` | string\[] | Polymarket Gamma event IDs. Use `["*"]` for all covered FIFA World Cup games. |
| `polymarket_game_ids` | string\[] | Polymarket sports game IDs. |
| `event_types` | string\[] | Optional event-type filter for `game_event` pushes. Does not count as the primary subscription filter. If omitted, all available event types are sent. |
| `mock` | string | Optional deterministic mock stream for integration testing. Use `live` for an in-progress game stream or `final` for an ended-game snapshot. Does not count as the primary subscription filter. |
## All Live Games Snapshot
When subscribing with `polymarket_event_ids: ["*"]`, the server sends an initial `live_games_snapshot` message containing the current live snapshot for all covered FIFA World Cup games.
If no covered FIFA World Cup games are live at subscription time, the server still sends the snapshot message with an empty `games` array. The connection remains open and future `game_state` and `game_event` messages are delivered when games become active.
After the initial snapshot, the websocket streams `game_state` updates as individual games change and `game_event` messages when key incidents are available.
```json theme={null}
{
"type": "event",
"subscription_id": "sub_01",
"channel": "sports_fifa_world_cup",
"data": {
"event_type": "live_games_snapshot",
"sequence": 1841,
"games": [
{
"polymarket_event_id": "351718",
"polymarket_game_id": "90086910",
"polymarket_slug": "fifwc-usa-par-2026-06-12",
"league": "fifwc",
"sport": "soccer",
"title": "United States vs Paraguay",
"scheduled_start": "2026-06-13T01:00:00Z",
"home_team": {
"code": "usa",
"name": "United States"
},
"away_team": {
"code": "par",
"name": "Paraguay"
},
"status": "in_progress",
"status_text": "Second Half",
"live": true,
"ended": false,
"period": "2H",
"clock": "58'",
"score": {
"home": 1,
"away": 0,
"display": "1-0"
},
"penalty_score": null,
"winner": null,
"last_play": {
"description": "Goal for United States",
"period": "2H",
"clock": "58'"
},
"significant_events": [
{
"id": "evt_01jz8d2h7q",
"type": "score_change",
"period": "2H",
"clock": "58'",
"team": "home",
"team_code": "usa",
"description": "Goal for United States"
}
],
"updated_at": "2026-06-13T02:18:22Z"
}
],
"updated_at": "2026-06-13T02:18:22Z"
}
}
```
No live games:
```json theme={null}
{
"type": "event",
"subscription_id": "sub_01",
"channel": "sports_fifa_world_cup",
"data": {
"event_type": "live_games_snapshot",
"sequence": 1841,
"games": [],
"updated_at": "2026-05-19T22:18:22Z"
}
}
```
## Mock Live Testing
Use `filters.mock` on the regular `sports_fifa_world_cup` channel when you want the same websocket method and message shape as production live data, but there are no live FIFA World Cup games available.
WSS mock mode is a single deterministic test stream. It is meant for websocket parser testing, score/status update handling, `last_play`, `significant_events`, and `game_event` handling. For multi-game display testing, use the REST endpoint with `mock=live`:
```bash theme={null}
curl --request GET \
--url "https://api.predexon.com/v2/sports/fifa-world-cup/live-games?mock=live&limit=20" \
--header "x-api-key: YOUR_DATA_KEY"
```
Mock streams still return `channel: "sports_fifa_world_cup"` and emit the normal message sequence:
| Message | Description |
| --------------------- | --------------------------------------------------------------------------------------- |
| `live_games_snapshot` | Initial mock snapshot. |
| `game_state` | Full mock game state updates as score, clock, period, and status change. |
| `game_event` | Individual mock key incidents such as goals, cards, substitutions, and game-end events. |
Mock messages include `mode: "mock"` inside `data` so clients can clearly separate test data from live production updates.
Supported mock values:
| Value | Description |
| ------- | -------------------------------------------------------------------------------- |
| `live` | Streams an in-progress FIFA-style soccer game from first half through full time. |
| `final` | Starts from an ended-game snapshot and emits final-state data. |
The normal optional controls can be used with mock streams:
| Field | Type | Description |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `event_types` | string\[] | Filters `game_event` pushes. `game_state` snapshots are still sent. |
| `speed` | number | Mock stream speed multiplier. Defaults to `60`. Minimum `1`, maximum `3600`. |
| `start_offset_seconds` | integer | Starts the mock stream at or after this match offset. Defaults to `0`. |
| `loop` | boolean | If `true`, the mock stream restarts after the final message until the client unsubscribes or disconnects. Defaults to `false`. |
Example mock stream with only score-change event pushes:
```json theme={null}
{
"action": "subscribe",
"platform": "predexon",
"version": 1,
"type": "sports_fifa_world_cup",
"filters": {
"polymarket_event_ids": ["*"],
"mock": "live",
"event_types": ["score_change"],
"speed": 600
}
}
```
## `last_play` and `significant_events`
`significant_events[]` is the normalized key-incident list for the game. It can include goals, cards, substitutions, penalties, period changes, game-end events, and other supported incidents.
`last_play` is the latest notable play for display. When present, it maps to the most recent item in `significant_events[]`.
`last_play` can be `null` when no notable incident has happened yet, or when the live data source has not supplied a latest notable play for that game at that time. This does not mean the field is under development.
## Server Messages
### ack
```json theme={null}
{
"type": "ack",
"subscription_id": "sub_01",
"channel": "sports_fifa_world_cup"
}
```
### game\_state
`game_state` is the core message type. It is sent on subscribe and whenever the current game state changes materially: score, status, period, clock, winner, or live/ended state.
```json theme={null}
{
"type": "event",
"subscription_id": "sub_01",
"channel": "sports_fifa_world_cup",
"data": {
"event_type": "game_state",
"sequence": 1842,
"polymarket_event_id": "351718",
"polymarket_game_id": "90086910",
"polymarket_slug": "fifwc-usa-par-2026-06-12",
"league": "fifwc",
"sport": "soccer",
"title": "United States vs Paraguay",
"scheduled_start": "2026-06-13T01:00:00Z",
"home_team": {
"code": "usa",
"name": "United States"
},
"away_team": {
"code": "par",
"name": "Paraguay"
},
"status": "in_progress",
"status_text": "Second Half",
"live": true,
"ended": false,
"period": "2H",
"clock": "58'",
"score": {
"home": 1,
"away": 0,
"display": "1-0"
},
"penalty_score": null,
"winner": null,
"last_play": {
"description": "Goal for United States",
"period": "2H",
"clock": "58'"
},
"significant_events": [
{
"id": "evt_01jz8d2h7q",
"type": "score_change",
"period": "2H",
"clock": "58'",
"team": "home",
"team_code": "usa",
"description": "Goal for United States"
}
],
"updated_at": "2026-06-13T02:18:22Z"
}
}
```
For games in or completed after a penalty shootout, `score` remains the match score and `penalty_score` carries the shootout score:
```json theme={null}
{
"score": {
"home": 3,
"away": 3,
"display": "3-3"
},
"penalty_score": {
"home": 4,
"away": 2,
"display": "4-2"
},
"period": "FT PEN",
"status_text": "Full Time (Penalties)"
}
```
### game\_event
`game_event` is sent when Predexon has a normalized key incident for the game. Event availability can vary by game and data coverage.
If `filters.event_types` is supplied on the subscription, only matching `game_event` messages are pushed. `game_state` messages are still sent as full snapshots.
```json theme={null}
{
"type": "event",
"subscription_id": "sub_01",
"channel": "sports_fifa_world_cup",
"data": {
"event_type": "game_event",
"sequence": 1843,
"polymarket_event_id": "351718",
"polymarket_game_id": "90086910",
"polymarket_slug": "fifwc-usa-par-2026-06-12",
"event": {
"id": "evt_01jz8d2h7q",
"type": "score_change",
"period": "2H",
"clock": "58'",
"team": "home",
"team_code": "usa",
"player": "Player Name",
"description": "Goal for United States",
"score": {
"home": 1,
"away": 0,
"display": "1-0"
}
},
"updated_at": "2026-06-13T02:18:22Z"
}
}
```
### error
```json theme={null}
{
"type": "error",
"code": "INVALID_FILTERS",
"message": "FIFA World Cup subscriptions require exactly one of polymarket_event_ids or polymarket_game_ids"
}
```
## Message Types
| `event_type` | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `live_games_snapshot` | Initial snapshot of all covered live FIFA World Cup games when subscribing with `polymarket_event_ids: ["*"]`. |
| `game_state` | Full current game snapshot. Sent on subscribe and when score, status, period, clock, winner, or live/ended state changes. |
| `game_event` | Normalized key game incident when available. |
## Sequence
`sequence` is a numeric ordering value. For live `game_state` and `game_event` pushes, it is generated as a monotonic timestamp-like value and does not reset during normal service lifecycle.
`live_games_snapshot.sequence` is the sequence for the snapshot message itself. If individual `games[]` objects include a `sequence`, that value is the cached game's last state sequence. Clients should use `sequence` for ordering or deduplication, not as a replay cursor. After reconnecting, treat the latest `game_state` or current snapshot as authoritative.
## Period and Clock
For FIFA World Cup game state, `period` is a normalized soccer match phase.
| Value | Meaning |
| -------- | -------------------------------------------------- |
| `null` | Scheduled/not started, or no period available yet. |
| `1H` | First half. |
| `HT` | Half time. |
| `2H` | Second half. |
| `WET` | Waiting for extra time. |
| `ET1` | Extra time first half. |
| `HT ET` | Extra time half time. |
| `ET2` | Extra time second half. |
| `FT` | Full time. |
| `FT ET` | Full time after extra time. |
| `WPE` | Waiting for penalty shootout. |
| `PEN` | Penalty shootout. |
| `FT PEN` | Full time after penalty shootout. |
| `INT` | Interrupted. |
| `SUSP` | Suspended. |
| `ABD` | Abandoned. |
| `CANC` | Canceled or coverage canceled. |
| `POSTP` | Postponed. |
`clock` is a display clock for elapsed match time. It counts upward, not downward. It is minute-level, not second-level, and is formatted as values such as `18'`, `45+3'`, `67'`, or `120+1'`.
`clock` can be `null` during scheduled, half-time, full-time, waiting, penalty-shootout, canceled, postponed, abandoned, suspended, or interrupted states.
The websocket sends updates when the game state changes materially, for example score, status, period, clock, winner, or live/ended state changes. Push cadence is event-driven and seconds-level; it is not a minute-based polling feed.
The feed currently exposes the overall scheduled kickoff as `scheduled_start`. It does not expose separate first-half, second-half, extra-time, or penalty-shootout start timestamps. Clients should use `period`, `status_text`, `clock`, `updated_at`, and `significant_events[]` for phase display.
## Game Event Vocabulary
`game_event.event.type` is a normalized vocabulary. Predexon emits these events only when the underlying game data is available and normalized.
| Type | Meaning |
| ----------------------- | ------------------------------------------------------------------------ |
| `score_change` | A scoring event, such as a goal. |
| `penalty_shootout_goal` | Successful penalty in a penalty shootout. |
| `penalty_shootout_miss` | Missed penalty in a penalty shootout. |
| `missed_penalty` | Missed penalty during regular or extra-time play. |
| `yellow_card` | Yellow card. |
| `red_card` | Red card. |
| `substitution` | Player substitution. |
| `period_start` | Start of a half, extra-time period, penalty shootout, or similar period. |
| `period_end` | End of a half, extra-time period, penalty shootout, or similar period. |
| `game_start` | Game started. |
| `game_end` | Game ended or final status reached. |
| `delay` | Game delayed or suspended. |
| `cancellation` | Game canceled or postponed. |
| `other` | Key event that does not map cleanly to another normalized type. |
## Identifiers
| Field | Meaning |
| --------------------- | --------------------------------------- |
| `polymarket_event_id` | Polymarket Gamma event ID for the game. |
| `polymarket_game_id` | Polymarket sports game ID for the game. |
| `polymarket_slug` | Polymarket event slug. |
Polymarket identifiers are returned as top-level fields so clients can reconcile the live game state with Polymarket event pages and venue-native market metadata.
## Coverage
The channel is intended to provide live score, penalty shootout score, status, period, clock, winner, and game lifecycle updates for covered FIFA World Cup games.
Key incidents are included when available and normalized by Predexon. Incident coverage may include goals, cards, substitutions, penalties, penalty shootout attempts, period changes, and game-end events, but availability can vary by game and live-data coverage.
## Replay Testing
Use the replay channel to test websocket integration before a live FIFA World Cup game is active. The replay channel emits the same game-state payload shape as the production `sports_fifa_world_cup` channel, including `live_games_snapshot`, `game_state`, and `game_event` messages. Replay messages use the replay channel name and include `mode: "replay"` inside `data`.
Replay streams are accelerated for testing. Message order is preserved, but clients do not need to wait for real match time.
Available replay IDs:
| Replay ID | Match | Replay event ID | Replay game ID | Scenario |
| ------------------------------------ | --------------------------------------------- | --------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `historical-intl-mar-nor-2026-06-07` | Morocco vs. Norway | `replay-mar-nor-2026-06-07` | `replay-mar-nor-2026-06-07` | `1-1` historical international friendly with goals, cards, substitutions, half-time, second-half, and final-state updates. |
| `historical-mls-clt-mia-2025-09-13` | Charlotte FC vs. Inter Miami CF | `43880` | `87867` | `3-0` match with goals, cards, and substitutions. |
| `historical-mls-dcu-orl-2025-09-13` | D.C. United SC vs. Orlando City SC | `43885` | `87862` | `1-1` match with goals, cards, a red card, and substitutions. |
| `historical-mls-atl-clb-2025-09-13` | Atlanta United FC vs. Columbus Crew | `43884` | `87865` | `4-5` high-scoring match with frequent score changes. |
| `historical-mls-vwh-phi-2025-09-13` | Vancouver Whitecaps FC vs. Philadelphia Union | `43892` | `87873` | `7-0` match with repeated score changes. |
Replay streams are for integration testing. Production FIFA live messages use real Polymarket identifiers. Historical replay streams may use replay-only identifiers so clients can test the websocket message shape without relying on a currently live FIFA game.
```json theme={null}
{
"action": "subscribe",
"platform": "predexon",
"version": 1,
"type": "sports_fifa_world_cup_replay",
"filters": {
"replay_ids": ["historical-intl-mar-nor-2026-06-07"],
"speed": 600,
"start_offset_seconds": 0,
"loop": false
}
}
```
Replay controls:
| Field | Type | Description |
| ---------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `replay_ids` | string\[] | Replay IDs to subscribe to. Use one replay ID per subscription. |
| `speed` | number | Replay speed multiplier. `60` means one match minute is delivered in about one real second. `600` is useful for quick integration tests. Defaults to `60`. Minimum `1`, maximum `3600`. |
| `start_offset_seconds` | integer | Starts the replay at or after this match offset. For example, `2700` starts at roughly the 45-minute mark. Defaults to `0`. |
| `loop` | boolean | If `true`, the replay restarts after the final message until the client unsubscribes or disconnects. Defaults to `false`. |
After subscribing, the server sends an `ack`, then emits replay messages for the requested replay ID. Clients can use the replay stream to validate parsing, score updates, penalty shootout scores, status changes, `last_play`, `significant_events`, and individual `game_event` handling.
Replay messages use `channel: "sports_fifa_world_cup_replay"` and include `mode: "replay"` inside `data` so they cannot be confused with live production updates.
The replay includes:
| Message | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `live_games_snapshot` | Initial replay snapshot for the match. |
| `game_state` | Full current replay state, including score, optional `penalty_score`, period, clock, status, `last_play`, and `significant_events`. |
| `game_event` | Individual normalized incidents such as goals, cards, substitutions, and penalty shootout attempts. |
For example, the Morocco vs. Norway replay progresses from `0-0` to `1-0`, `1-1`, and finally `1-1`, with game-start, goals, yellow-card, substitution, half-time, second-half, and game-end events included.
```json theme={null}
{
"type": "event",
"subscription_id": "sub_01",
"channel": "sports_fifa_world_cup_replay",
"data": {
"event_type": "game_state",
"mode": "replay",
"sequence": 8,
"polymarket_event_id": "replay-mar-nor-2026-06-07",
"polymarket_game_id": "replay-mar-nor-2026-06-07",
"polymarket_slug": "replay-mar-nor-2026-06-07",
"league": "international_friendlies",
"sport": "soccer",
"title": "Morocco vs Norway",
"scheduled_start": "2026-06-07T19:00:00Z",
"home_team": {
"code": "mar",
"name": "Morocco"
},
"away_team": {
"code": "nor",
"name": "Norway"
},
"status": "in_progress",
"status_text": "Replay in progress",
"live": true,
"ended": false,
"period": "1H",
"clock": "8'",
"score": {
"home": 1,
"away": 0,
"display": "1-0"
},
"winner": null,
"last_play": {
"description": "Goal for MAR: Brahim Diaz",
"period": "1H",
"clock": "8'"
},
"significant_events": [
{
"id": "evt_replay_01",
"type": "score_change",
"period": "1H",
"clock": "8'",
"team": "home",
"team_code": "mar",
"player": "Brahim Diaz",
"description": "Goal for MAR: Brahim Diaz",
"score": {
"home": 1,
"away": 0,
"display": "1-0"
}
}
],
"updated_at": "2026-06-07T19:08:00Z"
}
}
```
## Heartbeats and Reconnects
The gateway uses websocket ping/pong frames for connection liveness. Clients should respond to ping frames according to their websocket library's normal behavior.
If the connection drops, reconnect and resubscribe. Clients should treat `game_state` as the latest full snapshot for a game.