FIFA World Cup WebSocket

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

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

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 FIFA World Cup games covered by Predexon:

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

Subscribe by Polymarket Gamma event ID:

{
  "action": "subscribe",
  "platform": "predexon",
  "version": 1,
  "type": "sports_fifa_world_cup",
  "filters": {
    "polymarket_event_ids": ["351718"]
  }
}

Subscribe by Polymarket sports game ID:

{
  "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:

{
  "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:

{
  "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.

{
  "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:

{
  "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:

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:

{
  "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

{
  "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.

{
  "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:

{
  "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.

{
  "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

{
  "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.

{
  "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.

{
  "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.

Overview

Concepts

Sports Discovery API

Order Router

Overview

Endpoint

All Live Games Snapshot

Mock Live Testing

`last_play` and `significant_events`

Server Messages

ack

game_state

game_event

error

Message Types

Sequence

Period and Clock

Game Event Vocabulary

Identifiers

Coverage

Replay Testing

Heartbeats and Reconnects

​Overview

​Endpoint

​Subscribe

​All Live Games Snapshot

​Mock Live Testing

​last_play and significant_events

​Server Messages

​ack

​game_state

​game_event

​error

​Message Types

​Sequence

​Period and Clock

​Game Event Vocabulary

​Identifiers

​Coverage

​Replay Testing

​Heartbeats and Reconnects

Overview

Endpoint

Subscribe

All Live Games Snapshot

Mock Live Testing

`last_play` and `significant_events`

Server Messages

ack

game_state

game_event

error

Message Types

Sequence

Period and Clock

Game Event Vocabulary

Identifiers

Coverage

Replay Testing

Heartbeats and Reconnects