Referensi API WebSocket

Streaming data real-time untuk posisi paus, tarif pendanaan, likuidasi, dan skor konfirmasi AI. Latensi sub-detik dengan rekoneksi otomatis, kompresi data efisien, dan langganan multi-stream.

Ikhtisar

API WebSocket menyediakan komunikasi dua arah dengan latensi rendah untuk data derivatif kripto real-time. Alih-alih melakukan polling ke endpoint REST setiap 5-30 detik, koneksi WebSocket memberikan pembaruan secara instan saat kondisi pasar berubah. Cocok untuk bot trading, sistem peringatan, dan dashboard real-time.

Keunggulan utama WebSocket dibandingkan REST:

Latensi sub-detik untuk peristiwa yang memengaruhi pasar (likuidasi, pergerakan paus)

Penggunaan bandwidth efisien dengan pembaruan yang dienkode delta

Beberapa langganan simultan pada satu koneksi

Penyaringan dan agregasi sisi server

Penanganan heartbeat dan rekoneksi otomatis

Jumlah permintaan API yang lebih rendah terhadap kuota Anda

Koneksi WebSocket tersedia untuk semua tingkatan API. Pengguna tier gratis dapat berlangganan stream tarif pendanaan dan likuidasi. Tier Trader dan Pro membuka akses ke posisi paus, bunga terbuka, dan skor konfirmasi.

Autentikasi

Koneksi WebSocket menggunakan autentikasi yang sama dengan endpoint REST. Masukkan kunci API Anda sebagai parameter query atau kirimkan dalam pesan pertama setelah terhubung.

URL Koneksi

URL WebSocket Dasar: wss://ws.smartmoneyapi.com/stream

Sertakan kunci API Anda di URL koneksi:

URL

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

Siklus Hidup Koneksi

Koneksi Awal

Saat Anda terhubung ke endpoint WebSocket, server memvalidasi token autentikasi Anda dan mengirimkan pengakuan koneksi.

Respons Server (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)

Server mengirimkan ping heartbeat secara berkala setiap 30 detik. Klien Anda harus merespons dengan pesan pong untuk menjaga koneksi tetap hidup. Jika server tidak menerima respons pong dalam 10 detik, koneksi akan ditutup.

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") {
    // Respond to ping with pong
    ws.send(JSON.stringify({
      type: "pong",
      id: msg.id
    }));
  }
};

ws.onopen = () => {
  console.log("Connected to WebSocket");
};

Langganan

Setelah terhubung, berlangganan ke stream data menggunakan pesan langganan. Setiap langganan menghasilkan pembaruan setiap kali data pasar berubah.

Format Pesan Langganan

JSON

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

Format Pesan Berhenti Langganan

JSON

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

Stream Posisi Paus

Pembaruan real-time untuk posisi paus besar pada semua simbol dan bursa yang dilacak. Pembaruan dikirim saat paus membuka, menutup, atau memodifikasi posisi. Termasuk harga masuk, harga saat ini, P&L, leverage, dan risiko likuidasi.

JSON — Langganan

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

Pesan Pembaruan

JSON — Pembaruan

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

Stream Tarif Pendanaan

Pembaruan tarif pendanaan real-time di Bybit, Binance, dan Hyperliquid. Pembaruan setiap 1 menit atau saat tarif berubah secara signifikan. Termasuk tarif individu dari bursa dan metrik agregat.

JSON — Langganan

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

Pesan Pembaruan

JSON — Pembaruan

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

Stream Likuidasi

Feed likuidasi real-time yang menunjukkan penutupan paksa posisi leverage. Termasuk ukuran posisi, harga likuidasi, arah (long/short), dan bursa. Berguna untuk mengidentifikasi kaskade likuidasi dan pergerakan pasar berdampak tinggi.

JSON — Langganan

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

Pesan Pembaruan

JSON — Pembaruan

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

Stream Bunga Terbuka

Bunga terbuka agregat untuk semua trader leverage pada setiap simbol. Lacak peningkatan OI (lebih banyak uang masuk ke leverage) dan penurunan (penutupan posisi). Divergensi OI dari pergerakan harga mengidentifikasi kelelahan bullish/bearish tersembunyi.

JSON — Langganan

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

Stream Skor Konfirmasi

Skor konfirmasi AI real-time yang menggabungkan posisi paus, sinyal on-chain, tarif pendanaan, dan data sentimen. Skor diperbarui setiap kali sinyal dasar berubah, memberikan sinyal masuk/keluar langsung untuk algoritma trading.

JSON — Langganan

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

Logika Rekoneksi Otomatis

Masalah jaringan atau pemeliharaan server dapat menyebabkan pemutusan koneksi. Terapkan logika rekoneksi eksponensial backoff untuk secara otomatis pulih dari kegagalan sambil menghormati beban server.

Strategi Rekoneksi yang Direkomendasikan

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("Connected");
      this.reconnectDelay = 1000; // Reset backoff
      this.resubscribe(); // Re-subscribe after reconnect
    };

    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 error:", err);
  }

  reconnect() {
    console.log(`Reconnecting in ${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(`Update: ${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 });

Contoh Kode

Klien 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:
        # Wait for connection ack
        ack = await websocket.recv()
        print(f"Connected: {ack}")

        # Subscribe to whale positions
        await websocket.send(json.dumps({
            "type": "subscribe",
            "channel": "whale_positions",
            "symbols": ["BTCUSDT", "ETHUSDT"]
        }))

        # Listen for updates
        while True:
            try:
                msg = await websocket.recv()
                data = json.loads(msg)

                if data["type"] == "ping":
                    # Respond to ping
                    await websocket.send(json.dumps({
                        "type": "pong",
                        "id": data["id"]
                    }))
                elif data["type"] == "data":
                    print(f"New position: {data['data']}")
            except websockets.exceptions.ConnectionClosed:
                print("Connection closed, reconnecting...")
                await asyncio.sleep(1)

asyncio.run(stream_whale_positions())

Tips Performa

Filter saat berlangganan: Gunakan objek params untuk memfilter data di sisi server (min_position_size, min_size_usd) alih-alih memfilter di aplikasi Anda.

Batch langganan: Berlangganan ke beberapa simbol dalam satu pesan alih-alih satu langganan per simbol.

Berhenti langganan yang tidak digunakan: Saat Anda tidak memerlukan stream lagi, berhenti berlangganan untuk menghemat bandwidth dan mengurangi volume pesan.

Gunakan kompresi gzip: Aktifkan kompresi pesan di klien WebSocket Anda untuk menghemat bandwidth (pengurangan 20-40%).

Pantau kesehatan koneksi: Lacak latensi ping/pong dan rekoneksi otomatis untuk mendiagnosis masalah jaringan.

Buffer pesan saat pemutusan koneksi: Saat koneksi terputus, antrekan sinyal strategi dan jalankan saat terhubung kembali.

Mulai Streaming Sekarang

Dapatkan kunci API Anda dan mulai membangun sistem trading real-time. Streaming WebSocket tersedia di semua tingkatan.

Dapatkan Kunci API

Bangun Sistem Trading Real-Time

Stream posisi whale, funding rates, dan skor konfirmasi AI dengan latensi sub-detik.

Lihat Paket