Referência da API WebSocket

Streaming de dados em tempo real para posições de baleias, taxas de funding, liquidações e pontuações de confirmação de IA. Latência submilissegundo com reconexão automática, compressão eficiente de dados e assinaturas de múltiplos streams.

Visão Geral

A API WebSocket fornece comunicação bidirecional de baixa latência para dados de derivativos de criptomoedas em tempo real. Em vez de consultar endpoints REST a cada 5-30 segundos, as conexões WebSocket entregam atualizações instantaneamente quando as condições do mercado mudam. Perfeito para bots de negociação, sistemas de alerta e painéis em tempo real.

Vantagens-chave do WebSocket sobre REST:

Latência submilissegundo para eventos que movimentam o mercado (liquidações, movimentos de baleias)

Uso eficiente de largura de banda com atualizações codificadas em delta

Múltiplas assinaturas simultâneas em uma única conexão

Filtragem e agregação no lado do servidor

Manuseio automático de heartbeat e reconexão

Menor contagem de solicitações de API contra sua cota

As conexões WebSocket estão disponíveis para todos os níveis de API. Usuários do nível gratuito podem assinar streams de taxas de funding e liquidações. Os níveis Trader e Pro desbloqueiam posições de baleias, interesse aberto e pontuações de confirmação.

Autenticação

As conexões WebSocket usam a mesma autenticação dos endpoints REST. Passe sua chave de API como um parâmetro de consulta ou envie-a na primeira mensagem após a conexão.

URL de Conexão

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

Inclua sua chave de API na URL de conexão:

URL

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

Ciclo de Vida da Conexão

Conexão Inicial

Quando você se conecta ao endpoint WebSocket, o servidor valida seu token de autenticação e envia uma confirmação de conexão.

Resposta do 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
}

Heartbeat (Ping/Pong)

O servidor envia pings de heartbeat periódicos a cada 30 segundos. Seu cliente deve responder com uma mensagem pong para manter a conexão ativa. Se o servidor não receber uma resposta pong dentro de 10 segundos, a conexão será fechada.

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

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

Assinaturas

Após conectar, assine streams de dados usando mensagens de assinatura. Cada assinatura gera atualizações sempre que os dados do mercado mudam.

Formato da Mensagem de Assinatura

JSON

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

Formato da Mensagem de Cancelamento de Assinatura

JSON

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

Stream de Posições de Baleias

Atualizações em tempo real para grandes posições de baleias em todos os símbolos e exchanges rastreados. As atualizações são enviadas quando as baleias abrem, fecham ou modificam posições. Inclui preço de entrada, preço atual, P&L, alavancagem e risco de liquidação.

JSON — Assinar

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

Mensagem de Atualização

JSON — Atualização

{
  "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 de Taxas de Funding

Atualizações em tempo real das taxas de funding em Bybit, Binance e Hyperliquid. Atualizações a cada 1 minuto ou sempre que as taxas mudam significativamente. Inclui taxas individuais de exchanges e métricas agregadas.

JSON — Assinar

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

Mensagem de Atualização

JSON — Atualização

{
  "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 de Liquidações

Feed de liquidações em tempo real mostrando fechamentos forçados de posições alavancadas. Inclui tamanho da posição, preço de liquidação, direção (long/short) e exchange. Útil para identificar cascatas de liquidação e movimentos de mercado de alto impacto.

JSON — Assinar

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

Mensagem de Atualização

JSON — Atualização

{
  "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 de Interesse Aberto

Interesse aberto agregado para todos os traders de alavancagem em cada símbolo. Acompanhe aumentos de OI (mais dinheiro entrando na alavancagem) e diminuições (fechamento de posições). A divergência do OI em relação ao movimento de preço identifica exaustão oculta de alta/baixa.

JSON — Assinar

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

Stream de Pontuações de Confirmação

Pontuações de confirmação de IA em tempo real combinando posições de baleias, sinais on-chain, taxas de funding e dados de sentimento. As pontuações são atualizadas sempre que os sinais subjacentes mudam, fornecendo sinais de entrada/saída ao vivo para algoritmos de negociação.

JSON — Assinar

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

Lógica de Reconexão Automática

Problemas de rede ou manutenção do servidor podem causar desconexões. Implemente lógica de reconexão com backoff exponencial para recuperar automaticamente de falhas, respeitando a carga do servidor.

Estratégia de Reconexão 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 o backoff
      this.resubscribe(); // Reassina após 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("Erro no WebSocket:", err);
  }

  reconnect() {
    console.log(`Reconectando em ${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(`Atualização: ${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 });

Exemplos de Código

Cliente WebSocket em 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:
        # Aguarda a confirmação de conexão
        ack = await websocket.recv()
        print(f"Conectado: {ack}")

        # Assina posições de baleias
        await websocket.send(json.dumps({
            "type": "subscribe",
            "channel": "whale_positions",
            "symbols": ["BTCUSDT", "ETHUSDT"]
        }))

        # Escuta por atualizações
        while True:
            try:
                msg = await websocket.recv()
                data = json.loads(msg)

                if data["type"] == "ping":
                    # Responde ao ping
                    await websocket.send(json.dumps({
                        "type": "pong",
                        "id": data["id"]
                    }))
                elif data["type"] == "data":
                    print(f"Nova posição: {data['data']}")
            except websockets.exceptions.ConnectionClosed:
                print("Conexão fechada, reconectando...")
                await asyncio.sleep(1)

asyncio.run(stream_whale_positions())

Dicas de Desempenho

Filtre ao assinar: Use o objeto params para filtrar dados no lado do servidor (min_position_size, min_size_usd) em vez de filtrar em sua aplicação.

Assinaturas em lote: Assine vários símbolos em uma única mensagem em vez de uma assinatura por símbolo.

Cancele assinaturas não utilizadas: Quando você não precisar mais de um stream, cancele a assinatura para economizar largura de banda e reduzir o volume de mensagens.

Use compressão gzip: Ative a compressão de mensagens em seu cliente WebSocket para economizar largura de banda (redução de 20-40%).

Monitore a saúde da conexão: Acompanhe a latência de ping/pong e as reconexões automáticas para diagnosticar problemas de rede.

Bufferize mensagens durante a desconexão: Quando a conexão cair, enfileire sinais de estratégia e execute-os quando reconectar.

Comece a Transmitir Agora

Obtenha sua chave de API e comece a construir sistemas de negociação em tempo real. Streaming via WebSocket está disponível em todos os planos.

Obter Chave de API

Construa Sistemas de Negociação em Tempo Real

Acompanhe posições de baleias, taxas de funding e scores de confirmação de IA com latência inferior a um segundo.

Ver Planos