跳到主要内容

Websocket 接口

概述​

WebSocket 是 HTML5 一种新的协议（Protocol）。它实现了客户端与服务器全双工通信，使得数据可以快速地双向传播。通过一次简单的握手手就可以建立客户端和服务器连接，服务器根据业务规则可以主动推送信息给客户端。其优点如下：

  • 客户端和服务器进行数据传输时，请求头信息比较小，大概 2 个字节。
  • 客户端和服务器皆可以主动地发送数据给对方。
  • 不需要多次创建 TCP 请求和销毁，节约宽带和服务器的资源。
  • 强烈建议开发者使用 WebSocket API 获取市场行情和买卖深度等信息。
域名WebSocket API建议使用
现货频道wss://open-ws.j2coin.com/ws主域名，现货共频道
合约频道wss://open-fws.j2coin.com/ws主域名，合约频道

连接​

连接说明：

连接限制：300 次连接请求/IP/5 分钟，单个 IP 最多可以创建 100 个连接

订阅限制：240 次/小时/连接，单个连接最多可以订阅 1000 个频道

为了保持连接有效且稳定，建议您进行以下操作：

  1. 用户设置一个定时器，每 20 秒发送字符串 "ping"，并期待一个字符串 "pong" 作为回应。如果未收到字符串 "pong" 响应，请重新连接
  2. 如果 30 秒内服务器端没收到 "ping"，会自动断开连接
  3. Websocket 服务器每秒每连接最多接受 10 个消息。消息包括：
  • 字符串 "ping"
  • JSON 格式的消息，比如订阅、断开订阅
  1. 如果用户发送的消息超过限制，连接会被断开连接。反复被断开连接的 IP 有可能被服务器屏蔽
  2. 为了保持连接的稳定性，强烈建议单个连接不要订阅超过 50 个频道。订阅频道数越少的连接，稳定性会更高。

登录​

私有频道（订单、余额、持仓等）需要登录认证后才能订阅。登录使用与 REST API 一致的 HmacSHA256 签名机制，详见 签名说明。

请求格式：

{
  "op": "auth",
  "args": [
    {
      "validate-algorithms": "HmacSHA256",
      "validate-appkey": "ak_95e7762883a06dfc93ea479c08018afd",
      "validate-recvwindow": "5000",
      "validate-timestamp": "1641446237201",
      "validate-signature": "a0695576d86546a00c8e95422c868e82a78f7f76aa995cfda9cc454b77204295"
    }
  ]
}

参数说明：

字段说明
validate-algorithms签名算法，固定为 HmacSHA256
validate-appkey用户的 appkey
validate-recvwindow请求有效时间（毫秒），建议 5000
validate-timestamp当前时间戳（毫秒）
validate-signature签名值（生成方式见下方）

签名生成方式（与 REST API 完全一致）：

  1. 拼接请求头部分（按 key 字典序，& 连接），记作 X：

    validate-algorithms=HmacSHA256&validate-appkey=<appkey>&validate-recvwindow=<recvwindow>&validate-timestamp=<timestamp>

  2. 拼接数据部分，method 固定为 GET，path 固定为 /ws/auth，无 query、无 body，记作 Y：

    #GET#/ws/auth

  3. 最终待签名字符串 original = X + Y，使用 secretKey 进行 HmacSHA256 加密（hex 输出）：

    signature = hmacSha256Hex(secretKey, original)

成功响应：

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

失败响应：

{ "op": "auth", "success": false, "msg": "invalid signature" }
错误码说明
invalid signature签名错误
invalid appkeyappkey 无效
timestamp expired时间戳超出 recvwindow 范围
ip not allowedIP 未在白名单

认证成功后会自动订阅 order、balance（合约还会自动订阅 position）。

订阅​

请求格式：

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

成功响应：

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

失败响应：

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

推送消息格式：

{
  "ch": "ticker@BTC_USDT",
  "d": { ... }
}
字段说明
ch频道名称
d数据内容

取消订阅​

请求格式：

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

成功响应：

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