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

# WebSocket - Live market data and order updates on /v1/ws

> Connect to the Apexium API WebSocket, log in with your API key, choose channels and fixtures, and keep the connection healthy: envelope, limits, heartbeat, reconnection and languages.

One WebSocket carries both the market data and the state of your account: your balance, the bookmakers and currencies, the fixtures, scores and clocks, the odds, the betslip of the selections you follow, and your orders.

```
wss://api.apexiumbet.com/v1/ws
```

## Log in

Send a `login` frame as the first message, within 10 seconds of the connection:

```json theme={null}
{
  "type": "login",
  "apiKey": "apx_live_…",
  "receiveType": "zstd",
  "channels": ["odds", "fixtures", "scores", "orders", "balance"],
  "fixtureIds": ["id1000001770366972"],
  "sportIds": [10],
  "lang": "en"
}
```

| Field | Type | Default | Description |
| - | - | - | - |
| `apiKey` | string | required | The same key as on REST |
| `receiveType` | string | `json` | `json`, `binary` or `zstd`. Production accepts `zstd` only. See [Encodings](https://docs.apexiumbet.com/websocket/encodings.md) |
| `channels` | string\[] | every channel | Any of `balance`, `bookmakers`, `currencies`, `fixtures`, `scores`, `clocks`, `odds`, `betslip`, `orders`. See [Channels](#channels) |
| `fixtureIds` | string\[] | none | Fixtures to follow on `odds`, `bookmakers`, `fixtures`, `scores` and `clocks` |
| `tournamentIds` | integer\[] | none | Tournaments to follow on `fixtures`, `scores` and `clocks`; not on `odds`, see [Feed channels](https://docs.apexiumbet.com/websocket/feed-channels.md#what-you-receive) |
| `sportIds` | integer\[] | none | Sports to follow on `fixtures`, `scores` and `clocks`; not on `odds` |
| `lang` | string | `en` | Language of the `fixtures` channel. See [Languages](#languages) |
| `sinceEventId` | integer | none | Resume the `orders` channel. See [Orders](https://docs.apexiumbet.com/websocket/orders.md#resume) |

The server answers `login_ok` with what it applied:

```json theme={null}
{
  "type": "login_ok",
  "connectionId": "3d9a7f52-…",
  "sub": "8b0c6e0e-…",
  "lang": "en",
  "receiveType": "zstd",
  "channels": ["odds", "fixtures", "scores", "orders", "balance"],
  "sportIds": [10],
  "tournamentIds": [],
  "fixtureIds": ["id1000001770366972"],
  "limits": { "connections": 8, "fixtures": 500, "betslips": 50 }
}
```

`connectionId` is a UUID that identifies this connection. Quote it when you report a problem.

A refused login closes the connection with [`4001`](https://docs.apexiumbet.com/websocket/close-codes). One connection logs in once: a second `login` frame gets an `error` frame.

## Change what you follow

Add or remove fixtures, tournaments and sports without reconnecting:

```json theme={null}
{ "type": "subscribe", "fixtureIds": ["id1000001770366973"] }
{ "type": "unsubscribe", "sportIds": [10] }
```

The server answers `subscribed` or `unsubscribed` with the whole selection now in force. The channels are fixed at login.

## Channels

| Channel | Carries | Routed by |
| - | - | - |
| [`balance`](https://docs.apexiumbet.com/websocket/balance) | Your balance: the current one, then every change | your account |
| [`bookmakers`](https://docs.apexiumbet.com/websocket/feed-channels#channels) | Bookmaker-level changes on a fixture | `fixtureIds` |
| [`currencies`](https://docs.apexiumbet.com/websocket/feed-channels#channels) | Exchange rates | every connection on the channel |
| [`fixtures`](https://docs.apexiumbet.com/websocket/feed-channels#channels) | Fixture changes: schedule, status, participants | `fixtureIds`, `tournamentIds`, `sportIds` |
| [`scores`](https://docs.apexiumbet.com/websocket/feed-channels#channels) | Score changes | `fixtureIds`, `tournamentIds`, `sportIds` |
| [`clocks`](https://docs.apexiumbet.com/websocket/feed-channels#channels) | Match clock changes | `fixtureIds`, `tournamentIds`, `sportIds` |
| [`odds`](https://docs.apexiumbet.com/websocket/feed-channels#channels) | Odds changes of your bookmakers | `fixtureIds` |
| [`betslip`](https://docs.apexiumbet.com/websocket/betslip) | The price and stake limits of the selections you subscribe to, after your account's rules | your subscriptions |
| [`orders`](https://docs.apexiumbet.com/websocket/orders) | Your orders: a snapshot, then every change | your account |

`bookmakers`, `currencies`, `fixtures`, `scores`, `clocks` and `odds` are the [feed channels](https://docs.apexiumbet.com/websocket/feed-channels.md): they carry changes only, and you load the current state from `/v1/{lang}`. `balance`, `betslip` and `orders` are the execution channels: they carry the state of your account.

## Envelope

Every channel message has the same envelope:

```json theme={null}
{
  "channel": "odds",
  "type": "UPDATE",
  "payload": { "fixtureId": "id1000001770366972", "odds": { "…": "…" } },
  "ts": 1791413359090
}
```

* **`channel`** and **`type`** tell you how to read `payload`.
* **`ts`** is a Unix time in milliseconds. On feed channels, it is when Apexium received the message; on execution channels, when it sent it.
* **`seq`** is present on execution channels only. It counts the execution messages of this connection and starts again at 1 on every connection. It is not a resume cursor: resume `orders` with `eventId`.

Control frames have a `type` and no `channel`: `login_ok`, `subscribed`, `unsubscribed`, `betslip_subscribed`, `betslip_unsubscribed`, `snapshot_required`, `reconnect` and `error`. They are always JSON text frames, whatever your `receiveType`.

An `error` frame reports a frame the server could not apply, and the connection stays open:

```json theme={null}
{ "type": "error", "error": "bad_request", "message": "fixtureIds must be an array of fixture ids", "connectionId": "3d9a7f52-…" }
```

Every `error` frame carries the `connectionId` of the connection, including one sent before `login_ok` or right before a close.

## Limits

| Limit | Value | Past it |
| - | - | - |
| Connections per API key | 8 | `4004` at login |
| Fixtures per account, summed over its connections | 500 (`fixtureIds` only) | `4004` at login or on `subscribe` |
| Betslip selections per account, summed over its connections | 50 | `4004` on `subscribeBetslip` |
| Client frame size | 64 kB | the connection is closed with `1009` |
| Time to send `login` | 10 seconds | `4001` |

A connection that reads too slowly is closed with `4002`. See [Close codes](https://docs.apexiumbet.com/websocket/close-codes.md).

## Heartbeat

The server sends a WebSocket ping every 30 seconds. Client libraries answer with a pong on their own. A connection that leaves two pings in a row unanswered is dropped. You do not need to send pings yourself.

## Reconnect

Reconnect after any close, with an exponential backoff and a random jitter: for example 1 second, then doubling up to 30 seconds, each delay multiplied by a random factor between 0.5 and 1.5. The jitter keeps your connections from all coming back in the same instant.

After a reconnect:

* **Feed channels.** Load the state of your fixtures again from `/v1/{lang}`, then apply the messages.
* **`orders`.** Log in with `sinceEventId` to receive what you missed. See [Orders](https://docs.apexiumbet.com/websocket/orders.md#resume).
* **`balance`.** The current balance arrives right after `login_ok`.
* **`betslip`.** Send your `subscribeBetslip` frames again.

Before a planned restart, the server sends `{ "type": "reconnect", "reason": "server_restart" }` and closes with `1012`: reconnect at once.

## Languages

The `lang` of the login applies to the `fixtures` channel: the names of the sport, tournament, status, participants and venue follow it when a translation exists. It takes the same values as the [market data paths](https://docs.apexiumbet.com/api-reference/overview.md#languages). The other channels carry identifiers and numbers only, and identifiers never depend on the language.

## Bookmakers

The `odds` and `bookmakers` channels carry only the bookmakers that `GET /v1/me` lists: those of your account, except any closed to the API. A message left with none of your bookmakers is not sent. When that list changes, open connections follow within a few seconds.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.