WebSocket API Reference

Real-time na pag-stream ng datos para sa whale positions, funding rates, liquidations, at AI confirmation scores. Sub-second latency na may automatic reconnection, efficient na data compression, at multi-stream subscriptions.

Pangkalahatang-ideya

Ang WebSocket API ay nagbibigay ng low-latency, bidirectional na komunikasyon para sa real-time na datos ng cryptocurrency derivatives. Sa halip na mag-poll ng REST endpoints tuwing 5-30 segundo, ang WebSocket connections ay naghahatid ng updates agad kapag nagbago ang market conditions. Perpekto para sa trading bots, alert systems, at real-time dashboards.

Mga pangunahing advantage ng WebSocket kaysa REST:

Sub-second latency para sa market-moving events (liquidations, whale moves)

Efficient na bandwidth usage gamit ang delta-encoded updates

Maramihang simultaneous subscriptions sa iisang koneksyon

Server-side filtering at aggregation

Automatic heartbeat at reconnection handling

Mas mababang API request count laban sa iyong quota

Ang WebSocket connections ay available sa lahat ng API tiers. Ang free tier users ay maaaring mag-subscribe sa funding-rates at liquidations streams. Ang Trader at Pro tiers ay nag-uunlock ng whale positions, open interest, at confirmation scores.

Pagpapatunay

Ang WebSocket connections ay gumagamit ng parehong authentication gaya ng REST endpoints. I-pass ang iyong API key bilang query parameter o i-send ito sa unang mensahe pagkatapos kumonekta.

Connection URL

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

Isama ang iyong API key sa connection URL:

URL

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

Connection Lifecycle

Initial Connection

Kapag kumonekta ka sa WebSocket endpoint, ivalidate ng server ang iyong authentication token at magpapadala ng connection acknowledgment.

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

Ang server ay nagpapadala ng periodic heartbeat pings tuwing 30 segundo. Ang iyong client ay dapat tumugon ng pong message para mapanatiling buhay ang koneksyon. Kung hindi makatanggap ang server ng pong response sa loob ng 10 segundo, ang koneksyon ay isasara.

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");
};

Subscriptions

Pagkatapos kumonekta, mag-subscribe sa data streams gamit ang subscription messages. Ang bawat subscription ay nagge-generate ng updates tuwing may pagbabago sa market data.

Subscription Message Format

JSON

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

Unsubscribe Message Format

JSON

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

Whale Positions Stream

Real-time updates para sa malalaking whale positions sa lahat ng tracked symbols at exchanges. Ang updates ay ipinapadala kapag nagbukas, nagsara, o nagbago ang mga positions ng whales. Kasama ang entry price, current price, P&L, leverage, at liquidation risk.

JSON — Subscribe

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

Update Message

JSON — Update

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

Funding Rates Stream

Real-time funding rate updates sa buong Bybit, Binance, at Hyperliquid. Nag-u-update tuwing 1 minuto o tuwing may malaking pagbabago sa rates. Kasama ang individual exchange rates at aggregated metrics.

JSON — Subscribe

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

Update Message

JSON — Update

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

Liquidations Stream

Real-time liquidation feed na nagpapakita ng forced closures ng leveraged positions. Kasama ang position size, liquidation price, direction (long/short), at exchange. Kapaki-pakinabang para sa pag-identify ng liquidation cascades at high-impact market moves.

JSON — Subscribe

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

Update Message

JSON — Update

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

Open Interest Stream

Aggregate open interest para sa lahat ng leverage traders sa bawat symbol. Subaybayan ang OI increases (mas maraming pera na pumapasok sa leverage) at decreases (positions closing). Ang OI divergence mula sa price movement ay nag-i-identify ng hidden bullish/bearish exhaustion.

JSON — Subscribe

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

Confirmation Scores Stream

Real-time AI confirmation scores na pinagsasama ang whale positions, on-chain signals, funding rates, at sentiment data. Nag-u-update ang scores tuwing may pagbabago sa underlying signals, na nagbibigay ng live entry/exit signals para sa trading algorithms.

JSON — Subscribe

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

Automatic Reconnection Logic

Ang network issues o server maintenance ay maaaring maging sanhi ng disconnections. Mag-implement ng exponential backoff reconnection logic para awtomatikong maka-recover mula sa failures habang iginagalang ang server load.

Recommended Reconnection Strategy

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 });

Code Examples

Python WebSocket Client

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

Performance Tips

Filter on subscribe: Gamitin ang params object para i-filter ang data sa server-side (min_position_size, min_size_usd) sa halip na i-filter sa iyong application.

Batch subscriptions: Mag-subscribe sa maraming symbols sa isang mensahe sa halip na isang subscription bawat symbol.

Unsubscribe unused: Kapag hindi mo na kailangan ang isang stream, mag-unsubscribe para makatipid ng bandwidth at mabawasan ang message volume.

Use gzip compression: I-enable ang message compression sa iyong WebSocket client para sa bandwidth savings (20-40% reduction).

Monitor connection health: Subaybayan ang ping/pong latency at automatic reconnections para i-diagnose ang network issues.

Buffer messages during disconnection: Kapag bumagsak ang koneksyon, i-queue up ang strategy signals at i-execute ang mga ito kapag nakakonekta ulit.

Start Streaming Now

Kunin ang iyong API key at simulan ang pagbuo ng mga real-time na sistema ng pangangalakal. Magagamit ang WebSocket streaming sa lahat ng tier.

Kumuha ng API Key

Bumuo ng Mga Real-Time na Sistema ng Pangangalakal

Mag-stream ng mga posisyon ng whale, funding rates, at AI confirmation scores na may sub-second latency.

Tingnan ang Mga Plano