Suscripciones WebSocket de Hyperliquid: Ciclo de Vida de la Conexión, Feeds y Reconexión

Respuesta Directa: Lo que Necesitas Saber sobre los WebSockets de Hyperliquid

La API WebSocket de Hyperliquid es la única forma de recibir datos de mercado en tiempo real y actualizaciones específicas del usuario. A diferencia de los endpoints REST que requieren sondeo, los WebSockets envían datos a medida que ocurren, lo que los hace esenciales para bots de trading, paneles de control y cualquier aplicación que necesite datos de baja latencia. La API admite varios feeds distintos: l2Book, trades, candles, allMids, activeAssetCtxs, activeAssetCtx, userEvents y orderUpdates. Cada feed tiene un formato de mensaje de suscripción específico, y el ciclo de vida de la conexión está gobernado por un mecanismo de heartbeat que cierra las conexiones inactivas después de aproximadamente 30 segundos.

Para comenzar, te conectas a wss://api.hyperliquid.xyz/ws (mainnet) o wss://api.hyperliquid-testnet.xyz/ws (testnet), envías un mensaje de suscripción y luego escuchas los datos entrantes. También debes responder a los frames de ping para mantener la conexión activa. Esta guía cubre el ciclo de vida completo, desde la conexión inicial hasta la reconexión después de caídas inesperadas, con ejemplos de código ejecutables en Python y Node.js.

• Los datos en tiempo real solo están disponibles a través de WebSocket; los endpoints REST proporcionan solo instantáneas.
• Límites de conexión: una conexión de información y una conexión de usuario por IP.
• Heartbeat: el servidor envía frames de ping; si no se recibe un pong dentro de ~30 segundos, la conexión se cierra.

Entendiendo la Arquitectura WebSocket de Hyperliquid

La API WebSocket de Hyperliquid está separada de su API REST. Los endpoints REST (/info y /exchange) se utilizan para obtener datos históricos, realizar pedidos y consultar el estado de la cuenta. Los WebSockets se utilizan exclusivamente para la transmisión en tiempo real. Esta separación significa que para datos en vivo, debes usar WebSockets; el sondeo REST no es un sustituto.

El endpoint WebSocket es wss://api.hyperliquid.xyz/ws. La API admite dos tipos de conexiones: una conexión de 'información' para datos de mercado y una conexión de 'usuario' para eventos específicos del usuario. Puedes tener como máximo una de cada una por dirección IP. Este límite es importante para aplicaciones que necesitan suscribirse tanto a datos de mercado como a eventos de usuario simultáneamente.

El protocolo utiliza mensajes JSON. Para suscribirte, envías un mensaje con un campo method establecido en "subscribe" y un objeto subscription que especifica el feed y sus parámetros. Por ejemplo, para suscribirte al feed allMids, envías: {"method":"subscribe","subscription":{"type":"allMids"}}. Para cancelar la suscripción, envías un mensaje similar con method establecido en "unsubscribe".

El servidor envía datos como mensajes JSON. Cada mensaje tiene un campo channel que indica el tipo de feed y un campo data que contiene la carga útil. Por ejemplo, un mensaje de trade podría verse así: {"channel":"trades","data":[{"coin":"BTC","px":"50000","sz":"0.1","side":"B","time":1620000000000}]}.

• Conexión de información: para feeds de datos de mercado (l2Book, trades, candles, allMids, activeAssetCtxs).
• Conexión de usuario: para userEvents y orderUpdates.
• Los mensajes de suscripción deben incluir la cadena de canal exacta; de lo contrario, el servidor los ignora.

Feeds WebSocket Disponibles y Formatos de Suscripción

Hyperliquid ofrece varios feeds, cada uno con un formato de suscripción específico. Estos son los más comunes:

l2Book: Proporciona el libro de órdenes para una moneda específica. Suscríbete con {"type":"l2Book","coin":"BTC"}. Los datos incluyen ofertas y demandas con niveles y tamaños.

trades: Transmite operaciones individuales para una moneda. Suscríbete con {"type":"trades","coin":"BTC"}. Cada operación incluye precio, tamaño, lado y marca de tiempo.

candles: Proporciona datos de velas para una moneda e intervalo. Suscríbete con {"type":"candles","coin":"BTC","interval":"1m"}. Los datos incluyen valores OHLCV.

allMids: Transmite el precio medio para todas las monedas. Suscríbete con {"type":"allMids"}. Los datos son un mapa de moneda a precio medio.

activeAssetCtxs: Proporciona contexto para todos los activos activos, incluidos funding, interés abierto y precio de marca. Suscríbete con {"type":"activeAssetCtxs"}.

activeAssetCtx: Proporciona contexto para un activo específico. Suscríbete con {"type":"activeAssetCtx","coin":"BTC"}.

userEvents: Transmite eventos específicos del usuario como fills y pagos de funding. Suscríbete con {"type":"userEvents","user":"0x..."}.

orderUpdates: Transmite actualizaciones de estado de órdenes para un usuario. Suscríbete con {"type":"orderUpdates","user":"0x..."}.

• Todos los mensajes de suscripción deben incluir el campo type.
• Para feeds específicos de moneda, el campo coin es obligatorio.
• Para candles, el campo interval es obligatorio (por ejemplo, '1m', '5m', '1h').

Contrato de Heartbeat y Timeout

El servidor WebSocket de Hyperliquid envía un frame de ping cada 30 segundos para mantener la conexión activa. Si el cliente no responde con un frame de pong dentro de ese tiempo, el servidor cierra la conexión. Este es un mecanismo de heartbeat estándar de WebSocket, pero es crucial manejarlo correctamente en el código de tu cliente.

En la mayoría de las bibliotecas WebSocket, el ping/pong se maneja automáticamente. Sin embargo, si estás usando una biblioteca de bajo nivel, es posible que debas implementarlo manualmente. Por ejemplo, en la biblioteca websockets de Python, los parámetros ping_interval y ping_timeout controlan este comportamiento. En la biblioteca ws de Node.js, puedes escuchar el evento 'ping' y enviar un pong.

El timeout documentado es de aproximadamente 30 segundos. Si tu cliente no responde a un ping dentro de esa ventana, la conexión se terminará. Esta es una causa común de problemas de 'connection error getting candles', como se ve en informes de la comunidad.

• El servidor envía un ping cada 30 segundos.
• El cliente debe responder con un pong dentro de 30 segundos.
• Si no lo hace, el servidor cierra la conexión con un cierre anormal 1006.

Límites de Conexión y Límites de Tasa

Hyperliquid impone un límite de una conexión de información y una conexión de usuario por dirección IP. Esto significa que no puedes abrir múltiples conexiones WebSocket al mismo endpoint desde la misma IP. Si necesitas suscribirte a múltiples feeds, puedes hacerlo en una sola conexión enviando múltiples mensajes de suscripción.

Además, hay límites de tasa en la API REST, pero las conexiones WebSocket no están sujetas a los mismos límites de tasa. Sin embargo, enviar demasiados mensajes de suscripción en un corto período de tiempo podría provocar una desconexión. Es mejor suscribirse a todos los feeds necesarios inmediatamente después de conectarse.

Para más detalles sobre los límites de tasa, consulta nuestra guía de límites de tasa de Hyperliquid.

• Una conexión de información por IP.
• Una conexión de usuario por IP.
• Exceder estos límites resulta en el rechazo de la conexión.

Ejemplo de Cliente Python Ejecutable

A continuación se muestra un cliente Python completo que se suscribe a allMids y l2Book para BTC, maneja los pings automáticamente e incluye una estrategia de reconexión simple. Utiliza la biblioteca websockets, que maneja ping/pong automáticamente por defecto.

El cliente se conecta al WebSocket, envía mensajes de suscripción y luego escucha los mensajes. Si la conexión se cae, intenta reconectarse con backoff exponencial y se vuelve a suscribir a los mismos feeds.

import asyncio
import json
import websockets

async def subscribe(ws, subscription):
    await ws.send(json.dumps({"method": "subscribe", "subscription": subscription}))

async def main():
    uri = "wss://api.hyperliquid.xyz/ws"
    subscriptions = [
        {"type": "allMids"},
        {"type": "l2Book", "coin": "BTC"}
    ]
    while True:
        try:
            async with websockets.connect(uri, ping_interval=20, ping_timeout=20) as ws:
                for sub in subscriptions:
                    await subscribe(ws, sub)
                print("Subscribed to allMids and l2Book")
                async for message in ws:
                    data = json.loads(message)
                    print(f"Received: {data['channel']} - {data['data']}")
        except websockets.exceptions.ConnectionClosed as e:
            print(f"Connection closed: {e}. Reconnecting in 5 seconds...")
            await asyncio.sleep(5)
        except Exception as e:
            print(f"Error: {e}. Reconnecting in 5 seconds...")
            await asyncio.sleep(5)

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

Ejemplo de Cliente Node.js Ejecutable

Aquí tienes un cliente Node.js equivalente que utiliza la biblioteca ws. Maneja ping/pong manualmente escuchando el evento 'ping' y enviando un pong. También incluye una estrategia de reconexión con un retraso fijo.

El cliente se suscribe a allMids y l2Book para BTC, y registra todos los mensajes entrantes.

const WebSocket = require('ws');

const ws = new WebSocket('wss://api.hyperliquid.xyz/ws');

function subscribe(ws, subscription) {
  ws.send(JSON.stringify({ method: 'subscribe', subscription }));
}

ws.on('open', () => {
  console.log('Connected');
  subscribe(ws, { type: 'allMids' });
  subscribe(ws, { type: 'l2Book', coin: 'BTC' });
});

ws.on('ping', () => {
  ws.pong();
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  console.log(`Received: ${msg.channel} - ${JSON.stringify(msg.data)}`);
});

ws.on('close', () => {
  console.log('Connection closed. Reconnecting in 5 seconds...');
  setTimeout(() => {
    // Reconnect logic: create a new WebSocket and repeat subscriptions
    const newWs = new WebSocket('wss://api.hyperliquid.xyz/ws');
    // ... (repeat the same event handlers)
  }, 5000);
});

ws.on('error', (err) => {
  console.error('WebSocket error:', err);
});

Resultados Esperados y Cómo Verificarlos

Cuando ejecutes el cliente Python o Node.js, deberías ver un flujo de mensajes. Para allMids, recibirás mensajes como {"channel":"allMids","data":{"BTC":"50000.0","ETH":"3000.0"}}. Para l2Book, verás actualizaciones del libro de órdenes con ofertas y demandas.

Para verificar que tu suscripción está funcionando, comprueba que recibes mensajes para cada feed suscrito. También puedes usar la documentación de la API de Hyperliquid para ver ejemplos de cargas útiles.

Si no recibes ningún mensaje, revisa el formato de tu mensaje de suscripción y asegúrate de estar conectado al endpoint correcto. Además, verifica que tu cliente esté respondiendo a los pings.

• Deberías recibir un mensaje para cada feed suscrito en unos pocos segundos.
• El campo channel en el mensaje indica el tipo de feed.
• Si no ves mensajes, revisa el formato de tu suscripción y la conectividad de red.

Fallos Comunes y Solución de Problemas

Un problema común es el error 'connection error getting candles', a menudo reportado por usuarios de bots de trading como Hummingbot. Esto ocurre típicamente cuando la conexión WebSocket se cae debido a un heartbeat perdido o un problema de red. Para solucionarlo, asegúrate de que tu cliente maneje los pings correctamente e implemente una estrategia de reconexión.

Otro problema es exceder el límite de conexión. Si intentas abrir más de una conexión de información desde la misma IP, el servidor rechazará la nueva conexión. Asegúrate de que tu aplicación use una sola conexión para todas las suscripciones de datos de mercado.

Si estás usando un proxy o un balanceador de carga, asegúrate de que la conexión WebSocket no se termine prematuramente. Algunos proxies tienen timeouts de inactividad más cortos que el intervalo de heartbeat de 30 segundos de Hyperliquid.

Para una lista completa de soluciones para desconexiones WebSocket, consulta nuestra guía de soluciones genéricas para desconexiones WebSocket RPC.

• Comprueba que tu cliente responda a los pings dentro de 30 segundos.
• Verifica que no estés excediendo el límite de una conexión por IP.
• Asegúrate de que tu red permita conexiones WebSocket y no tenga timeouts de inactividad agresivos.

Compensaciones y Limitaciones

La API WebSocket de Hyperliquid es potente pero tiene algunas limitaciones. El límite de una conexión por IP puede ser restrictivo para aplicaciones que necesitan suscribirse a muchos feeds desde un solo servidor. Sin embargo, puedes suscribirte a múltiples feeds en una sola conexión, por lo que esto rara vez es un problema.

El mecanismo de heartbeat requiere que los clientes sean receptivos. Si tu aplicación está ocupada procesando datos, podría perder un ping y ser desconectada. Para mitigar esto, usa un hilo o proceso separado para la conexión WebSocket, o usa una biblioteca que maneje los pings automáticamente.

Otra limitación es que la API WebSocket no proporciona datos históricos. Para datos históricos, debes usar el endpoint REST /info. Esto significa que necesitas combinar ambas APIs para una solución completa.

Finalmente, la API WebSocket no está documentada públicamente en detalle más allá de los documentos oficiales. Algunos feeds pueden cambiar sin previo aviso, por lo que es importante monitorear la documentación oficial para actualizaciones.

• Una conexión por IP para feeds de información y usuario.
• No hay datos históricos a través de WebSocket; usa REST para eso.
• El heartbeat requiere respuestas pong oportunas.

Próximos Pasos y Recursos Adicionales

Ahora que entiendes la API WebSocket de Hyperliquid, puedes construir aplicaciones en tiempo real. Para comenzar, intenta modificar los ejemplos de clientes para suscribirte a diferentes feeds o para manejar eventos de usuario.

Para casos de uso más avanzados, considera usar un proveedor de infraestructura gestionada como OnFinality. Nuestra página de red de Hyperliquid proporciona endpoints WebSocket confiables con reconexión automática y balanceo de carga. También puedes usar nuestro Asistente RPC para encontrar los mejores endpoints para tus necesidades.

Si estás construyendo un bot de trading, también necesitarás entender la API REST para realizar pedidos. Consulta nuestro servicio de API para acceso gestionado a la API. Y no olvides revisar nuestros precios para elegir un plan que se ajuste a tu uso.

Para más contenido educativo, visita nuestro centro de aprendizaje para guías sobre mejores prácticas de WebSocket, límites de tasa y más.

• Experimenta con diferentes feeds y formatos de suscripción.
• Usa los endpoints WebSocket gestionados de OnFinality para confiabilidad en producción.
• Explora nuestras otras guías sobre Hyperliquid y mejores prácticas de WebSocket.