Flujo WebSocket en tiempo real para desarrolladores

Los canales y el plan

Cada canal pertenece a una familia de datos de mercado, la misma que por REST y MCP: trades.futures, trades.spot, orderbook.spot y orderbook.futures son de microestructura, liquidations de derivados. Una familia que falta en tu plan falta en todos los canales, incluido el flujo. En concreto: Free no tiene el flujo en absoluto (403 en el handshake), y todo el flujo está abierto a partir de Traders. El tiempo real no es la familia de ticks brutos, abierta a partir del plan Financial, que designa el historial tick a tick servido por REST.

Un canal fuera del plan recibe {"op": "error", "server_time": "…", "error": {"code": "plan_family", "message": "Channel 'orderbook.futures.BTCUSDT' is not in your plan: the 'microstructure' data family is not included in your subscription.", "param": "channels"}} y, como en cualquier suscripción, no se aplica ningún canal de la trama. El número de conexiones simultáneas por cuenta también depende del plan: 3 en Traders, 10 en Financial, 20 en Startup. Ver los precios.

Operaciones

{
  "channel": "trades.futures.BTCUSDT",
  "server_time": "2026-10-14T09:25:26.408Z",
  "data": [
    { "time": "2026-10-14T09:25:26.176Z", "id": "3cf0988ca613980c", "side": "buy", "price": 83283.9, "quantity": 0.24, "value_usd": 19988.136 },
    { "time": "2026-10-14T09:25:26.184Z", "id": "4b408a64af719aa6", "side": "sell", "price": 83268.6, "quantity": 0.002, "value_usd": 166.5372 }
  ],
  "seq": 443379
}

side es el lado del taker: buy significa que un comprador consumió la oferta. Una fila es una ejecución: una orden taker que barre varias órdenes maker del mismo tamaño al mismo precio produce varias filas idénticas, y es normal. Las operaciones se agrupan por tick, pero no se pierde ninguna: cada una conserva su marca de tiempo original en data[].time, distinta del server_time del mensaje, y las operaciones de un mensaje van ordenadas por esa marca de tiempo, de la más antigua a la más reciente. Ese orden vale solo dentro de un mensaje: un mensaje posterior puede traer una operación más antigua que la más reciente ya recibida (un mercado que la reporta con retraso, normalmente de menos de un segundo, a veces hasta unos 1,5 s). Para construir velas, agrupa por data[].time y cierra un periodo unos dos segundos después de su fin.

Cada operación lleva id, el mismo identificador que el tick de /v1/trades/futures o /v1/trades/spot para esa operación (una huella opaca: no indica ni el mercado ni su identificador nativo), y value_usd = price × quantity. Usa id para eliminar duplicados entre el flujo en directo y el historial REST.

Liquidaciones

{
  "channel": "liquidations.BTCUSDT",
  "server_time": "2026-10-10T09:11:51.652Z",
  "data": [
    { "time": "2026-10-10T09:11:51.576Z", "price": 83168.0, "quantity": 0.081, "side": "short", "value_usd": 6736.608 }
  ],
  "seq": 7
}

side es aquí el lado de la posición liquidada: long significa que se liquidó una posición larga. No todos los mercados usan esta convención; la normalización se hace por ti. Como con las operaciones, las liquidaciones de un mensaje van ordenadas por time. Un mercado puede reportar una liquidación con unos segundos de retraso: filtra y agrupa por time, nunca por el momento de recepción. Una liquidación antigua que un mercado vuelve a publicar más de 60 s después de su time no se retransmite (/v1/liquidations/events conserva todos los eventos).

Libro de órdenes

{
  "channel": "orderbook.futures.BTCUSDT",
  "server_time": "2026-10-14T09:25:26.304Z",
  "data": {
    "bids": [[83271.0, 67.65684], [83270.0, 4.85424], [83269.0, 15.31266]],
    "asks": [[83272.0, 17.0135], [83273.0, 11.33315], [83274.0, 5.34624]],
    "avg_mid_price": 83271.75,
    "avg_spread_bps": 0.036
  },
  "seq": 627302
}

Cada fila es [precio, cantidad], siendo la cantidad la suma de los mercados en ese nivel de precio. Los bids son decrecientes, los asks crecientes. Los precios se llevan a una rejilla común por activo; sin ella, cada mercado caería en sus propios niveles y el libro consolidado tendría más filas, cada una más fina.

El paso de esa cuadrícula, en la moneda de cotización: BTC 1; ETH, BNB, TAO, ZEC, BCH 0.1; SOL, HYPE, XMR, LTC, QNT, AAVE, ETC, VVV, DASH, BSV 0.01; LINK, UNI, GRAM, AVAX, NEAR, DOT, MORPHO, ICP, RENDER, ATOM, FIL, INJ, LIT, ZRO, CAKE, TRUMP, PENDLE, LDO 0.001; XRP, TRX, SUI, XLM, ADA, USDCUSDT, USDTUSDC, ENA, ONDO, WLD, ASTER, WLFI, ARB, ALGO, POL, JUP, AERO, APT, STX, TIA, CRV, FET, VIRTUAL, GRASS, XPL, SPX, XTZ 0.0001; DOGE, HBAR, CC, SKY, JST, KAS, STABLE, AKE, NIGHT, PYTH, STRK, SEI, FF 0.00001; PUMP, VET, PENGU 0.000001.

Hay un libro por mercado: orderbook.spot solo fusiona los libros spot, orderbook.futures solo los libros perpetuos. Los dos nunca se mezclan, porque sus precios difieren en la base. Dentro de un mismo tipo de mercado, una plataforma cuyo precio medio se aleja más de 5 puntos básicos de la mediana de las demás (cuando hay al menos tres) queda fuera de la fusión hasta que vuelve a la normalidad: una plataforma aislada no puede deformar el libro consolidado.

El libro consolidado es una profundidad, no el libro de una plataforma

Entre varias plataformas de un mismo tipo de mercado no hay un motor de emparejamiento común: sus precios medios difieren en unos pocos puntos básicos, mientras que el diferencial compra/venta de una plataforma en BTC es de unos 0,1 puntos básicos. Sumados a su precio bruto, sus niveles cruzaban el libro consolidado en casi todos los mensajes.

Desde el 08/10/2026, cada plataforma se recentra en avg_mid_price antes de la fusión: todos sus niveles se desplazan en avg_mid_price menos su propio precio medio. Las cantidades no cambian, la distancia de cada nivel al precio medio de su plataforma se conserva, y el libro consolidado nunca está cruzado: bids[0][0] siempre está por debajo de asks[0][0]. Una plataforma que en ese momento solo tiene un lado de su libro no contribuye.

El número de operaciones no mide la actividad

Algunos mercados fraccionan sus ejecuciones al extremo, hasta órdenes de un satoshi, una fracción de céntimo. En el flujo consolidado, el número de operaciones está por tanto dominado por ejecuciones diminutas. Para medir la actividad, suma quantity o quantity × price; nunca cuentes las filas.

Un salto en seq significa que has perdido mensajes

La cola de envío de cada cliente está limitada a 512 tramas, unos ocho ticks a plena carga (800 ms de sacudida absorbible). Un cliente que no consume lo bastante rápido ve descartados sus mensajes más antiguos; se degrada solo, sin afectar a los demás.

En los canales de eventos, un mensaje descartado se pierde definitivamente; el salto en seq es lo que te lo indica. En el libro de órdenes solo se guarda el último estado: un salto allí no tiene consecuencias, el siguiente estado sustituye por completo al anterior.

La credencial se comprueba en el handshake, no en una trama

La clave (o el token) se comprueba en el handshake, antes de que se abra la conexión: un plan que no incluye el flujo recibe un 403 y no se establece nada. Desde un servidor viaja en la cabecera X-API-KEY; un navegador, que no puede poner cabeceras en un WebSocket, usa un token de corta duración en la URL (?token=), para que la clave nunca salga de tu servidor.

La trama {"op": "auth"} se sigue aceptando y responde authenticated, pero ya no es necesaria: la sesión se abre ya autenticada. ?token= y ?api_key= solo se aceptan en el handshake de WebSocket, nunca en las rutas REST, y la pasarela no registra la línea de petición de /ws.

El número de conexiones simultáneas depende del plan

Cada plan limita el número de conexiones abiertas a la vez, para toda la cuenta, sumando todas las claves. La conexión que sobra se cierra de inmediato con el código 4003 y el límite en el motivo. No la confundas con un 503 en el handshake, que indica que el propio servicio está lleno, sea cual sea el plan.

Una desconexión libera su plaza al instante: no hay nada que esperar ni que reiniciar.

El flujo nunca nombra un mercado

Ningún mensaje dice de qué mercado procede una operación, una liquidación o un nivel del libro, ni cuántos mercados lo alimentaron: el flujo sirve el mercado consolidado. Un mercado en silencio durante más de diez segundos sale automáticamente del libro, y un mercado con el libro vacío nunca se fusiona en él.