> For the complete documentation index, see [llms.txt](https://info.soccerfootball.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://info.soccerfootball.info/websocket/channels.md).

# Channels

This document provides an overview of all available WebSocket channels and their purposes.

### Available Channels

| Channel         | Description                       | Update Frequency                           | Plans            |
| --------------- | --------------------------------- | ------------------------------------------ | ---------------- |
| MAIN            | Key match events                  | Event-driven                               | PRO, ULTRA, MEGA |
| MAIN\_REALTIME  | Key match events (lowest latency) | Event-driven (ultra-low latency)           | MEGA             |
| STATS           | Full statistics snapshots         | Immediate (match/league) · 30s batch (all) | ULTRA, MEGA      |
| ODDS            | Full odds snapshots               | Immediate (match/league) · 30s batch (all) | ULTRA, MEGA      |
| STATS\_REALTIME | Statistics deltas                 | Real-time                                  | MEGA             |
| ODDS\_REALTIME  | Odds deltas                       | Real-time                                  | MEGA             |

### Channel Details

#### MAIN Channel

The MAIN channel delivers key match events as they happen:

* Match start
* Goals
* Halftime
* Second half start
* Match end

**Best for:** Applications that need to track match progress and key events without full statistics.

**Update frequency:** Event-driven (only when events occur)

#### MAIN\_REALTIME Channel

The MAIN\_REALTIME channel delivers the same key match events as MAIN but with the lowest possible latency:

* Match start
* Goals
* Halftime
* Second half start
* Match end

**Best for:** Applications that require the absolute fastest match event delivery, such as live betting platforms and real-time trading systems.

**Update frequency:** Event-driven with ultra-low latency (MEGA plan only)

#### STATS Channel

The STATS channel delivers complete statistics snapshots:

* All match statistics in a single message
* **match/league scope:** immediate delivery when data changes
* **all scope:** batched delivery every 30 seconds (`batch_update`)

**Best for:** Applications that need complete statistics data and don't require real-time updates.

**Update frequency:** Immediate for `match`/`league` scope · Every 30 seconds (batch) for `all` scope

#### ODDS Channel

The ODDS channel delivers complete odds snapshots:

* All odds markets in a single message
* **match/league scope:** immediate delivery when data changes
* **all scope:** batched delivery every 30 seconds (`batch_update`)

**Best for:** Applications that need complete odds data and don't require real-time updates.

**Update frequency:** Immediate for `match`/`league` scope · Every 30 seconds (batch) for `all` scope

#### STATS\_REALTIME Channel

The STATS\_REALTIME channel delivers only the statistics that changed:

* Delta updates (only changed values)
* Immediate delivery when changes occur
* Lower bandwidth than full snapshots

**Best for:** Applications that need instant statistics updates and can maintain local state.

**Update frequency:** Real-time (as changes occur)

#### ODDS\_REALTIME Channel

The ODDS\_REALTIME channel delivers only the odds that changed:

* Delta updates (only changed values)
* Immediate delivery when changes occur
* Lower bandwidth than full snapshots

**Best for:** Applications that need instant odds updates and can maintain local state.

**Update frequency:** Real-time (as changes occur)

### Channel Availability by Plan

| Plan  | MAIN | MAIN\_REALTIME | STATS | ODDS | STATS\_REALTIME | ODDS\_REALTIME |
| ----- | ---- | -------------- | ----- | ---- | --------------- | -------------- |
| BASIC | -    | -              | -     | -    | -               | -              |
| PRO   | Yes  | -              | -     | -    | -               | -              |
| ULTRA | Yes  | -              | Yes   | Yes  | -               | -              |
| MEGA  | Yes  | Yes            | Yes   | Yes  | Yes             | Yes            |

### Subscription Scopes

All channels support the following subscription scopes:

<table><thead><tr><th width="102.7999267578125">Scope</th><th width="111.4000244140625">Format</th><th width="120.5999755859375">id required</th><th>Description</th></tr></thead><tbody><tr><td>All</td><td><code>all</code></td><td>No</td><td>Receive events for all matches</td></tr><tr><td>Match</td><td><code>match</code></td><td>Yes</td><td>Receive events for a specific match (pass <code>id</code> separately)</td></tr><tr><td>League</td><td><code>league</code></td><td>Yes</td><td>Receive events for all matches in a league (pass <code>id</code> separately)</td></tr></tbody></table>

### Choosing the Right Channel

#### For basic match tracking

Use **MAIN** channel only. You'll receive goals, halftime, and match end events.

#### For detailed statistics

Use **STATS** channel for periodic full snapshots, or **STATS\_REALTIME** (MEGA only) for immediate updates.

#### For odds monitoring

Use **ODDS** channel for periodic full snapshots, or **ODDS\_REALTIME** (MEGA only) for immediate updates.

#### For real-time applications

Combine **MAIN** for events with **STATS\_REALTIME** and **ODDS\_REALTIME** for the most responsive experience. For the absolute fastest event delivery, use **MAIN\_REALTIME** instead of MAIN (MEGA plan only).

### Message Format

#### Event message (match/league scope)

Sent immediately to `match` and `league` scope subscribers:

```json
{
  "type": "event",
  "channel": "CHANNEL_NAME",
  "scope": "match",
  "id": "12345",
  "eventType": "stats_update",
  "eventId": "abc123",
  "ts": 1705312800000,
  "data": { ... }
}
```

| Field       | Type    | Description                                                    |
| ----------- | ------- | -------------------------------------------------------------- |
| `type`      | string  | Always `"event"`                                               |
| `channel`   | string  | Source channel name                                            |
| `scope`     | string  | Publish scope (`"match"`)                                      |
| `id`        | string  | Match public ID                                                |
| `eventType` | string  | Event type (e.g., `"stats_update"`, `"odds_update"`, `"goal"`) |
| `eventId`   | string  | Unique event ID for deduplication                              |
| `ts`        | integer | Event timestamp in milliseconds                                |
| `data`      | object  | Event-specific data                                            |

#### Batch message (all scope)

Sent every 30 seconds to `all` scope subscribers of STATS and ODDS channels:

```json
{
  "type": "batch_update",
  "channel": "CHANNEL_NAME",
  "scope": "all",
  "timestamp": 1705312800000,
  "matches": [
    { "matchId": "12345", "leagueId": "67890", "data": { ... } }
  ]
}
```

| Field                | Type    | Description                                          |
| -------------------- | ------- | ---------------------------------------------------- |
| `type`               | string  | Always `"batch_update"`                              |
| `channel`            | string  | Source channel name (`"STATS"` or `"ODDS"`)          |
| `scope`              | string  | Always `"all"`                                       |
| `timestamp`          | integer | Batch creation timestamp in milliseconds             |
| `matches`            | array   | Array of match updates accumulated since last batch  |
| `matches[].matchId`  | string  | Match public ID                                      |
| `matches[].leagueId` | string  | League/Championship public ID                        |
| `matches[].data`     | object  | Event-specific data (same structure as `event` data) |

### Best Practices

1. **Start with MAIN**: Always subscribe to MAIN for basic match events
2. **Add channels as needed**: Subscribe to STATS or ODDS only if you need that data
3. **Use REALTIME wisely**: REALTIME channels are powerful but require local state management
4. **Unsubscribe when done**: Free up subscription slots when matches end