Tài liệu WebSocket API

Truyền dữ liệu thời gian thực về vị thế cá voi, tỷ lệ funding, thanh lý và điểm xác nhận AI. Độ trễ dưới 1 giây với khả năng kết nối lại tự động, nén dữ liệu hiệu quả và đăng ký đa luồng.

Tổng quan

WebSocket API cung cấp giao tiếp hai chiều độ trễ thấp cho dữ liệu phái sinh tiền điện tử thời gian thực. Thay vì phải polling REST endpoint mỗi 5-30 giây, kết nối WebSocket cập nhật ngay lập tức khi thị trường thay đổi. Lý tưởng cho bot giao dịch, hệ thống cảnh báo và bảng điều khiển thời gian thực.

Ưu điểm chính của WebSocket so với REST:

Độ trễ dưới 1 giây cho sự kiện ảnh hưởng thị trường (thanh lý, di chuyển cá voi)

Tiết kiệm băng thông với cập nhật mã hóa delta

Đăng ký đồng thời nhiều luồng trên một kết nối

Lọc và tổng hợp phía máy chủ

Tự động heartbeat và xử lý kết nối lại

Giảm số lượng yêu cầu API trong hạn mức

Kết nối WebSocket có sẵn cho mọi cấp độ API. Người dùng miễn phí có thể đăng ký luồng funding-rates và thanh lý. Cấp Trader và Pro mở khóa vị thế cá voi, open interest và điểm xác nhận.

Xác thực

Kết nối WebSocket sử dụng cùng cơ chế xác thực như REST endpoint. Truyền API key dưới dạng tham số query hoặc gửi trong tin nhắn đầu tiên sau khi kết nối.

URL kết nối

URL WebSocket cơ bản: wss://ws.smartmoneyapi.com/stream

Bao gồm API key trong URL kết nối:

URL

wss://ws.smartmoneyapi.com/stream?token=sk_live_abc123xyz789

Vòng đời kết nối

Kết nối ban đầu

Khi bạn kết nối tới endpoint WebSocket, máy chủ sẽ xác thực token và gửi thông báo xác nhận kết nối.

Phản hồi từ máy chủ (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
}

Heartbeat (Ping/Pong)

Máy chủ gửi ping heartbeat định kỳ mỗi 30 giây. Client phải phản hồi bằng tin nhắn pong để duy trì kết nối. Nếu máy chủ không nhận được pong trong vòng 10 giây, kết nối sẽ bị đóng.

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") {
    // Phản hồi ping bằng pong
    ws.send(JSON.stringify({
      type: "pong",
      id: msg.id
    }));
  }
};

ws.onopen = () => {
  console.log("Đã kết nối WebSocket");
};

Đăng ký

Sau khi kết nối, đăng ký các luồng dữ liệu bằng tin nhắn subscription. Mỗi đăng ký sẽ nhận cập nhật khi dữ liệu thị trường thay đổi.

Định dạng tin nhắn đăng ký

JSON

{
  "type": "subscribe",
  "channel": "whale_positions",
  "symbols": ["BTCUSDT", "ETHUSDT"],
  "params": {
    "min_position_size": 10,
    "exchanges": ["bybit", "binance"]
  }
}

Định dạng tin nhắn hủy đăng ký

JSON

{
  "type": "unsubscribe",
  "channel": "whale_positions",
  "symbols": ["BTCUSDT"]
}

Luồng vị thế cá voi

Cập nhật thời gian thực về các vị thế lớn của cá voi trên mọi symbol và sàn giao dịch. Gửi cập nhật khi cá voi mở, đóng hoặc điều chỉnh vị thế. Bao gồm giá vào lệnh, giá hiện tại, P&L, đòn bẩy và rủi ro thanh lý.

JSON — Đăng ký

{
  "type": "subscribe",
  "channel": "whale_positions",
  "symbols": ["BTCUSDT", "ETHUSDT", "SOLUSDT"]
}

Tin nhắn cập nhật

JSON — Cập nhật

{
  "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"
  }
}

Luồng tỷ lệ funding

Cập nhật tỷ lệ funding thời gian thực trên Bybit, Binance và Hyperliquid. Cập nhật mỗi 1 phút hoặc khi tỷ lệ thay đổi đáng kể. Bao gồm tỷ lệ từng sàn và chỉ số tổng hợp.

JSON — Đăng ký

{
  "type": "subscribe",
  "channel": "funding_rates",
  "symbols": ["BTCUSDT", "ETHUSDT"]
}

Tin nhắn cập nhật

JSON — Cập nhật

{
  "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
    }
  }
}

Luồng thanh lý

Dữ liệu thanh lý thời gian thực về các vị thế bị đóng bắt buộc. Bao gồm kích thước vị thế, giá thanh lý, hướng (long/short) và sàn giao dịch. Hữu ích để xác định hiệu ứng domino thanh lý và biến động mạnh.

JSON — Đăng ký

{
  "type": "subscribe",
  "channel": "liquidations",
  "params": {
    "min_size_usd": 50000
  }
}

Tin nhắn cập nhật

JSON — Cập nhật

{
  "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"
  }
}

Luồng Open Interest

Tổng hợp open interest của tất cả nhà giao dịch đòn bẩy trên mỗi symbol. Theo dõi tăng OI (tiền vào đòn bẩy) và giảm OI (đóng vị thế). Phân kỳ OI với giá giúp xác định điểm đảo chiều tiềm ẩn.

JSON — Đăng ký

{
  "type": "subscribe",
  "channel": "open_interest",
  "symbols": ["BTCUSDT", "ETHUSDT"]
}

Luồng điểm xác nhận AI

Điểm xác nhận AI thời gian thực kết hợp vị thế cá voi, tín hiệu on-chain, tỷ lệ funding và dữ liệu sentiment. Cập nhật khi tín hiệu thay đổi, cung cấp tín hiệu vào/lệnh cho thuật toán giao dịch.

JSON — Đăng ký

{
  "type": "subscribe",
  "channel": "confirmation_scores",
  "symbols": ["BTCUSDT", "ETHUSDT", "SOLUSDT"]
}

Logic kết nối lại tự động

Sự cố mạng hoặc bảo trì có thể gây ngắt kết nối. Triển khai logic kết nối lại exponential backoff để tự động phục hồi sau lỗi mà vẫn tôn trọng tải máy chủ.

Chiến lược kết nối lại đề xuất

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("Đã kết nối");
      this.reconnectDelay = 1000; // Reset backoff
      this.resubscribe(); // Đăng ký lại sau khi kết nối
    };

    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("Lỗi WebSocket:", err);
  }

  reconnect() {
    console.log(`Kết nối lại sau ${this.reconnectDelay}ms`);
    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(`Cập nhật: ${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 });

Ví dụ mã

Client WebSocket Python

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:
        # Chờ xác nhận kết nối
        ack = await websocket.recv()
        print(f"Đã kết nối: {ack}")

        # Đăng ký vị thế cá voi
        await websocket.send(json.dumps({
            "type": "subscribe",
            "channel": "whale_positions",
            "symbols": ["BTCUSDT", "ETHUSDT"]
        }))

        # Lắng nghe cập nhật
        while True:
            try:
                msg = await websocket.recv()
                data = json.loads(msg)

                if data["type"] == "ping":
                    # Phản hồi ping
                    await websocket.send(json.dumps({
                        "type": "pong",
                        "id": data["id"]
                    }))
                elif data["type"] == "data":
                    print(f"Vị thế mới: {data['data']}")
            except websockets.exceptions.ConnectionClosed:
                print("Mất kết nối, đang kết nối lại...")
                await asyncio.sleep(1)

asyncio.run(stream_whale_positions())

Mẹo hiệu suất

Lọc khi đăng ký: Sử dụng params để lọc dữ liệu phía máy chủ (min_position_size, min_size_usd) thay vì lọc trong ứng dụng.

Đăng ký hàng loạt: Đăng ký nhiều symbol trong một tin nhắn thay vì từng symbol riêng lẻ.

Hủy đăng ký không dùng: Khi không cần luồng dữ liệu nữa, hủy đăng ký để tiết kiệm băng thông.

Dùng nén gzip: Bật nén tin nhắn trong client WebSocket để tiết kiệm 20-40% băng thông.

Giám sát kết nối: Theo dõi độ trễ ping/pong và số lần kết nối lại để chẩn đoán sự cố mạng.

Đệm tin nhắn khi mất kết nối: Khi kết nối gián đoạn, xếp hàng các tín hiệu chiến lược và thực thi khi kết nối lại.

Bắt Đầu Truyền Dữ Liệu Ngay

Nhận API key của bạn và bắt đầu xây dựng hệ thống giao dịch thời gian thực. Hỗ trợ streaming qua WebSocket trên mọi gói dịch vụ.

Nhận API Key

Xây Dựng Hệ Thống Giao Dịch Thời Gian Thực

Theo dõi vị thế cá voi, tỷ lệ funding và điểm xác nhận AI với độ trễ dưới 1 giây.

Xem Các Gói