WebSocket 总览

现货 WebSocket 实时推送行情、订单簿、K 线、成交记录，以及私有频道的订单、余额更新。

连接地址

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

客户端请求格式

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

订阅

{
  "op": "subscribe",
  "args": ["ticker@BTC_USDT", "depth@BTC_USDT,20"]
}

取消订阅

{
  "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,1m	公开
成交	trade@{symbol}	trade@BTC_USDT	公开
标记价格（3s）	{symbol}@markPrice	BTC_USDT@markPrice	公开
标记价格（1s）	{symbol}@markPrice@1s	BTC_USDT@markPrice@1s	公开
订单	order	order	私有
余额	balance	balance	私有

错误信息

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

快速开始示例

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

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

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);
  }
};

// 心跳，建议每 30 秒
setInterval(() => ws.send(JSON.stringify({ op: 'ping' })), 30000);