现货 WebSocket 指南

REST API 非常适合执行操作（如下单），但对于监控市场来说太慢了。对于实时数据，您应该使用 WebSocket API。

本指南涵盖了连接、认证和处理实时数据流的内容。

准备工作

• 端点: wss://api.big.one/ws/v2
• 库: 我们推荐 websockets (Python) 或 ws (Node.js)。
• 协议: JSON 是默认且最易于使用的协议。

---

第一课：连接与心跳

BigONE 的 WebSocket 服务器要求您保持连接活跃。如果您长时间不活动，服务器将断开您的连接。

逻辑

1. 连接到 wss://api.big.one/ws/v2。
2. 每 30 秒 发送一个 Ping 帧或虚拟消息。
3. 监听来自服务器的 PING 消息并回复 PONG（大多数库会自动处理此操作）。

import asyncio
import websockets
import json

URL = "wss://api.big.one/ws/v2"

async def connect():
    async with websockets.connect(URL) as websocket:
        print("Connected!")
        
        # 心跳循环 (简化版)
        while True:
            try:
                msg = await websocket.recv()
                print(f"< {msg}")
            except websockets.exceptions.ConnectionClosed:
                print("Disconnected")
                break

---

第二课：订阅公共频道

观看像 订单簿 或 最新成交 这样的公共市场数据不需要认证。

请求格式

每个请求都需要一个唯一的 requestId。

{
  "requestId": "1",
  "subscribeMarketDepthRequest": {
    "market": "BTC-USDT"
  }
}

处理订单簿数据

订单簿数据流发送两种类型的消息：

1. 快照 (Snapshot): 完整的订单簿（买单 + 卖单）。订阅后立即发送。
2. 更新 (Update): 增量变更。

订单簿策略

对于简单的机器人，您可以只使用快照并定期重新订阅。对于高频交易，您必须将更新应用到本地快照中。

---

第三课：认证 (私有频道)

要接收关于 您的订单 或 您的余额 的更新，您必须登录。

逻辑

1. 连接。
2. 立即 发送带有 JWT 的 authenticateCustomerRequest。
3. 等待成功响应。
4. 然后 订阅私有频道。

Payload:

{
  "requestId": "auth-1",
  "authenticateCustomerRequest": {
    "token": "Bearer YOUR_JWT_TOKEN"
  }
}

---

完整示例

此脚本连接、认证并同时监控 BTC-USDT 订单簿 和 您的订单状态。

import asyncio
import websockets
import json
import time
import jwt # pip install PyJWT

# --- 配置 ---
API_KEY = "YOUR_KEY"
SECRET_KEY = "YOUR_SECRET"
WS_URL = "wss://api.big.one/ws/v2"

def generate_token():
    payload = {
        "sub": API_KEY,
        "nonce": int(time.time() * 1000000),
        "iat": int(time.time()),
        "exp": int(time.time()) + 60 # Token 仅用于握手
    }
    return jwt.encode(payload, SECRET_KEY, algorithm="HS256")

async def run():
    async with websockets.connect(WS_URL) as ws:
        print("1. Connected")

        # 2. 认证
        token = generate_token()
        auth_req = {
            "requestId": "auth",
            "authenticateCustomerRequest": {"token": f"Bearer {token}"}
        }
        await ws.send(json.dumps(auth_req))
        print("2. Sent Auth...")

        # 3. 订阅
        subs = [
            # 公共: 订单簿
            {
                "requestId": "sub-depth",
                "subscribeMarketDepthRequest": {"market": "BTC-USDT"}
            },
            # 私有: 我的订单
            {
                "requestId": "sub-orders",
                "subscribeViewerOrdersRequest": {"market": "BTC-USDT"}
            }
        ]

        for sub in subs:
            await ws.send(json.dumps(sub))
        print("3. Subscribed")

        # 4. 循环监听
        while True:
            response = await ws.recv()
            data = json.loads(response)
            
            # 检查错误
            if "error" in data:
                print(f"ERROR: {data['error']}")
                continue

            # 识别消息类型
            if "marketDepth" in data:
                bids = data['marketDepth'].get('bids', [])
                best_bid = bids[0] if bids else "None"
                print(f"[Depth] Best Bid: {best_bid}")
            
            elif "orderUpdate" in data:
                order = data['orderUpdate']
                print(f"[Order] {order['id']} is {order['state']}")

if __name__ == "__main__":
    asyncio.run(run())

结论

WebSocket 对于响应市场波动至关重要。

要点:

• 心跳: 确保您的库处理 Ping 或实现手动保活。
• 顺序: 始终在订阅私有频道 之前 进行认证。
• 数据流: 对初始快照和后续更新进行不同处理。

下一步:

• 阅读 现货 WebSocket 参考 获取完整的频道列表。
• 实现一个本地订单簿缓存，高效地应用 marketDepth 更新。