Suscripción al order book en tiempo real de Hyperliquid

6 may 2026

  • hyperliquid orderbook websocket

  • real time hyperliquid api

  • order book en tiempo real de Hyperliquid

  • suscripción websocket de Hyperliquid

  • hyperliquid l2 book

El order book es una de las estructuras de datos más importantes de cualquier exchange: muestra en tiempo real la distribución de precios y tamaños de las órdenes límite de compra y venta que aún no se han ejecutado. Para bots de trading cuantitativo, sistemas de arbitraje y paneles de análisis de mercado, recibir el estado del libro con latencia de milisegundos puede marcar la diferencia entre una estrategia útil y una que llega tarde.

Hyperliquid ofrece una interfaz WebSocket completa para recibir snapshots y actualizaciones incrementales del order book L2 en tiempo real. En esta guía verás cómo suscribirte, cómo interpretar los mensajes, cómo mantener un libro local y qué detalles de ingeniería conviene cuidar en producción, como reconexión y control de estado. Si no quieres construir tu propia infraestructura, OneKey Perps ya integra visualización de mercado en tiempo real y una experiencia lista para operar.

WebSocket vs. polling con REST

Antes de entrar en la parte técnica, vale la pena entender por qué WebSocket suele ser la opción correcta frente a consultar una REST API de forma repetida.

Para casos donde necesitas un order book en tiempo real, hacer polling con REST rara vez es suficiente: aumenta la latencia, consume más recursos y puede perder cambios entre una consulta y otra. WebSocket mantiene una conexión abierta y permite recibir datos apenas el servidor los emite. Para detalles exactos de límites, formatos y parámetros, consulta la documentación oficial de Hyperliquid.

Establecer la conexión WebSocket

Endpoint

El endpoint WebSocket de Hyperliquid, sujeto siempre a la documentación oficial vigente, es:

wss://api.hyperliquid.xyz/ws

Código base de conexión

import asyncio
import json
import websockets

WS_URL = "wss://api.hyperliquid.xyz/ws"

async def connect_and_subscribe():
    async with websockets.connect(WS_URL) as ws:
        # Enviar mensaje de suscripción
        subscribe_msg = {
            "method": "subscribe",
            "subscription": {
                "type": "l2Book",
                "coin": "BTC"
            }
        }

        await ws.send(json.dumps(subscribe_msg))

        # Recibir mensajes continuamente
        async for raw_msg in ws:
            msg = json.loads(raw_msg)
            handle_message(msg)

asyncio.run(connect_and_subscribe())

Formato del mensaje de suscripción

Suscripción al order book L2

Para suscribirte al libro L2 de BTC:

{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "BTC"
  }
}

Hyperliquid permite suscribirse a varios pares desde una misma conexión. Solo necesitas enviar un mensaje de suscripción por cada mercado; cada uno recibirá sus propias actualizaciones.

Cancelar una suscripción

{
  "method": "unsubscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "BTC"
  }
}

Tipos de mensaje: snapshot y actualizaciones incrementales

Snapshot inicial

Después de suscribirte, el servidor envía primero un snapshot completo del order book, con los niveles de precio y el tamaño agregado disponible en ese momento:

{
  "channel": "l2Book",
  "data": {
    "coin": "BTC",
    "time": 1714500000000,
    "levels": [
      [
        [{"px": "64000.0", "sz": "0.5", "n": 3}],
        [{"px": "64010.0", "sz": "0.3", "n": 2}]
      ]
    ]
  }
}
  • px: precio.
  • sz: tamaño total en ese nivel de precio. Si es 0, ese nivel quedó vacío.
  • n: número de órdenes en ese nivel.

En el ejemplo, los bids —compras— vienen ordenados de mayor a menor precio, mientras que los asks —ventas— vienen de menor a mayor.

Actualización incremental o delta

Después del snapshot, el servidor envía solo los niveles que cambiaron:

{
  "channel": "l2Book",
  "data": {
    "coin": "BTC",
    "time": 1714500000100,
    "levels": [
      [
        [{"px": "63990.0", "sz": "0.0", "n": 0}],
        [{"px": "64010.0", "sz": "0.8", "n": 4}]
      ]
    ]
  }
}

Cuando sz es "0", "0.0" o 0, significa que todas las órdenes de ese nivel fueron ejecutadas o canceladas, por lo que debes eliminar ese precio del libro local.

Mantener un order book local

Mantener correctamente el estado local del libro es el punto crítico al trabajar con datos WebSocket:

from sortedcontainers import SortedDict

class LocalOrderBook:
    def __init__(self, coin):
        self.coin = coin
        self.bids = SortedDict(lambda x: -float(x))  # Compras: precio de mayor a menor
        self.asks = SortedDict(lambda x: float(x))   # Ventas: precio de menor a mayor
        self.last_time = None

    def apply_snapshot(self, data):
        self.bids.clear()
        self.asks.clear()

        levels = data["levels"][0]

        for bid in levels[0]:
            if float(bid["sz"]) > 0:
                self.bids[bid["px"]] = float(bid["sz"])

        for ask in levels[1]:
            if float(ask["sz"]) > 0:
                self.asks[ask["px"]] = float(ask["sz"])

        self.last_time = data["time"]

    def apply_delta(self, data):
        levels = data["levels"][0]

        for bid in levels[0]:
            px, sz = bid["px"], float(bid["sz"])
            if sz == 0:
                self.bids.pop(px, None)
            else:
                self.bids[px] = sz

        for ask in levels[1]:
            px, sz = ask["px"], float(ask["sz"])
            if sz == 0:
                self.asks.pop(px, None)
            else:
                self.asks[px] = sz

        self.last_time = data["time"]

    @property
    def best_bid(self):
        return next(iter(self.bids.items()), None)

    @property
    def best_ask(self):
        return next(iter(self.asks.items()), None)

    @property
    def mid_price(self):
        bid = self.best_bid
        ask = self.best_ask
        if bid and ask:
            return (float(bid[0]) + float(ask[0])) / 2
        return None

    @property
    def spread(self):
        bid = self.best_bid
        ask = self.best_ask
        if bid and ask:
            return float(ask[0]) - float(bid[0])
        return None

Lógica de procesamiento de mensajes

La lógica básica consiste en aplicar el primer mensaje como snapshot y los siguientes como deltas:

order_book = LocalOrderBook("BTC")
is_initialized = False

def handle_message(msg):
    global is_initialized

    if msg.get("channel") != "l2Book":
        return

    data = msg["data"]

    if not is_initialized:
        order_book.apply_snapshot(data)
        is_initialized = True
        print(
            f"Order book inicializado: "
            f"{len(order_book.bids)} niveles de compra, "
            f"{len(order_book.asks)} niveles de venta"
        )
    else:
        order_book.apply_delta(data)

    # Imprimir información del mejor bid/ask
    print(
        f"Best bid: {order_book.best_bid}, "
        f"best ask: {order_book.best_ask}, "
        f"spread: {order_book.spread}"
    )

Manejo de desconexiones y reconexión

Una conexión WebSocket puede cortarse por inestabilidad de red, reinicios del servidor o timeouts. Un sistema de producción debe reconectarse automáticamente:

import asyncio
import json
import websockets

async def subscribe_with_reconnect(coin, handle_fn, max_retries=None):
    retries = 0

    while max_retries is None or retries < max_retries:
        try:
            async with websockets.connect(
                WS_URL,
                ping_interval=20,
                ping_timeout=10
            ) as ws:
                retries = 0  # Conexión exitosa: reiniciar contador

                await ws.send(json.dumps({
                    "method": "subscribe",
                    "subscription": {"type": "l2Book", "coin": coin}
                }))

                async for raw_msg in ws:
                    handle_fn(json.loads(raw_msg))

        except (websockets.ConnectionClosed, ConnectionError, OSError) as e:
            retries += 1
            wait = min(2 ** retries, 60)  # Backoff exponencial, máximo 60 segundos
            print(f"Conexión cerrada ({e}). Reintentando en {wait}s, intento {retries}")

            # Al reconectar, el servidor enviará un nuevo snapshot completo.
            # Reinicia el estado en tu lógica de manejo.
            await asyncio.sleep(wait)

Al reconectar, debes reiniciar el flag is_initialized, porque el servidor volverá a enviar un snapshot completo. No asumas que recibirás deltas desde el punto exacto donde se cortó la conexión.

Timestamps y orden de mensajes

Los mensajes WebSocket de Hyperliquid incluyen un campo de tiempo que puedes usar para detectar mensajes fuera de orden. En sistemas de producción conviene:

  • Guardar el timestamp del último mensaje procesado.
  • Descartar mensajes cuyo timestamp sea anterior al último ya aplicado.
  • Si no recibes mensajes durante un periodo anormalmente largo, enviar ping o reconectar.
  • Para estrategias muy sensibles a la latencia, considerar infraestructura con menor distancia geográfica o conectividad más estable.

Suscripción concurrente a varios mercados

Una sola conexión WebSocket puede suscribirse a varios pares. Lo habitual es usar una arquitectura asíncrona para administrar los libros locales:

coins = ["BTC", "ETH", "SOL"]
order_books = {coin: LocalOrderBook(coin) for coin in coins}
initialized = {coin: False for coin in coins}

async def multi_subscribe():
    async with websockets.connect(WS_URL) as ws:
        for coin in coins:
            await ws.send(json.dumps({
                "method": "subscribe",
                "subscription": {"type": "l2Book", "coin": coin}
            }))

        async for raw_msg in ws:
            msg = json.loads(raw_msg)

            if msg.get("channel") != "l2Book":
                continue

            data = msg["data"]
            coin = data["coin"]

            if coin not in order_books:
                continue

            if not initialized[coin]:
                order_books[coin].apply_snapshot(data)
                initialized[coin] = True
            else:
                order_books[coin].apply_delta(data)

Casos de uso del order book en tiempo real

Los datos de libro L2 se usan en distintos flujos de trading y análisis:

  • Bots de trading: ajustar dinámicamente precios de órdenes límite según spread, profundidad y presión de compra/venta.
  • Sistemas de arbitraje: monitorear diferencias de precio entre Hyperliquid y otros venues, como dYdX o GMX.
  • Dashboards de mercado: visualizar profundidad, historial de spread y distribución de liquidez.
  • Sistemas de riesgo: disparar alertas cuando el spread se amplía de forma anormal o la liquidez cae de golpe.

OneKey Perps: operar sin construir infraestructura propia

Construir y mantener un sistema WebSocket para order book requiere tiempo, monitoreo y disciplina operativa. Si tu objetivo principal es operar perpetuos y no desarrollar infraestructura cuantitativa, OneKey Perps ofrece una forma más directa de acceder a mercados con visualización en tiempo real y funciones de trading integradas.

Además, OneKey combina esa experiencia con firma segura desde hardware wallet, lo que ayuda a separar mejor la custodia de tus fondos de la ejecución diaria. Para usuarios que conectan aplicaciones descentralizadas mediante WalletConnect, OneKey soporta el protocolo estándar y puede interactuar con aplicaciones Web3 como Hyperliquid de forma segura.

Si quieres una alternativa práctica, descarga o abre OneKey, revisa OneKey Perps y prueba el flujo con montos pequeños antes de aumentar exposición. La idea no es prometer resultados, sino reducir fricción operativa y mejorar la seguridad del proceso.

Preguntas frecuentes

Q1: ¿Hay límites de concurrencia para conexiones WebSocket?

Sí puede haber límites, y debes revisarlos en la documentación oficial de Hyperliquid. En general, evita abrir demasiadas conexiones desde una misma IP. Para múltiples mercados, suele ser mejor reutilizar una sola conexión y enviar varias suscripciones.

Q2: Si pierdo una actualización incremental, ¿mi order book queda mal?

Sí. Si se pierde un delta por problemas de red, tu libro local puede dejar de coincidir con el estado real del servidor. La práctica recomendada es cerrar la conexión y volver a suscribirte cuando sospeches inconsistencia, por ejemplo si ves spreads anómalos, saltos bruscos del best bid/ask o largos periodos sin mensajes.

Q3: ¿Los datos de order book en tiempo real sirven para backtesting?

No directamente. El backtesting requiere datos históricos, no solo un stream en vivo. Si quieres usar L2 para investigación, debes guardar los datos tick por tick con timestamp y luego procesarlos. También puedes combinar ese trabajo con APIs históricas de velas de Hyperliquid para pruebas iniciales menos granulares.

Q4: ¿Cómo sé si mi conexión WebSocket está saludable?

Monitorea al menos estos puntos: tiempo desde el último mensaje recibido, latencia de ping/pong, reconexiones recientes y gaps anormales en timestamps. Si el último mensaje supera un umbral definido —por ejemplo, 5 segundos, según tu estrategia— activa una reconexión controlada.

Q5: ¿OneKey Wallet aumenta la latencia de trading?

La firma con hardware wallet suele completarse en cientos de milisegundos, algo aceptable para la mayoría de usuarios y muchas estrategias no ultra frecuentes. Para estrategias de muy alta frecuencia, como decenas de órdenes por segundo, puede tener sentido separar funciones: usar una hot wallet o API Agent para firmas frecuentes y mantener la gestión principal de fondos protegida con OneKey.

Conclusión

La suscripción al order book en tiempo real es una fuente de datos clave para sistemas de trading cuantitativo, arbitraje y análisis de liquidez. La API WebSocket de Hyperliquid tiene un diseño claro y permite construir un libro local confiable si manejas bien snapshots, deltas, reconexión y validación de estado.

Si lo que buscas es operar perpetuos sin encargarte de la infraestructura técnica, OneKey Perps es un flujo práctico para empezar: mercado en tiempo real, experiencia de trading integrada y firma segura con OneKey. Úsalo con criterio, prueba primero con bajo riesgo y mantén siempre una gestión de exposición conservadora.

Aviso de riesgo: los datos de order book reflejan solo el estado del mercado en un momento específico y no deben ser la única base para tomar decisiones. Las estrategias automatizadas basadas en order book pueden sufrir pérdidas importantes por volatilidad, fallas técnicas o errores de diseño. El trading de perpetuos es de alto riesgo y puede causar la pérdida total del capital. Este contenido es solo una referencia técnica y no constituye asesoría financiera, legal ni de inversión.

Asegura tu viaje cripto con OneKey

View details for Comprar OneKeyComprar OneKey

Comprar OneKey

La cartera de hardware más avanzada del mundo.

View details for Descargar aplicaciónDescargar aplicación

Descargar aplicación

Alertas de estafa. Todas las monedas soportadas.

View details for OneKey SifuOneKey Sifu

OneKey Sifu

Claridad cripto — a una llamada de distancia.