> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/exchange/zh-cn/apis-and-rates/apis-and-rates/exchange-websocket.md).

# 交易所 WebSocket

实时订单簿、成交和账户数据流：订阅、令牌与重连。

WebSocket API 推送实时的订单簿更新、成交、K线、引擎状态以及账户事件（订单、成交、仓位、余额、强平）。对于任何对延迟敏感的集成，这都是推荐的接入方式。

### 连接

共有两个 WebSocket 端点，其中只有一个需要令牌。

**`/stream`：公共市场数据，无需令牌。** 不带任何凭证打开套接字，然后发送一条列出频道的消息，例如 `{"subscribe": ["book:BTC-USDX-PERP"]}`。服务器只读取这第一条消息，因此要更换频道就需要重新连接。消息帧以 `type` 标记（`BookUpdate`、`Trade`、`MarketHalted`、`MarketResumed`，以及连接落后时的 `gap`）。自动减仓结算不会在 `/stream` 上发布，因为它们会暴露所涉及的账户。每个订单簿帧都是完整的前20档快照而非增量，因此重连后无需回放。服务器不发送心跳，公共主机会在连接打开约30秒后将其关闭，因此请重新连接并重新订阅。下文的限制和频道不适用于 `/stream`。

**`/ws`：账户频道和公共频道，需要令牌。** 浏览器无法在 WebSocket 升级请求中附加自定义身份验证请求头，因此该端点使用短期令牌而非请求头：

1. 调用 `POST /ws/token`，并使用您的 HMAC 密钥或已注册的代理密钥签名（即一次普通的已签名 REST 请求）。这会生成一个**60秒有效、一次性**的不透明令牌。您的 secret 永远不会经过 WebSocket 传输。
2. 打开到 `/ws?token=…` 的 WebSocket 连接，并用 `{"op": "subscribe", "channel": "…", "market": "…"}` 消息进行订阅。

令牌是一次性的，60秒后回收，并且只在生成它的网络上有效。请为每个连接生成一个新令牌。旧版的 `POST /ws-tokens` 仍可生成令牌，但当前 API 中没有任何功能需要它们：`/stream` 不需要令牌，`/ws` 使用来自 `POST /ws/token` 的令牌。

### 连接限制（`/ws`）

* 每个 IP 最多**5个活跃连接**，在每个等级上均于升级时执行。第6个连接会在升级时被以 `HTTP 429` 拒绝。不会驱逐任何已有连接，且该一次性令牌已被消耗，因此重试前请生成一个新令牌。
* 在此之上还有按账户的连接上限：Pro 等级为**5**，MarketMaker 等级为**100**。
* 订阅数量按连接*和*按账户设有相同的上限（Pro 50，MarketMaker 1,000），因此增加套接字并不能换来更多订阅。
* 客户端入站帧按连接限流（Pro 10/s，MarketMaker 50/s），允许2倍突发；持续洪泛会以代码 `1008` 关闭连接。
* **这些上限是独立的预算**。它们与 REST 请求预算和交易操作预算相互独立。请参阅[速率限制](https://docs.nexus.xyz/interfaces/rate-limits)。

### 频道（`/ws`）

标注之处按市场订阅。可用频道：

| 频道             | 范围  | 数据内容     |
| -------------- | --- | -------- |
| `book`         | 按市场 | 订单簿深度更新  |
| `trades`       | 按市场 | 已执行的成交   |
| `candles`      | 按市场 | OHLCV K线 |
| `engine`       | 全局  | 引擎吞吐量与状态 |
| `orders`       | 账户  | 订单生命周期更新 |
| `fills`        | 账户  | 您已执行的成交  |
| `positions`    | 账户  | 仓位变化     |
| `balances`     | 账户  | 余额变化     |
| `liquidations` | 账户  | 强平事件     |

账户范围的频道（`orders`、`fills`、`positions`、`balances`、`liquidations`）需要与您的令牌绑定的已验证订阅。

### 推送目标

系统以低延迟扇出为目标；已发布的延迟目标会随各发布关口逐步收紧（订单簿和成交推送的延迟从撮合事件到客户端接收计算）。当前测试网的表现适用于开发和集成测试。

> **状态**：测试网预览版。确切的订阅消息格式和各频道的 Schema 定义在 `/openapi.json` 的 OpenAPI 规范以及 [API 参考](https://docs.nexus.xyz/api-reference)的 WebSocket 页面中；消息结构请以它们为权威来源。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/exchange/zh-cn/apis-and-rates/apis-and-rates/exchange-websocket.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.