跳到主要内容

WebSocket 基本信息

通用 WebSocket 信息​

WebSocket 基础地址：wss://fstream.x.group/ws/market（公共频道，无需 listenKey）

请求头​

发送建立 WebSocket 连接的 HTTP 请求时，建议添加压缩扩展协议的请求头：

建议请求头
Sec-Websocket-Extensions: permessage-deflate

订阅步骤​

  1. 建立 WebSocket 连接。
  2. 订阅公共频道的 WebSocket 事件时，发送：
订阅
{
  "method": "SUBSCRIBE",
  "params": ["{topic}@{你关注的交易对}"],
  "id": "id_field_could_call_whatever_you_want"
}

请求消息格式​

订阅/取消订阅示例

消息格式
{
  "method": "SUBSCRIBE/UNSUBSCRIBE",
  "params": [
    "{topic1}@{arg1},{arg2}",
    "{topic2}@{arg}"
  ],
  "id": "id_field_could_call_whatever_you_want"     // 回调 ID
}

响应消息格式​

响应
{
  "id":   "{id}",   // 回调 ID
  "code": 1,         // 结果 0=成功；1=失败；2=listenKey 无效
  "msg":  ""
}

推送消息格式​

格式
{
  "topic": "topic",
  "event": "{topic}@{symbol}",  // 标题
  "data": {}
}
示例
{
  "topic": "trade",
  "event": "trade@btc_usdt",
  "data": {
    "s": "btc_usdt",
    "i": 6316559590087222000,
    "t": 1655992403617,
    "p": "43000",
    "q": "0.21",
    "b": true
  }
}

心跳检测​

每个客户端连接必须定期发送文本 ping 消息。服务器将回复文本 pong。

如果服务器在 30 秒 内未收到 ping，将主动断开连接。

错误码​

错误码描述
400请求消息有误，请检查

订单簿管理​

如何正确管理本地订单簿

  1. 建立连接：wss://fstream.xt.com/ws/market，订阅 depth_update@btc_usdt。
  2. 缓存从数据流接收到的事件。
  3. 获取深度快照：https://fapi.xt.com/future/market/v1/public/depth?symbol=btc_usdt&level=500。
  4. 丢弃快照中 u <= lastUpdateId 的任何事件。
  5. 第一个处理的事件应满足 fu <= lastUpdateId + 1 且 u >= lastUpdateId + 1。
  6. 在监听数据流时，每个新事件的 fu 应等于前一个事件的 u + 1。
  7. 每个事件中的数据是价格档位的绝对数量。
  8. 如果数量为 0，删除该价格档位。
  9. 接收到删除本地订单簿中不存在的价格档位的事件可能发生且是正常的。

注意事项​

由于深度快照对价格档位数量有限制，初始快照之外且没有数量变化的价格档位不会在增量深度流中更新。因此，即使正确应用增量深度流的所有更新，这些价格档位也不会在本地订单簿中显示，可能导致与实际订单簿存在细微差异。不过，对于大多数使用场景，500 档深度限制足以理解市场并有效交易。