WebSocket API Reference

Real-time data streaming for whale positions, funding rates, liquidations, and AI confirmation scores. Sub-second latency with automatic reconnection, efficient data compression, and multi-stream subscriptions.

Overview

The WebSocket API provides low-latency, bidirectional communication for real-time cryptocurrency derivatives data. Instead of polling REST endpoints every 5-30 seconds, WebSocket connections deliver updates instantly when market conditions change. Perfect for trading bots, alert systems, and real-time dashboards.

Key advantages of WebSocket over REST:

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

Efficient bandwidth usage with delta-encoded updates

Multiple simultaneous subscriptions on single connection

Server-side filtering and aggregation

Automatic heartbeat and reconnection handling

Lower API request count against your quota

WebSocket connections are available to all API tiers. Free tier users can subscribe to funding-rates and liquidations streams. Trader and Pro tiers unlock whale positions, open interest, and confirmation scores.

Authentication

WebSocket connections use the same authentication as REST endpoints. Pass your API key as a query parameter or send it in the first message after connecting.

Connection URL

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

Include your API key in the connection URL:

URL

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

Connection Lifecycle

Initial Connection

When you connect to the WebSocket endpoint, the server validates your authentication token and sends a 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)

The server sends periodic heartbeat pings every 30 seconds. Your client must respond with a pong message to keep the connection alive. If the server doesn't receive a pong response within 10 seconds, the connection will be closed.

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

After connecting, subscribe to data streams using subscription messages. Each subscription generates updates whenever market data changes.

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 for large whale positions on all tracked symbols and exchanges. Updates are sent when whales open, close, or modify positions. Includes entry price, current price, P&L, leverage, and 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 across Bybit, Binance, and Hyperliquid. Updates every 1 minute or whenever rates change significantly. Includes individual exchange rates and 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 showing forced closures of leveraged positions. Includes position size, liquidation price, direction (long/short), and exchange. Useful for identifying liquidation cascades and 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 for all leverage traders on each symbol. Track OI increases (more money entering leverage) and decreases (positions closing). OI divergence from price movement identifies hidden bullish/bearish exhaustion.

JSON — Subscribe

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

Confirmation Scores Stream

Real-time AI confirmation scores combining whale positions, on-chain signals, funding rates, and sentiment data. Scores update whenever underlying signals change, providing live entry/exit signals for trading algorithms.

JSON — Subscribe

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

Automatic Reconnection Logic

Network issues or server maintenance may cause disconnections. Implement exponential backoff reconnection logic to automatically recover from failures while respecting 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: Use the params object to filter data server-side (min_position_size, min_size_usd) rather than filtering in your application.

Batch subscriptions: Subscribe to multiple symbols in a single message rather than one subscription per symbol.

Unsubscribe unused: When you no longer need a stream, unsubscribe to save bandwidth and reduce message volume.

Use gzip compression: Enable message compression in your WebSocket client for bandwidth savings (20-40% reduction).

Monitor connection health: Track ping/pong latency and automatic reconnections to diagnose network issues.

Buffer messages during disconnection: When the connection drops, queue up strategy signals and execute them when reconnected.

Start Streaming Now

Get your API key and start building real-time trading systems. WebSocket streaming is available across all tiers.

Get API Key

Build Real-Time Trading Systems

Stream whale positions, funding rates, and AI confirmation scores with sub-second latency.

View Plans