Riferimento API WebSocket

Streaming di dati in tempo reale per posizioni delle balene, tassi di funding, liquidazioni e punteggi di conferma AI. Latenza inferiore al secondo con riconnessione automatica, compressione efficiente dei dati e sottoscrizioni multi-stream.

Panoramica

L'API WebSocket fornisce una comunicazione bidirezionale a bassa latenza per dati in tempo reale sui derivati crittografici. Invece di interrogare gli endpoint REST ogni 5-30 secondi, le connessioni WebSocket forniscono aggiornamenti istantanei quando le condizioni di mercato cambiano. Ideale per bot di trading, sistemi di allerta e dashboard in tempo reale.

Vantaggi chiave di WebSocket rispetto a REST:

Latenza inferiore al secondo per eventi che muovono il mercato (liquidazioni, mosse delle balene)

Utilizzo efficiente della banda con aggiornamenti codificati a delta

Sottoscrizioni multiple simultanee su una singola connessione

Filtraggio e aggregazione lato server

Gestione automatica di heartbeat e riconnessione

Numero inferiore di richieste API contro il tuo limite

Le connessioni WebSocket sono disponibili per tutti i livelli API. Gli utenti del livello gratuito possono sottoscrivere gli stream di tassi di funding e liquidazioni. I livelli Trader e Pro sbloccano posizioni delle balene, open interest e punteggi di conferma.

Autenticazione

Le connessioni WebSocket utilizzano la stessa autenticazione degli endpoint REST. Passa la tua chiave API come parametro di query o inviala nel primo messaggio dopo la connessione.

URL di Connessione

URL WebSocket di base: wss://ws.smartmoneyapi.com/stream

Includi la tua chiave API nell'URL di connessione:

URL

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

Ciclo di Vita della Connessione

Connessione Iniziale

Quando ti connetti all'endpoint WebSocket, il server convalida il tuo token di autenticazione e invia un acknowledgment di connessione.

Risposta del 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)

Il server invia periodicamente heartbeat ping ogni 30 secondi. Il tuo client deve rispondere con un messaggio pong per mantenere attiva la connessione. Se il server non riceve una risposta pong entro 10 secondi, la connessione verrà chiusa.

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") {
    // Rispondi al ping con un pong
    ws.send(JSON.stringify({
      type: "pong",
      id: msg.id
    }));
  }
};

ws.onopen = () => {
  console.log("Connesso a WebSocket");
};

Sottoscrizioni

Dopo la connessione, sottoscrivi agli stream di dati utilizzando messaggi di sottoscrizione. Ogni sottoscrizione genera aggiornamenti ogni volta che i dati di mercato cambiano.

Formato del Messaggio di Sottoscrizione

JSON

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

Formato del Messaggio di Annullamento Sottoscrizione

JSON

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

Stream delle Posizioni delle Balene

Aggiornamenti in tempo reale per grandi posizioni delle balene su tutti i simboli e exchange tracciati. Gli aggiornamenti vengono inviati quando le balene aprono, chiudono o modificano posizioni. Include prezzo di ingresso, prezzo corrente, P&L, leva e rischio di liquidazione.

JSON — Sottoscrivi

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

Messaggio di Aggiornamento

JSON — Aggiornamento

{
  "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 dei Tassi di Funding

Aggiornamenti in tempo reale sui tassi di funding su Bybit, Binance e Hyperliquid. Aggiornamenti ogni 1 minuto o quando i tassi cambiano significativamente. Include tassi individuali degli exchange e metriche aggregate.

JSON — Sottoscrivi

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

Messaggio di Aggiornamento

JSON — Aggiornamento

{
  "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 delle Liquidazioni

Feed in tempo reale delle liquidazioni che mostra le chiusure forzate di posizioni con leva. Include dimensione della posizione, prezzo di liquidazione, direzione (long/short) e exchange. Utile per identificare cascate di liquidazioni e mosse di mercato ad alto impatto.

JSON — Sottoscrivi

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

Messaggio di Aggiornamento

JSON — Aggiornamento

{
  "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 dell'Open Interest

Open interest aggregato per tutti i trader con leva su ciascun simbolo. Tieni traccia degli aumenti di OI (più soldi che entrano nella leva) e delle diminuzioni (chiusure di posizioni). La divergenza dell'OI dal movimento dei prezzi identifica l'esaurimento rialzista/ribassista nascosto.

JSON — Sottoscrivi

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

Stream dei Punteggi di Conferma

Punteggi di conferma AI in tempo reale che combinano posizioni delle balene, segnali on-chain, tassi di funding e dati di sentiment. I punteggi si aggiornano ogni volta che cambiano i segnali sottostanti, fornendo segnali di ingresso/uscita in tempo reale per algoritmi di trading.

JSON — Sottoscrivi

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

Logica di Riconnessione Automatica

Problemi di rete o manutenzione del server possono causare disconnessioni. Implementa una logica di riconnessione con backoff esponenziale per riprendersi automaticamente dagli errori rispettando il carico del server.

Strategia di Riconnessione Consigliata

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("Connesso");
      this.reconnectDelay = 1000; // Ripristina il backoff
      this.resubscribe(); // Ri-sottoscrivi dopo la riconnessione
    };

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

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

Esempi di Codice

Client WebSocket in 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:
        # Attendi l'acknowledgment di connessione
        ack = await websocket.recv()
        print(f"Connesso: {ack}")

        # Sottoscrivi alle posizioni delle balene
        await websocket.send(json.dumps({
            "type": "subscribe",
            "channel": "whale_positions",
            "symbols": ["BTCUSDT", "ETHUSDT"]
        }))

        # Ascolta gli aggiornamenti
        while True:
            try:
                msg = await websocket.recv()
                data = json.loads(msg)

                if data["type"] == "ping":
                    # Rispondi al ping
                    await websocket.send(json.dumps({
                        "type": "pong",
                        "id": data["id"]
                    }))
                elif data["type"] == "data":
                    print(f"Nuova posizione: {data['data']}")
            except websockets.exceptions.ConnectionClosed:
                print("Connessione chiusa, riconnessione...")
                await asyncio.sleep(1)

asyncio.run(stream_whale_positions())

Consigli sulle Prestazioni

Filtra alla sottoscrizione: Usa l'oggetto params per filtrare i dati lato server (min_position_size, min_size_usd) invece di filtrare nella tua applicazione.

Sottoscrizioni in batch: Sottoscrivi a più simboli in un singolo messaggio invece di una sottoscrizione per simbolo.

Annulla le sottoscrizioni inutilizzate: Quando non hai più bisogno di uno stream, annulla la sottoscrizione per risparmiare banda e ridurre il volume dei messaggi.

Usa la compressione gzip: Abilita la compressione dei messaggi nel tuo client WebSocket per risparmiare banda (riduzione del 20-40%).

Monitora la salute della connessione: Tieni traccia della latenza ping/pong e delle riconnessioni automatiche per diagnosticare problemi di rete.

Bufferizza i messaggi durante la disconnessione: Quando la connessione cade, metti in coda i segnali della strategia e eseguili quando ti riconnetterai.

Inizia lo Streaming Ora

Ottieni la tua chiave API e inizia a costruire sistemi di trading in tempo reale. Lo streaming WebSocket è disponibile in tutti i livelli.

Ottieni Chiave API

Costruisci Sistemi di Trading in Tempo Reale

Streaming di posizioni delle balene, tassi di finanziamento e punteggi di conferma AI con latenza sub-secondo.

Visualizza Piani