Websocket接口

概述

什么是 WebSocket API?

WebSocket API 是一种基于 WebSocket 协议的实时数据推送服务。与 REST API 的请求-响应模式不同,WebSocket 建立持久连接,服务器可以主动向客户端推送数据。

主要优势

特性WebSocketREST API
延迟< 50ms200ms+
推送方式服务器主动推送客户端轮询
连接持久连接每次请求新建
效率高效低效
成本

适用场景

  • 实时行情展示
  • 订单状态监控
  • 账户资产变化通知
  • 高频交易数据获取
  • 实时风险监控

连接

连接地址

公共频道(无需认证):

wss://{{STREAM_API_HOST}}/v2/ws/public

私有频道(需要认证):

wss://{{STREAM_API_HOST}}/v2/ws/private

连接参数

参数说明
心跳间隔30 秒(建议)
连接超时60 秒无数据自动断开
连接限制100 个/IP
消息大小IP最大 1MB

心跳

心跳机制

客户端需要每 30 秒发送一次心跳,保持连接活跃。

如果连接成功后未发送心跳,30s未订阅或订阅后30s内服务器未向用户推送数据,系统会自动断开连接

心跳请求

{
  "op": "ping"
}

心跳响应

{
  "event": "pong"
}

登录(私有频道认证)

认证流程

  1. 建立 WebSocket 连接到私有频道
  2. 立即发送登录请求
  3. 等待登录响应
  4. 登录成功后可订阅私有频道

登录请求

{
  "op": "login",
  "args": [
    {
      "apiKey": "YOUR_API_KEY",
      "passphrase": "YOUR_PASSPHRASE",
      "timestamp": "1766124407915",
      "sign": "BASE64_ENCODED_SIGNATURE"
    }
  ]
}

参数说明:

参数类型说明
apiKeyStringAPI Key
passphraseStringAPI 口令
timestampString当前时间戳(毫秒)
signString签名(Base64 编码)

签名生成

签名字符串Message

timestamp + "GET" + "/users/self/verify" + ""

生成最终签名的步骤

第1步,将待签名字符串使用私钥secretkey进行hmac sha256加密

Signature = hmac_sha256(secretkey, Message)

第2步,对于Signature进行base64编码

Signature = base64.encode(Signature)

登录响应

成功

{
  "event": "login",
  "code": "0",
}

代码示例

JavaScript:

const crypto = require('crypto');

function generateSign(timestamp, secretKey) {
  const message = timestamp + 'GET' + '/users/self/verify' + '';
  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(message)
    .digest('base64');
  return signature;
}

Python:

import hmac
import base64

def generate_sign(timestamp, secret_key):
    message = timestamp + 'GET' + '/users/self/verify' + ''
    signature = hmac.new(
        bytes(secret_key, encoding='utf8'),
        bytes(message, encoding='utf-8'),
        digestmod='sha256'
    ).digest()
    return base64.b64encode(signature).decode()

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class SignatureGenerator {

    public static String generateSign(String timestamp, String secretKey)  {
        String message = timestamp + "GET" + "/users/self/verify" + "";

        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(
            secretKey.getBytes("UTF-8"),
            "HmacSHA256"
        );
        mac.init(secretKeySpec);

        byte[] digest = mac.doFinal(message.getBytes("UTF-8"));
        return Base64.getEncoder().encodeToString(digest);
    }

    // 使用示例
    public static void main(String[] args) {
        String timestamp = System.currentTimeMillis();
        String secretKey = "YOUR_SECRET_KEY";
        String sign = generateSign(timestamp, secretKey);
        System.out.println("签名: " + sign);
    }
}

错误处理

常见错误码

错误码说明
30001频道不存在
30002不合法的请求
30003无效 op
30004用户需要登录
30005登录失败
30011无效的 ACCESS_KEY
30012无效的 ACCESS_PASSPHRASE
30013无效的 ACCESS_TIMESTAMP
30014请求时间戳过期
30015无效的签名
30016参数错误

最佳实践

  1. 连接管理:使用指数退避策略进行重连
  2. 心跳机制:定期发送心跳保持连接
  3. 订阅管理:避免重复订阅,及时取消不需要的订阅
  4. 数据处理:使用消息队列异步处理数据
  5. 安全建议:使用 WSS 加密连接,妥善保管 API Key