WebSocket 总览

合约 WebSocket 实时推送行情、订单簿、K 线（含 1s 周期）、成交、标记价格，以及私有频道的订单、余额、持仓更新。

连接地址

类型	地址
公共频道	ws://<host>:9021/ws
私有频道	ws://<host>:9021/ws（连接后发送 auth）

客户端请求格式

所有客户端请求采用统一的 {op, args} 结构。

订阅

{
  "op": "subscribe",
  "args": [
    "ticker@BTC_USDT",
    "depth@BTC_USDT,20",
    "kline@BTC_USDT,1s",
    "BTC_USDT@markPrice@1s"
  ]
}

取消订阅

{
  "op": "unsubscribe",
  "args": ["ticker@BTC_USDT"]
}

认证（私有频道）

登录使用与 REST API 一致的 HmacSHA256 签名机制，详细说明请参考 公共模块 · Websocket 接口。

心跳

{ "op": "ping" }

服务端响应格式

成功响应

{
  "op": "subscribe",
  "success": true,
  "args": ["ticker@BTC_USDT"]
}

错误响应

{
  "op": "subscribe",
  "success": false,
  "msg": "invalid channel format"
}

认证响应

{ "op": "auth", "success": true }

{ "op": "auth", "success": false, "msg": "token is expired" }

Pong 响应

{ "op": "pong" }

推送消息格式

所有推送消息统一为：

{
  "ch": "<channel>",
  "d": { ... }
}

字段	说明
ch	频道名称
d	数据内容

频道汇总

频道类型	格式	示例	权限	合约特有
Ticker 行情	ticker@{symbol}	ticker@BTC_USDT	公开	-
深度快照	depth@{symbol},{level}	depth@BTC_USDT,20	公开	-
深度增量	depth_update@{symbol}	depth_update@BTC_USDT	公开	-
K 线	kline@{symbol},{interval}	kline@BTC_USDT,1s	公开	✅ 支持 1s 周期
成交	trade@{symbol}	trade@BTC_USDT	公开	-
标记价格（3s）	{symbol}@markPrice	BTC_USDT@markPrice	公开	✅
标记价格（1s）	{symbol}@markPrice@1s	BTC_USDT@markPrice@1s	公开	✅
订单	order	order	私有	-
余额	balance	balance	私有	-
持仓	position	position	私有	✅

错误信息

错误信息	说明
invalid message format	消息格式错误
invalid channel format	频道格式错误
unknown operation	未知操作
authentication required	需要认证
invalid token	Token 无效
max subscriptions reached	订阅数达到上限

快速开始示例

const ws = new WebSocket('ws://host:9021/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    op: 'subscribe',
    args: [
      'ticker@BTC_USDT',
      'depth@BTC_USDT,20',
      'BTC_USDT@markPrice@1s',
      'kline@BTC_USDT,1s'
    ]
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.ch) {
    console.log('Channel:', msg.ch, 'Data:', msg.d);
  } else if (msg.op) {
    console.log('Response:', msg);
  }
};

setInterval(() => ws.send(JSON.stringify({ op: 'ping' })), 30000);