Referencia de la API WebSocket

Transmisión de datos en tiempo real para posiciones de ballenas, tarifas de financiación, liquidaciones y puntuaciones de confirmación de IA. Latencia inferior a un segundo con reconexión automática, compresión eficiente de datos y suscripciones a múltiples flujos.

Resumen

La API WebSocket proporciona comunicación bidireccional de baja latencia para datos en tiempo real de derivados de criptomonedas. En lugar de sondear endpoints REST cada 5-30 segundos, las conexiones WebSocket entregan actualizaciones al instante cuando cambian las condiciones del mercado. Ideal para bots de trading, sistemas de alerta y paneles en tiempo real.

Ventajas clave de WebSocket sobre REST:

Latencia inferior a un segundo para eventos que mueven el mercado (liquidaciones, movimientos de ballenas)

Uso eficiente del ancho de banda con actualizaciones codificadas en delta

Múltiples suscripciones simultáneas en una sola conexión

Filtrado y agregación en el servidor

Manejo automático de latidos y reconexión

Menor recuento de solicitudes de API contra tu cuota

Las conexiones WebSocket están disponibles para todos los niveles de API. Los usuarios de nivel gratuito pueden suscribirse a los flujos de tarifas de financiación y liquidaciones. Los niveles Trader y Pro desbloquean posiciones de ballenas, interés abierto y puntuaciones de confirmación.

Autenticación

Las conexiones WebSocket utilizan la misma autenticación que los endpoints REST. Pasa tu clave API como parámetro de consulta o envíala en el primer mensaje después de conectarte.

URL de conexión

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

Incluye tu clave API en la URL de conexión:

URL

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

Ciclo de vida de la conexión

Conexión inicial

Cuando te conectas al endpoint WebSocket, el servidor valida tu token de autenticación y envía un acuse de recibo de conexión.

Respuesta del servidor (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
}

Latido (Ping/Pong)

El servidor envía latidos ping periódicos cada 30 segundos. Tu cliente debe responder con un mensaje pong para mantener la conexión activa. Si el servidor no recibe una respuesta pong en 10 segundos, la conexión se cerrará.

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

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

Suscripciones

Después de conectarte, suscríbete a flujos de datos usando mensajes de suscripción. Cada suscripción genera actualizaciones cuando cambian los datos del mercado.

Formato del mensaje de suscripción

JSON

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

Formato del mensaje de cancelación de suscripción

JSON

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

Flujo de posiciones de ballenas

Actualizaciones en tiempo real de grandes posiciones de ballenas en todos los símbolos e intercambios rastreados. Las actualizaciones se envían cuando las ballenas abren, cierran o modifican posiciones. Incluye precio de entrada, precio actual, P&L, apalancamiento y riesgo de liquidación.

JSON — Suscribirse

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

Mensaje de actualización

JSON — Actualización

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

Flujo de tarifas de financiación

Actualizaciones en tiempo real de las tarifas de financiación en Bybit, Binance e Hyperliquid. Se actualiza cada 1 minuto o cuando las tarifas cambian significativamente. Incluye tarifas individuales de intercambio y métricas agregadas.

JSON — Suscribirse

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

Mensaje de actualización

JSON — Actualización

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

Flujo de liquidaciones

Transmisión en tiempo real de liquidaciones que muestra el cierre forzado de posiciones apalancadas. Incluye tamaño de la posición, precio de liquidación, dirección (long/short) e intercambio. Útil para identificar cascadas de liquidación y movimientos de mercado de alto impacto.

JSON — Suscribirse

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

Mensaje de actualización

JSON — Actualización

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

Flujo de interés abierto

Interés abierto agregado para todos los operadores con apalancamiento en cada símbolo. Rastrea aumentos de OI (más dinero ingresando al apalancamiento) y disminuciones (cierre de posiciones). La divergencia del OI con el movimiento del precio identifica agotamiento alcista/bajista oculto.

JSON — Suscribirse

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

Flujo de puntuaciones de confirmación

Puntuaciones de confirmación de IA en tiempo real que combinan posiciones de ballenas, señales on-chain, tarifas de financiación y datos de sentimiento. Las puntuaciones se actualizan cuando cambian las señales subyacentes, proporcionando señales de entrada/salida en vivo para algoritmos de trading.

JSON — Suscribirse

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

Lógica de reconexión automática

Los problemas de red o el mantenimiento del servidor pueden causar desconexiones. Implementa una lógica de reconexión con retroceso exponencial para recuperarte automáticamente de fallos respetando la carga del servidor.

Estrategia de reconexión recomendada

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("Conectado");
      this.reconnectDelay = 1000; // Reinicia el retroceso
      this.resubscribe(); // Vuelve a suscribirte después de reconectar
    };

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

  reconnect() {
    console.log(`Reconectando en ${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(`Actualización: ${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 });

Ejemplos de código

Cliente WebSocket en 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:
        # Espera el acuse de recibo de conexión
        ack = await websocket.recv()
        print(f"Conectado: {ack}")

        # Suscríbete a posiciones de ballenas
        await websocket.send(json.dumps({
            "type": "subscribe",
            "channel": "whale_positions",
            "symbols": ["BTCUSDT", "ETHUSDT"]
        }))

        # Escucha actualizaciones
        while True:
            try:
                msg = await websocket.recv()
                data = json.loads(msg)

                if data["type"] == "ping":
                    # Responde al ping
                    await websocket.send(json.dumps({
                        "type": "pong",
                        "id": data["id"]
                    }))
                elif data["type"] == "data":
                    print(f"Nueva posición: {data['data']}")
            except websockets.exceptions.ConnectionClosed:
                print("Conexión cerrada, reconectando...")
                await asyncio.sleep(1)

asyncio.run(stream_whale_positions())

Consejos de rendimiento

Filtra al suscribirte: Usa el objeto params para filtrar datos en el servidor (min_position_size, min_size_usd) en lugar de filtrar en tu aplicación.

Suscripciones por lotes: Suscríbete a múltiples símbolos en un solo mensaje en lugar de una suscripción por símbolo.

Cancela suscripciones no utilizadas: Cuando ya no necesites un flujo, cancela la suscripción para ahorrar ancho de banda y reducir el volumen de mensajes.

Usa compresión gzip: Habilita la compresión de mensajes en tu cliente WebSocket para ahorrar ancho de banda (reducción del 20-40%).

Monitoriza la salud de la conexión: Controla la latencia ping/pong y las reconexiones automáticas para diagnosticar problemas de red.

Almacena mensajes durante la desconexión: Cuando la conexión se interrumpa, pon en cola las señales de tu estrategia y ejecútalas cuando te reconectes.

Comienza a transmitir ahora

Obtén tu clave API y comienza a construir sistemas de trading en tiempo real. La transmisión por WebSocket está disponible en todos los niveles.

Obtener clave API

Construye sistemas de trading en tiempo real

Transmite posiciones de ballenas, tasas de financiamiento y puntajes de confirmación de IA con latencia de menos de un segundo.

Ver planes