> ## 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 - 通过 /v1/ws 获取实时行情与订单更新

> 连接 Apexium API WebSocket，用 API 密钥登录，选择频道和赛事，并保持连接稳定：消息封装、限制、心跳、重连与语言。

一个 WebSocket 同时传送行情数据和您账户的状态：您的余额，博彩公司和汇率，赛事、比分和比赛时钟，赔率，您所关注选项的投注单，以及您的订单。

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

## 登录

连接后 10 秒内，将 `login` 帧作为第一条消息发送：

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

| 字段 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `apiKey` | string | 必填 | 与 REST 相同的密钥 |
| `receiveType` | string | `json` | `json`、`binary` 或 `zstd`。生产环境只接受 `zstd`。参见[编码](https://docs.apexiumbet.com/zh/websocket/encodings.md) |
| `channels` | string\[] | 所有频道 | `balance`、`bookmakers`、`currencies`、`fixtures`、`scores`、`clocks`、`odds`、`betslip`、`orders` 中的任意几个。参见[频道](#频道) |
| `fixtureIds` | string\[] | 无 | 在 `odds`、`bookmakers`、`fixtures`、`scores` 和 `clocks` 上关注的赛事 |
| `tournamentIds` | integer\[] | 无 | 在 `fixtures`、`scores` 和 `clocks` 上关注的联赛；不适用于 `odds`，参见[行情频道](https://docs.apexiumbet.com/zh/websocket/feed-channels.md#您会收到什么) |
| `sportIds` | integer\[] | 无 | 在 `fixtures`、`scores` 和 `clocks` 上关注的运动；不适用于 `odds` |
| `lang` | string | `en` | `fixtures` 频道的语言。参见[语言](#语言) |
| `sinceEventId` | integer | 无 | 恢复 `orders` 频道。参见[订单](https://docs.apexiumbet.com/zh/websocket/orders.md#恢复) |

服务器以 `login_ok` 回复其实际应用的内容：

```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` 是标识此连接的 UUID。报告问题时请提供它。

登录被拒绝时，连接以 [`4001`](https://docs.apexiumbet.com/zh/websocket/close-codes) 关闭。一个连接只能登录一次：第二个 `login` 帧会收到 `error` 帧。

## 更改关注内容

无需重连即可添加或移除赛事、联赛和运动：

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

服务器以 `subscribed` 或 `unsubscribed` 回复，并附上当前生效的完整选择。频道在登录时确定，之后不能更改。

## 频道

| 频道 | 内容 | 路由依据 |
| - | - | - |
| [`balance`](https://docs.apexiumbet.com/zh/websocket/balance) | 您的余额：先是当前余额，然后是每次变化 | 您的账户 |
| [`bookmakers`](https://docs.apexiumbet.com/zh/websocket/feed-channels#频道) | 赛事上博彩公司层面的变化 | `fixtureIds` |
| [`currencies`](https://docs.apexiumbet.com/zh/websocket/feed-channels#频道) | 汇率 | 订阅该频道的每个连接 |
| [`fixtures`](https://docs.apexiumbet.com/zh/websocket/feed-channels#频道) | 赛事变化：时间、状态、参赛方 | `fixtureIds`、`tournamentIds`、`sportIds` |
| [`scores`](https://docs.apexiumbet.com/zh/websocket/feed-channels#频道) | 比分变化 | `fixtureIds`、`tournamentIds`、`sportIds` |
| [`clocks`](https://docs.apexiumbet.com/zh/websocket/feed-channels#频道) | 比赛时钟变化 | `fixtureIds`、`tournamentIds`、`sportIds` |
| [`odds`](https://docs.apexiumbet.com/zh/websocket/feed-channels#频道) | 您的博彩公司的赔率变化 | `fixtureIds` |
| [`betslip`](https://docs.apexiumbet.com/zh/websocket/betslip) | 您订阅的选项经您账户规则处理后的价格和投注额限额 | 您的订阅 |
| [`orders`](https://docs.apexiumbet.com/zh/websocket/orders) | 您的订单：先是快照，然后是每次变化 | 您的账户 |

`bookmakers`、`currencies`、`fixtures`、`scores`、`clocks` 和 `odds` 是[行情频道](https://docs.apexiumbet.com/zh/websocket/feed-channels.md)：它们只传送变化，当前状态需从 `/v1/{lang}` 加载。`balance`、`betslip` 和 `orders` 是执行频道：它们传送您账户的状态。

## 消息封装

每条频道消息的封装都相同：

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

* **`channel`** 和 **`type`** 告诉您如何读取 `payload`。
* **`ts`** 是以毫秒为单位的 Unix 时间。在行情频道上，它是 Apexium 收到消息的时间；在执行频道上，是发送消息的时间。
* **`seq`** 只出现在执行频道上。它为本连接的执行消息计数，每个新连接都从 1 重新开始。它不是恢复游标：请用 `eventId` 恢复 `orders`。

控制帧只有 `type`，没有 `channel`：`login_ok`、`subscribed`、`unsubscribed`、`betslip_subscribed`、`betslip_unsubscribed`、`snapshot_required`、`reconnect` 和 `error`。无论 `receiveType` 是什么，它们始终是 JSON 文本帧。

`error` 帧表示服务器无法应用某个帧，连接保持打开：

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

每个 `error` 帧都带有该连接的 `connectionId`，包括在 `login_ok` 之前或紧接在关闭之前发送的 `error` 帧。

## 限制

| 限制 | 值 | 超出后 |
| - | - | - |
| 每个 API 密钥的连接数 | 8 | 登录时 `4004` |
| 每个账户的赛事数，所有连接合计 | 500（仅计 `fixtureIds`） | 登录或 `subscribe` 时 `4004` |
| 每个账户的投注单选项数，所有连接合计 | 50 | `subscribeBetslip` 时 `4004` |
| 客户端帧大小 | 64 kB | 连接以 `1009` 关闭 |
| 发送 `login` 的时限 | 10 秒 | `4001` |

读取过慢的连接会以 `4002` 关闭。参见[关闭代码](https://docs.apexiumbet.com/zh/websocket/close-codes.md)。

## 心跳

服务器每 30 秒发送一次 WebSocket ping。客户端库会自动回复 pong。连续两次 ping 未得到回复的连接会被断开。您无需自己发送 ping。

## 重连

任何关闭之后都要重连，并使用指数退避加随机抖动：例如先等 1 秒，之后加倍，最多 30 秒，每次延迟乘以 0.5 到 1.5 之间的随机系数。抖动可以避免您的所有连接在同一时刻同时重连。

重连之后：

* **行情频道。** 从 `/v1/{lang}` 重新加载您所关注赛事的状态，然后应用消息。
* **`orders`。** 带上 `sinceEventId` 登录，以接收您错过的内容。参见[订单](https://docs.apexiumbet.com/zh/websocket/orders.md#恢复)。
* **`balance`。** 当前余额会紧接在 `login_ok` 之后到达。
* **`betslip`。** 重新发送您的 `subscribeBetslip` 帧。

计划重启之前，服务器会发送 `{ "type": "reconnect", "reason": "server_restart" }` 并以 `1012` 关闭：请立即重连。

## 语言

登录时的 `lang` 作用于 `fixtures` 频道：运动、联赛、状态、参赛方和场馆的名称在有翻译时使用该语言。它的取值与[行情数据路径](https://docs.apexiumbet.com/zh/api-reference/overview.md#语言)相同。其他频道只传送标识符和数字，标识符永远不依赖于语言。

## 博彩公司

`odds` 和 `bookmakers` 频道只传送 `GET /v1/me` 列出的博彩公司：您账户的博彩公司，对 API 关闭的除外。不含您任何博彩公司的消息不会发送。该列表变化后，已打开的连接会在几秒内跟上。


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