概述
什么是 WebSocket API?
WebSocket API 是一种基于 WebSocket 协议的实时数据推送服务。与 REST API 的请求-响应模式不同,WebSocket 建立持久连接,服务器可以主动向客户端推送数据。
主要优势
| 特性 | WebSocket | REST API |
|---|---|---|
| 延迟 | < 50ms | 200ms+ |
| 推送方式 | 服务器主动推送 | 客户端轮询 |
| 连接 | 持久连接 | 每次请求新建 |
| 效率 | 高效 | 低效 |
| 成本 | 低 | 高 |
适用场景
- 实时行情展示
- 订单状态监控
- 账户资产变化通知
- 高频交易数据获取
- 实时风险监控
连接
连接地址
公共频道(无需认证):
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"
}登录(私有频道认证)
认证流程
- 建立 WebSocket 连接到私有频道
- 立即发送登录请求
- 等待登录响应
- 登录成功后可订阅私有频道
登录请求
{
"op": "login",
"args": [
{
"apiKey": "YOUR_API_KEY",
"passphrase": "YOUR_PASSPHRASE",
"timestamp": "1766124407915",
"sign": "BASE64_ENCODED_SIGNATURE"
}
]
}参数说明:
| 参数 | 类型 | 说明 |
|---|---|---|
| apiKey | String | API Key |
| passphrase | String | API 口令 |
| timestamp | String | 当前时间戳(毫秒) |
| sign | String | 签名(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 | 参数错误 |
最佳实践
- 连接管理:使用指数退避策略进行重连
- 心跳机制:定期发送心跳保持连接
- 订阅管理:避免重复订阅,及时取消不需要的订阅
- 数据处理:使用消息队列异步处理数据
- 安全建议:使用 WSS 加密连接,妥善保管 API Key