WebSocket API 参考文档
实时推送鲸鱼仓位、资金费率、强平数据和AI确认分数。亚秒级延迟，支持自动重连、高效数据压缩及多流订阅。
概述
WebSocket API为加密货币衍生品数据提供低延迟双向通信。相比每5-30秒轮询REST接口，WebSocket能在市场变动时即时推送更新。完美适配交易机器人、预警系统和实时看板。
WebSocket相比REST的核心优势：
市场关键事件（强平、鲸鱼异动）亚秒级延迟
采用差值编码的高效带宽利用
单一连接支持多路并发订阅
服务端过滤与聚合
自动心跳检测与重连机制
减少API配额消耗
所有API套餐均支持WebSocket连接。免费版用户可订阅资金费率和强平数据流，交易版和专业版额外解锁鲸鱼仓位、未平仓合约和确认分数。
身份验证
WebSocket连接使用与REST接口相同的验证机制。可将API密钥作为查询参数传递，或在连接后首条消息中发送。
连接URL
WebSocket基础URL： wss://ws.smartmoneyapi.com/stream
在连接URL中包含API密钥：
URL
wss://ws.smartmoneyapi.com/stream?token=sk_live_abc123xyz789
连接生命周期
初始连接
连接WebSocket端点时，服务器会验证您的身份令牌并返回连接确认。
服务器响应（JSON）
{
"type": "connection_ack",
"connection_id": "conn_1a2b3c4d5e6f7g8h",
"server_version": "1.2.4",
"timestamp": "2026-03-21T14:35:22Z",
"api_tier": "pro",
"max_subscriptions": 50,
"max_symbols_per_sub": 100
}
心跳检测（Ping/Pong）
服务器每30秒发送心跳ping。客户端必须返回pong消息维持连接。若10秒内未收到pong响应，服务器将关闭连接。
JavaScript
const ws = new WebSocket("wss://ws.smartmoneyapi.com/stream?token=sk_live_abc123xyz789");
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
if (msg.type === "ping") {
// 响应ping请求
ws.send(JSON.stringify({
type: "pong",
id: msg.id
}));
}
};
ws.onopen = () => {
console.log("已连接WebSocket");
};
订阅
连接成功后，通过订阅消息订阅数据流。每个订阅会在市场数据变化时触发更新。
订阅消息格式
JSON
{
"type": "subscribe",
"channel": "whale_positions",
"symbols": ["BTCUSDT", "ETHUSDT"],
"params": {
"min_position_size": 10,
"exchanges": ["bybit", "binance"]
}
}
取消订阅格式
JSON
{
"type": "unsubscribe",
"channel": "whale_positions",
"symbols": ["BTCUSDT"]
}
鲸鱼仓位数据流
实时追踪所有监控标的和交易所的大额仓位变动。当鲸鱼开仓、平仓或调整仓位时触发更新，包含入场价、当前价、盈亏、杠杆和强平风险数据。
JSON — 订阅
{
"type": "subscribe",
"channel": "whale_positions",
"symbols": ["BTCUSDT", "ETHUSDT", "SOLUSDT"]
}
更新消息
JSON — 更新
{
"type": "data",
"channel": "whale_positions",
"symbol": "BTCUSDT",
"data": {
"wallet_address": "0x1234...",
"exchange": "bybit",
"direction": "long",
"position_size": 25.3,
"entry_price": 41200.0,
"current_price": 43200.5,
"pnl": 50701.50,
"pnl_percent": 4.86,
"leverage": 8,
"liquidation_price": 33760.0,
"timestamp": "2026-03-21T14:35:45Z"
}
}
资金费率数据流
实时推送Bybit、Binance和Hyperliquid的资金费率。每分钟或费率显著变动时更新，包含各交易所费率及聚合指标。
JSON — 订阅
{
"type": "subscribe",
"channel": "funding_rates",
"symbols": ["BTCUSDT", "ETHUSDT"]
}
更新消息
JSON — 更新
{
"type": "data",
"channel": "funding_rates",
"symbol": "BTCUSDT",
"data": {
"timestamp": "2026-03-21T14:00:00Z",
"bybit": {
"rate": 0.000120,
"next_rate": 0.000145
},
"binance": {
"rate": 0.000098,
"next_rate": 0.000115
},
"hyperliquid": {
"rate": 0.000140,
"next_rate": 0.000160
},
"aggregated": {
"mean": 0.000119,
"median": 0.000120,
"spread": 0.000062
}
}
}
强平数据流
实时杠杆仓位强制平仓数据流。包含仓位规模、强平价、方向（多/空）及交易所信息。用于识别连环强平和市场剧烈波动。
JSON — 订阅
{
"type": "subscribe",
"channel": "liquidations",
"params": {
"min_size_usd": 50000
}
}
更新消息
JSON — 更新
{
"type": "data",
"channel": "liquidations",
"data": {
"exchange": "binance",
"symbol": "BTCUSDT",
"direction": "long",
"position_size": 12.5,
"liquidation_price": 41000.0,
"size_usd": 512500.0,
"timestamp": "2026-03-21T14:35:12Z"
}
}
未平仓合约数据流
各交易对杠杆交易者的聚合未平仓合约。追踪OI增长（杠杆资金入场）和减少（仓位平仓）。OI与价格走势的背离可识别潜在多空衰竭。
JSON — 订阅
{
"type": "subscribe",
"channel": "open_interest",
"symbols": ["BTCUSDT", "ETHUSDT"]
}
确认分数数据流
实时AI确认分数，综合鲸鱼仓位、链上信号、资金费率和情绪数据。当底层信号变化时即时更新，为交易算法提供实时进出场信号。
JSON — 订阅
{
"type": "subscribe",
"channel": "confirmation_scores",
"symbols": ["BTCUSDT", "ETHUSDT", "SOLUSDT"]
}
自动重连逻辑
网络问题或服务器维护可能导致断连。建议实现指数退避重连机制，在故障恢复时自动重连并兼顾服务器负载。
推荐重连策略
JavaScript
class SmartMoneyWebSocket {
constructor(token, options = {}) {
this.token = token;
this.maxReconnectDelay = options.maxReconnectDelay || 30000;
this.reconnectDelay = 1000;
this.subscriptions = new Map();
this.connect();
}
connect() {
this.ws = new WebSocket(
`wss://ws.smartmoneyapi.com/stream?token=${this.token}`
);
this.ws.onopen = () => {
console.log("连接成功");
this.reconnectDelay = 1000; // 重置退避时间
this.resubscribe(); // 重连后重新订阅
};
this.ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
if (msg.type === "ping") {
this.ws.send(JSON.stringify({ type: "pong", id: msg.id }));
}
this.onMessage(msg);
};
this.ws.onclose = () => this.reconnect();
this.ws.onerror = (err) => console.error("WebSocket错误:", err);
}
reconnect() {
console.log(`将在${this.reconnectDelay}毫秒后重连`);
setTimeout(() => {
this.connect();
this.reconnectDelay = Math.min(
this.reconnectDelay * 1.5,
this.maxReconnectDelay
);
}, this.reconnectDelay);
}
subscribe(channel, symbols, params) {
const key = `${channel}:${symbols.join(",")}`;
this.subscriptions.set(key, { channel, symbols, params });
this.ws.send(JSON.stringify({ type: "subscribe", channel, symbols, params }));
}
resubscribe() {
for (const { channel, symbols, params } of this.subscriptions.values()) {
this.ws.send(JSON.stringify({ type: "subscribe", channel, symbols, params }));
}
}
onMessage(msg) {
if (msg.type === "data") {
console.log(`更新: ${msg.channel}/${msg.symbol}`, msg.data);
}
}
}
const client = new SmartMoneyWebSocket("sk_live_abc123xyz789");
client.subscribe("whale_positions", ["BTCUSDT", "ETHUSDT"]);
client.subscribe("funding_rates", ["BTCUSDT"]);
client.subscribe("liquidations", [], { min_size_usd: 100000 });
代码示例
Python WebSocket客户端
Python
import asyncio
import json
import websockets
async def stream_whale_positions():
uri = "wss://ws.smartmoneyapi.com/stream?token=sk_live_abc123xyz789"
async with websockets.connect(uri) as websocket:
# 等待连接确认
ack = await websocket.recv()
print(f"连接成功: {ack}")
# 订阅鲸鱼仓位
await websocket.send(json.dumps({
"type": "subscribe",
"channel": "whale_positions",
"symbols": ["BTCUSDT", "ETHUSDT"]
}))
# 监听更新
while True:
try:
msg = await websocket.recv()
data = json.loads(msg)
if data["type"] == "ping":
# 响应ping
await websocket.send(json.dumps({
"type": "pong",
"id": data["id"]
}))
elif data["type"] == "data":
print(f"新仓位: {data['data']}")
except websockets.exceptions.ConnectionClosed:
print("连接中断，正在重连...")
await asyncio.sleep(1)
asyncio.run(stream_whale_positions())
性能优化
订阅时过滤： 使用params对象进行服务端过滤（如min_position_size, min_size_usd），而非在应用中处理。
批量订阅： 单条消息内订阅多个交易对，而非逐个订阅。
及时取消： 不再需要的数据流应及时取消订阅以节省带宽。
启用压缩： 在WebSocket客户端启用gzip压缩（可减少20-40%带宽）。
监控连接： 追踪ping/pong延迟和自动重连情况以诊断网络问题。
断连缓冲： 连接中断时缓存策略信号，重连后统一执行。