WebSocket 指南

本页面介绍连接生命周期、心跳、重连策略以及适用于所有 BTSE WebSocket 端点（现货、期货、OTC）的最佳实践。

有关特定产品的主题和订阅详情，请参阅每个产品侧边栏中的 WebSocket API 部分。

---

端点

Product	Production	Testnet
Spot WebSocket	wss://ws.btse.com/ws/spot	wss://testws.btse.io/ws/spot
Spot OSS	wss://ws.btse.com/ws/oss/spot	wss://testws.btse.io/ws/oss/spot
Futures WebSocket	wss://ws.btse.com/ws/futures	wss://testws.btse.io/ws/futures
Futures OSS	wss://ws.btse.com/ws/oss/futures	wss://testws.btse.io/ws/oss/futures
Otc WebSocket	wss://ws.btse.com/ws/otc	wss://testws.btse.io/ws/otc
Otc OSS	wss://ws.btse.com/ws/oss/otc	wss://testws.btse.io/ws/oss/otc

主连接 vs OSS： OSS（Order Stream Service）端点是专用的高吞吐量通道，仅用于订单簿数据。其他所有功能（交易记录、身份验证、通知、成交）请使用主端点。

---

连接生命周期

Connect → (optional) Authenticate → Subscribe → Receive messages
   ↑                                                    |
   └──────────── ping every 15s to keep alive ──────────┘

1. 连接 — 打开到相应端点的 WebSocket 连接
2. 身份验证（仅私有主题）— 发送带有 HMAC-SHA384 签名的 authKeyExpires
3. 订阅 — 发送 {"op": "subscribe", "args": ["topic1", "topic2"]}
4. 接收 — 消息以 JSON 格式到达，pong 除外（为纯文本）
5. 保持连接 — 定期发送 ping（纯文本）

---

心跳（Ping / Pong）

发送纯文本 ping 消息以保持连接。服务器响应 pong。

参数	值
建议间隔	每 15 秒
服务器超时	60 秒内未收到 ping 的连接将被断开
格式	纯文本 ping（非 JSON）

→ ping
← pong

如果您未收到 pong 响应，您的连接可能已失效 — 请关闭并重新连接。

---

重连策略

连接可能因网络问题、服务器维护或空闲超时而断开。您的客户端应优雅地处理断开连接：

建议方法

1. 检测断开 — 监听 WebSocket 的 close 和 error 事件
2. 等待后再重连 — 使用指数退避：
   • 第 1 次重试：1 秒
   • 第 2 次重试：2 秒
   • 第 3 次重试：4 秒
   • 最大间隔：30 秒
3. 重新身份验证 — 身份验证不会跨连接保持
4. 重新订阅 — 订阅不会跨连接保持
5. 重新同步状态 — 对于订单簿流，重新订阅后的第一条消息始终是完整的 snapshot

订单簿特定恢复

如果检测到以下任何情况，请取消订阅并重新订阅以获取新的快照：

• 序列号间隔 — seqNum != prevSeqNum + 1
• 订单簿交叉 — 最优买价 >= 最优卖价
• 数据过期 — 长时间未收到更新

---

连接限制

限制	值
每个 IP 的最大连接数	50
每个连接的最大订阅数	100 个主题
消息缓冲区	如果服务器向您客户端的出站缓冲区已满，连接将被关闭（错误代码 1007）

保持在限制内的方法：

• 尽可能在单个连接上共享多个主题
• 取消订阅不再需要的主题
• 使用 OSS 端点获取订单簿数据，以减轻主连接的负担

---

身份验证

私有主题（通知、成交、持仓）需要对 WebSocket 会话进行身份验证。身份验证是按连接进行的，在连接关闭之前不会过期。

签名： HMAC-SHA384(secret, wsPath + nonce)

其中 wsPath 是 WebSocket 路径（例如 /ws/spot、/ws/futures）。

{
  "op": "authKeyExpires",
  "args": ["<API_KEY>", "<NONCE>", "<SIGNATURE>"]
}

参见快速入门 → 第 4 步获取完整的代码示例。

---

订阅格式

所有主题使用相同的订阅/取消订阅格式：

{"op": "subscribe", "args": ["topic1", "topic2"]}
{"op": "unsubscribe", "args": ["topic1"]}

服务器确认响应：

{"event": "subscribe", "channel": ["topic1", "topic2"]}

---

可用主题

现货 (wss://ws.btse.com/ws/spot)

主题	认证	说明
tradeHistoryApi:<symbol>	公开	实时交易记录
notificationApiV3	私有	订单状态更新
fills	私有	成交通知

现货 OSS (wss://ws.btse.com/ws/oss/spot)

主题	认证	说明
snapshotL1:<symbol>	公开	最优买卖价（Level 1）
update:<symbol>_<grouping>	公开	订单簿增量更新（快照 + 增量）

期货 (wss://ws.btse.com/ws/futures)

主题	认证	说明
tradeHistoryApiV3:<symbol>	公开	实时交易记录
notificationApiV4	私有	订单状态更新
fillsV2	私有	成交通知
allPositionV4	私有	所有持仓快照
positionsV3	私有	持仓更新

期货 OSS (wss://ws.btse.com/ws/oss/futures)

主题	认证	说明
snapshotL1:<symbol>_<grouping>	公开	按分组的最优买卖价
update:<symbol>_<grouping>	公开	订单簿增量更新

OTC (wss://ws.btse.com/ws/otc)

主题	认证	说明
quote	私有	实时 OTC 报价流

---

错误代码（WebSocket）

代码	消息	处理方式
1000	Market pair not supported	检查交易对名称
1001	Operation not supported	检查 op 字段
1002	Invalid request	检查必填字段
1005	Topic does not exist	检查主题名称格式
1007	Message buffer full	减少订阅数量或加快消费速度
1008	Max failed attempts reached	会话已关闭 — 请重新连接