API WebSocket de Hyperliquid: guía 2026 de suscripciones, heartbeats y post requests

En resumen: conéctate a wss://api.hyperliquid.xyz/ws, manda {"method":"subscribe","subscription":{...}} por cada feed y lee los mensajes según su campo channel. Envía {"method":"ping"} si un feed puede quedarse en silencio, porque el servidor cierra cualquier conexión a la que no haya enviado nada en 60 segundos. Los feeds de usuario como userFills empiezan con un snapshot marcado isSnapshot: true. Además, puedes mandar peticiones info y acciones firmadas por el mismo socket con {"method":"post"}.

Hacer polling por REST vale para un panel que se refresca cada minuto. Si quieres el libro de órdenes en vivo, los trades al momento o el flujo de fills de una wallet, la API WebSocket de Hyperliquid es la herramienta correcta: una conexión, muchos feeds y sin peso por petición. Esta guía explica el formato de los mensajes, los feeds más útiles, lo que medimos en mainnet el 20 de octubre de 2026 y un script de Python listo para ejecutar. Si solo necesitas ver el PnL y las posiciones de una wallet, no te hace falta nada de esto: Hyperfolio ya lo hace en modo solo lectura.

Endpoints y formato de los mensajes

• Mainnet: wss://api.hyperliquid.xyz/ws
• Testnet: wss://api.hyperliquid-testnet.xyz/ws (mira nuestra guía de la testnet de Hyperliquid)

Todo va en frames de texto JSON. Hay cuatro métodos de cliente:

Método	Ejemplo	Respuesta del servidor
subscribe	{"method":"subscribe","subscription":{"type":"trades","coin":"BTC"}}	channel: "subscriptionResponse" y después datos en channel: "trades"
unsubscribe	El mismo objeto de la suscripción original	El feed se detiene
ping	{"method":"ping"}	{"channel":"pong"}
post	{"method":"post","id":1,"request":{"type":"info","payload":{...}}}	channel: "post" con el mismo id

El acuse de recibo devuelve tu suscripción con los valores por defecto ya rellenos. Al suscribirnos a l2Book de BTC, llegó como {"type":"l2Book","coin":"BTC","nSigFigs":null,"mantissa":null,"fast":false}. Úsalo para confirmar que el servidor entendió exactamente lo que pediste.

Las suscripciones que conviene conocer

La documentación oficial recoge más de 20 tipos de feed. Estos cubren casi todo el trabajo de trading, análisis y seguimiento:

Feed	Suscripción	Qué recibes
allMids	{"type":"allMids"} (opcional dex)	Precios medios de todos los mercados. Los de spot solo vienen con el primer perp dex.
trades	{"type":"trades","coin":"BTC"}	Arrays de trades con precio, tamaño, lado, hora, tid y users: [comprador, vendedor]
l2Book	{"type":"l2Book","coin":"BTC"} (opcionales nSigFigs, mantissa, fast)	Snapshots del libro: 20 niveles por lado, o 5 con fast: true
bbo	{"type":"bbo","coin":"BTC"}	Mejor bid y ask, solo cuando cambian en un bloque
candle	{"type":"candle","coin":"BTC","interval":"1m"}	La vela en curso. Intervalos de 1m a 1M.
activeAssetCtx	{"type":"activeAssetCtx","coin":"BTC"}	Funding, open interest, precio mark, oráculo y medio, volumen de 24 h
userFills	{"type":"userFills","user":"0x…"} (opcional aggregateByTime)	Snapshot de fills recientes y luego cada fill nuevo
orderUpdates	{"type":"orderUpdates","user":"0x…"}	Cambios de estado de las órdenes de esa cuenta
userEvents	{"type":"userEvents","user":"0x…"}	Fills, funding, liquidaciones y cancelaciones no hechas por el usuario. Llega en channel: "user".
userFundings	{"type":"userFundings","user":"0x…"}	Pagos de funding cada hora
clearinghouseState	{"type":"clearinghouseState","user":"0x…"}	Resumen de margen y posiciones abiertas

Hay dos detalles que pillan a mucha gente. Primero, los mensajes de userEvents llegan en channel: "user", no en "userEvents", así que un router que use el tipo de suscripción como clave se los pierde. Segundo, los feeds de usuario necesitan la dirección real de la cuenta (principal o subcuenta). La documentación avisa de que usar la dirección de una API wallet (agent wallet) devuelve un resultado vacío.

Lo que medimos en mainnet

Ejecutamos el script de abajo contra mainnet el 20 de octubre de 2026, sobre las 07:10 UTC. Son observaciones de ventanas cortas de 15 a 30 segundos, no garantías: la cadencia depende de la actividad del mercado.

Feed	Observado
l2Book BTC (por defecto)	20 niveles por lado, un envío cada 4,5 a 5 segundos aproximadamente
l2Book BTC con fast: true	5 niveles por lado, un envío cada 0,55 segundos aproximadamente
bbo BTC	204 mensajes en 30 segundos (unos 7 por segundo)
trades BTC	Un lote cada 0,85 segundos aproximadamente, 75 trades en 20 segundos
activeAssetCtx BTC	Una actualización por segundo aproximadamente. Muestra: mark 81.800, oráculo 81.820, funding 0,0000125 por hora, open interest 39.965 BTC
allMids	Cada 5 segundos aproximadamente, 1.355 claves, de ellas 472 pares spot escritos como @índice
userFills	Primer mensaje con isSnapshot: true y 30 fills; después, mensajes en streaming sin el campo isSnapshot

La conclusión: si necesitas el mejor precio rápido, usa bbo o l2Book con fast: true. El libro por defecto de 20 niveles sirve para gráficos de profundidad, pero es lento para cualquier cosa sensible a la latencia. Fíjate también en que los mensajes de fills en streaming simplemente omiten isSnapshot, así que comprueba data.get("isSnapshot") en vez de compararlo con false.

Snapshots, reconexiones y datos perdidos

Hyperliquid dice claramente que las desconexiones pueden ocurrir de forma periódica y sin aviso, y que todo cliente automatizado debe reconectarse. La buena noticia es que casi nunca pierdes datos:

1. Al volver a suscribirte, los feeds de series temporales como userFills y userFundings mandan primero un snapshot (isSnapshot: true). Deduplica contra lo que ya guardaste, por ejemplo con (coin, tid) para los fills.
2. En trades, la documentación indica que tid es un hash de 50 bits de los IDs de orden de comprador y vendedor. Para un ID de trade único global, usa (block_time, coin, tid).
3. Si el snapshot no llega lo bastante atrás, rellena con la petición REST info equivalente, como userFillsByTime. Nuestra guía de datos históricos de Hyperliquid explica los límites de paginación.

Un patrón simple y robusto es un bucle que reconecta con backoff exponencial (1 s, 2 s, 4 s, con un tope de unos 30 s), vuelve a suscribir todo desde una lista y trata el primer snapshot tras cada reconexión como una fusión, no como un reemplazo.

Heartbeats: la regla de los 60 segundos

El servidor cierra la conexión si no te ha enviado nada en 60 segundos. Un feed con mucho movimiento como bbo nunca llega a ese límite, pero un socket suscrito solo a userFills de una wallet tranquila sí. Envía {"method":"ping"} más o menos cada 50 segundos y espera {"channel":"pong"}. Comprobamos el pong en mainnet. La documentación especifica este mensaje JSON, así que mándalo en lugar de fiarte del ping a nivel de protocolo de tu librería.

Post requests por el WebSocket

Puedes enviar por el socket los mismos payloads que por la API REST. Envuélvelos así:

{"method": "post", "id": 1,
 "request": {"type": "info",
             "payload": {"type": "clearinghouseState", "user": "0x..."}}}

La respuesta llega en channel: "post" con el mismo id, y response.type vale info, action o error. Las acciones firmadas usan "type": "action" con los habituales action, nonce y signature. El id es obligatorio, así que dale uno único a cada petición para emparejar las respuestas. Las peticiones explorer no están soportadas. En nuestra prueba, un post de clearinghouseState para la dirección del vault HLP devolvió un valor de cuenta de unos 39,0 M$ por el mismo socket que estaba recibiendo datos de mercado.

Límites que hay que tener en cuenta

El WebSocket tiene sus propios topes, aparte del peso REST: 10 conexiones, 30 conexiones nuevas por minuto, 1.000 suscripciones, 10 usuarios únicos en los feeds de usuario, 2.000 mensajes enviados por minuto y 100 post requests en vuelo. El tope de 10 usuarios es el que importa para seguir wallets: desde una IP no puedes recibir los fills de 50 wallets. Nuestra guía de rate limits de Hyperliquid tiene el desglose completo y ejemplos de polling.

Ejemplo en Python: datos de mercado y fills de una wallet

Solo necesita pip install websockets y ninguna clave, porque todos estos datos son públicos. Cambia WALLET por la dirección que quieras vigilar.

import asyncio, json, time, collections
import websockets  # pip install websockets

WS_URL = "wss://api.hyperliquid.xyz/ws"
WALLET = "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"  # any public address (here: the HLP vault)

SUBS = [
    {"type": "allMids"},
    {"type": "trades", "coin": "BTC"},
    {"type": "bbo", "coin": "BTC"},
    {"type": "l2Book", "coin": "BTC"},
    {"type": "candle", "coin": "BTC", "interval": "1m"},
    {"type": "userFills", "user": WALLET, "aggregateByTime": True},
]

async def heartbeat(ws):
    while True:                      # server drops sockets silent for 60 s
        await asyncio.sleep(50)
        await ws.send(json.dumps({"method": "ping"}))

async def run(seconds=30):
    counts = collections.Counter()
    async with websockets.connect(WS_URL, max_size=None) as ws:
        for s in SUBS:
            await ws.send(json.dumps({"method": "subscribe", "subscription": s}))
        # one-off info request over the same socket
        await ws.send(json.dumps({"method": "post", "id": 1,
            "request": {"type": "info", "payload": {"type": "clearinghouseState", "user": WALLET}}}))
        hb = asyncio.create_task(heartbeat(ws))
        end = time.time() + seconds
        while time.time() < end:
            msg = json.loads(await asyncio.wait_for(ws.recv(), timeout=60))
            ch, data = msg["channel"], msg.get("data")
            counts[ch] += 1
            if ch == "userFills" and data.get("isSnapshot"):
                print("userFills snapshot:", len(data["fills"]), "fills")
            elif ch == "bbo" and counts[ch] == 1:
                bid, ask = data["bbo"]
                print("BTC bbo:", bid["px"], "/", ask["px"])
            elif ch == "post":
                st = data["response"]["payload"]["data"]
                print("account value:", st["marginSummary"]["accountValue"])
        hb.cancel()
    print(dict(counts))

if __name__ == "__main__":
    asyncio.run(run())

En nuestra ejecución imprimió el mejor bid y ask de BTC (81.803 / 81.805), el snapshot de fills, el valor de cuenta de la post request y un recuento de mensajes por canal. Para producción, mete run() en un bucle de reconexión con backoff y escribe los mensajes en una cola en vez de imprimirlos.

Cuándo no necesitas el WebSocket

Montar tu propio stream tiene sentido para bots, market making e investigación. Si lo que quieres es saber cómo va una wallet, es mucha fontanería: reconexiones, deduplicado, el tope de 10 usuarios, y la contabilidad de funding y comisiones. Hyperfolio es una PWA (app web instalable) gratuita y de solo lectura que sigue wallets de Hyperliquid con PnL, posiciones, funding y vistas de Smart Money y Markets, sin API keys ni firmas. Mira cómo funciona el seguimiento sin API keys y cómo seguir varias wallets a la vez.

Preguntas frecuentes

¿Cuál es la URL del WebSocket de Hyperliquid?

wss://api.hyperliquid.xyz/ws en mainnet y wss://api.hyperliquid-testnet.xyz/ws en testnet.

¿Necesito una API key para usar el WebSocket de Hyperliquid?

No. Los feeds de mercado y de usuario son públicos y no requieren autenticación. Solo firmas cuando envías acciones (órdenes, cancelaciones) mediante una post request.

¿Por qué se desconecta mi WebSocket de Hyperliquid al minuto?

El servidor cierra las conexiones a las que no ha enviado nada en 60 segundos. Envía {"method":"ping"} con regularidad en las suscripciones tranquilas.

¿Por qué no me llegan los mensajes de userEvents?

Llegan en channel: "user". Revisa también que usas la dirección de la cuenta y no la de una agent wallet.

¿Qué velocidad tiene el feed l2Book de Hyperliquid?

En nuestra prueba, el libro de BTC por defecto (20 niveles) se actualizó cada 4,5 a 5 segundos aproximadamente, y con fast: true (5 niveles) cada 0,55 segundos. Para el mejor precio, bbo mandó unos 7 mensajes por segundo.

¿Puedo enviar órdenes por el WebSocket?

Sí. Manda la acción firmada dentro de {"method":"post","request":{"type":"action",...}}. La respuesta replica la del endpoint REST de exchange.

¿Quieres el resultado sin la fontanería? Pega una wallet en Hyperfolio y mira el PnL y las posiciones en vivo, sin API keys. ¿Operas en Hyperliquid? Usa el código HYPERFOLIO para un 4% de descuento en comisiones (cómo funciona el referido).