Hyperliquid REST vs WebSocket: cuándo usar cada uno

Muchos desarrolladores que integran la API de Hyperliquid se hacen la misma pregunta: ¿mi estrategia debería usar REST o WebSocket? Aunque ambos sirven para conectarte con Hyperliquid, funcionan de forma muy distinta y están pensados para casos de uso diferentes. Elegir mal puede significar desde gastar ancho de banda innecesariamente hasta reaccionar tarde al mercado y terminar con más slippage del esperado.

En esta guía vamos a comparar REST y WebSocket en Hyperliquid: cómo funcionan, cuándo conviene usar cada uno, qué latencia puedes esperar y cuáles son los errores comunes que deberías evitar. También veremos cómo encaja OneKey, especialmente OneKey Perps, dentro de un flujo de trading más seguro y práctico.

REST API: modelo de solicitud y respuesta

REST, abreviatura de Representational State Transfer, es el modelo clásico de API sobre HTTP: el cliente envía una solicitud, el servidor responde y la interacción termina. Es un esquema de “pregunta y respuesta”.

En Hyperliquid, los endpoints REST se dividen principalmente en dos grupos:

• Info endpoint (/info): maneja consultas de solo lectura, como metadatos de mercado, trades históricos, snapshots de posiciones o información de la cuenta. Estas consultas no requieren firma y pueden ser llamadas por cualquier cliente.
• Exchange endpoint (/exchange): maneja operaciones de escritura, como enviar órdenes, cancelar órdenes, modificar apalancamiento o ajustar margen. Estas solicitudes requieren una firma estructurada EIP-712. El servidor valida que la firma corresponda a la dirección de la cuenta antes de ejecutar la acción.

Cuándo usar REST

REST es ideal para consultas puntuales. Por ejemplo:

• Obtener el estado actual de tus posiciones al iniciar una estrategia.
• Revisar periódicamente el balance de una cuenta.
• Consultar el historial de funding de un contrato específico.
• Descargar datos históricos para backtesting.

En todos estos casos no necesitas una conexión permanente. Haces una solicitud, recibes una respuesta y sigues con el flujo de tu estrategia.

REST también es obligatorio para enviar y cancelar órdenes. Aunque uses WebSocket para recibir datos en tiempo real, las instrucciones de trading se envían a través del endpoint Exchange por REST. Esa parte no se reemplaza con WebSocket.

Para descargas grandes de datos históricos, REST también suele ser suficiente. Puedes paginar llamadas al endpoint Info para obtener trades, velas o snapshots, siempre respetando los límites de tasa.

Limitaciones de REST

La principal limitación de REST es que funciona en modo “pull”: tú tienes que preguntar. Si no preguntas, no recibes nuevos datos.

Esto crea un problema para estrategias sensibles al tiempo. Si consultas el libro de órdenes cada 100 ms, podrías chocar con límites de tasa o gastar recursos innecesarios. Si consultas una vez por segundo, en un mercado rápido quizá tu estrategia llegue tarde.

Para estrategias que necesitan reaccionar a cambios del mercado en tiempo real, hacer polling constante con REST suele ser ineficiente y poco confiable.

WebSocket: conexión persistente y datos en tiempo real

WebSocket es un protocolo full-duplex. Una vez establecida la conexión, el servidor puede enviarte datos de forma continua sin que tengas que estar haciendo solicitudes repetidas.

El endpoint WebSocket de Hyperliquid es:

wss://api.hyperliquid.xyz/ws

Después de conectarte, el cliente envía mensajes de suscripción indicando qué datos quiere recibir. A partir de ahí, el servidor envía actualizaciones hasta que la conexión se cierre o el cliente cancele la suscripción.

Cuándo usar WebSocket

WebSocket es la opción natural para datos en tiempo real.

Un caso típico es monitorear el libro de órdenes. Al suscribirte al canal l2Book, recibes actualizaciones cuando cambia la profundidad del mercado. Esto permite que una estrategia detecte cambios de liquidez con mucha más rapidez que usando REST.

El canal trades sirve para seguir el flujo de ejecuciones en tiempo real. Es útil para leer ritmo de mercado, presión compradora o vendedora y posibles impactos de órdenes grandes.

El canal userEvents permite recibir eventos de cuenta, como fills, actualizaciones relevantes o notificaciones importantes. Esto evita tener que consultar constantemente el estado de la cuenta vía REST.

Para estrategias de arbitraje o de funding, WebSocket también puede ser útil porque permite reaccionar cuando cambian datos relevantes, en vez de esperar al siguiente ciclo de polling.

Riesgos y cuidados al usar WebSocket

La estabilidad de la conexión es el principal desafío. Una conexión WebSocket puede cortarse por problemas de red, reinicios del servidor, timeouts o periodos de inactividad.

En producción deberías implementar:

• Heartbeats con ping/pong.
• Reconexión automática.
• Re-suscripción a todos los canales después de reconectar.
• Lógica para reconstruir el estado si perdiste mensajes durante la desconexión.

También debes cuidar la presión de procesamiento. Algunos canales, como libros de órdenes de contratos muy líquidos, pueden generar muchos mensajes por segundo. Si tu cliente no procesa los mensajes lo suficientemente rápido, la cola se acumula y tus datos dejan de ser realmente “en tiempo real”.

Comparación rápida: REST vs WebSocket

Ejemplos de código

Consulta REST de un snapshot del libro de órdenes en Python:

import requests

response = requests.post(
    "https://api.hyperliquid.xyz/info",
    json={"type": "l2Book", "coin": "ETH"}
)

book = response.json()

# Obtienes el snapshot del libro de órdenes en ese momento.
# No se actualiza automáticamente.

Suscripción WebSocket a actualizaciones del libro de órdenes en Python:

import asyncio
import websockets
import json

async def stream_orderbook():
    uri = "wss://api.hyperliquid.xyz/ws"

    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "l2Book", "coin": "ETH"}
        }))

        # Recibes mensajes continuamente mientras cambia el libro.
        async for message in ws:
            data = json.loads(message)
            print(data)

asyncio.run(stream_orderbook())

La diferencia es clara: REST devuelve un snapshot y termina; WebSocket mantiene la conexión abierta y entrega actualizaciones hasta que se interrumpe.

Firmas para órdenes e integración con OneKey

Cuando una solicitud implica una operación de escritura, como enviar una orden o modificar parámetros de trading, necesitas una firma EIP-712. La seguridad de esa clave de firma define buena parte del riesgo operativo de la cuenta.

OneKey Wallet ofrece aislamiento de firmas a nivel de hardware: la clave privada se mantiene dentro del dispositivo y las firmas se realizan internamente. El código que corre en tu computadora no accede a la clave privada en texto plano.

Para traders cuantitativos, esto reduce un riesgo importante: si el entorno donde corre la estrategia tiene una vulnerabilidad, un atacante no debería poder extraer directamente la clave privada desde el código.

Un flujo posible es:

1. La estrategia construye el payload de la orden.
2. Envía la solicitud de firma al dispositivo OneKey mediante WalletConnect.
3. El usuario revisa y confirma en la pantalla del dispositivo.
4. La firma vuelve al código de la estrategia.
5. La estrategia envía la orden al endpoint /exchange de Hyperliquid.

Este flujo agrega confirmación manual, por lo que suele encajar mejor con estrategias de baja o media frecuencia. Para estrategias de alta frecuencia totalmente automatizadas, conviene evaluar una arquitectura con hot wallets dedicadas y límites operativos claros, separadas de la cuenta principal.

OneKey también ofrece OneKey Perps como una forma práctica de acceder a trading de perpetuos con una experiencia más directa, manteniendo una separación más clara entre gestión de wallet, firma y ejecución. Si quieres operar Hyperliquid sin construir toda la infraestructura desde cero, puedes descargar OneKey y probar OneKey Perps con montos prudentes, entendiendo siempre los riesgos del apalancamiento.

Arquitectura híbrida: la práctica más común

En producción, REST y WebSocket no compiten: se complementan.

Una arquitectura típica para una estrategia sobre Hyperliquid podría ser:

• WebSocket para suscribirse a datos en tiempo real, como l2Book, trades y userEvents.
• REST para enviar órdenes, cancelar órdenes y modificar parámetros de trading.
• REST al inicio para cargar estado inicial de cuenta, balances y posiciones.
• REST periódicamente para reconciliar el estado completo y detectar posibles desajustes causados por desconexiones de WebSocket.

Este enfoque aprovecha lo mejor de ambos modelos: WebSocket para reaccionar rápido y REST para acciones puntuales, inicialización y verificación.

FAQ

1. Si mi estrategia solo envía órdenes programadas, ¿necesito WebSocket?

No necesariamente. Si tu estrategia ejecuta órdenes en horarios o condiciones simples, puedes resolverlo con REST: consultas precio y estado de cuenta cuando toca, construyes la orden y la envías al endpoint Exchange.

WebSocket en este caso puede ser una carga extra si no necesitas reaccionar a cambios de mercado en tiempo real.

2. Si WebSocket se desconecta, ¿cómo sé qué datos me perdí?

Es un problema clásico. Lo más común es que, al reconectar, uses REST para descargar el estado completo actual, como un snapshot del libro de órdenes o tus posiciones. Ese snapshot se convierte en tu nuevo punto de referencia.

Para datos históricos, como trades, puedes consultar el periodo de desconexión vía REST si necesitas rellenar el hueco.

3. ¿Cuánta latencia hay entre enviar una orden por REST y recibir el fill?

La respuesta REST normalmente confirma que la orden fue aceptada, pero el evento de ejecución puede llegar después mediante userEvents por WebSocket o al consultar nuevamente el estado de cuenta.

La latencia depende de la red, la carga del sistema y las condiciones del mercado. En condiciones normales suele ser baja, pero en momentos extremos puede aumentar.

4. ¿Cuántas conexiones WebSocket debería abrir?

Lo recomendable es concentrar las suscripciones de una misma cuenta en pocas conexiones. Abrir demasiadas conexiones puede aumentar la complejidad y acercarte a límites operativos.

Si tienes varias estrategias internas, puedes compartir una conexión WebSocket mediante un bus de mensajes interno. Así reduces conexiones externas y simplificas la lógica de reconexión.

5. ¿Qué debo considerar al probar WebSocket en Jupyter Notebook?

Jupyter puede tener conflictos con el event loop de asyncio. Ejecutar directamente asyncio.run() puede fallar.

Una opción es usar nest_asyncio y llamar nest_asyncio.apply() al inicio del notebook. Otra opción, más limpia para producción, es mover el código WebSocket a un script Python independiente.

Conclusión

REST y WebSocket no son rivales. Son herramientas distintas para necesidades distintas.

Una forma simple de recordarlo:

• Si necesitas datos “en ese momento”, usa REST.
• Si necesitas datos “en tiempo real”, usa WebSocket.
• Para operaciones de escritura, como enviar órdenes, usa REST.

Entender esta división es clave para diseñar una integración sólida con Hyperliquid. A partir de ahí, OneKey puede funcionar como una capa práctica de seguridad para firmas, y OneKey Perps puede ayudarte a operar perpetuos con un flujo más simple que construir toda la infraestructura por tu cuenta.

Si quieres probarlo, descarga OneKey, revisa cómo funciona OneKey Perps y empieza con una configuración conservadora antes de aumentar complejidad o tamaño de posición.

Descargo de responsabilidad

Este contenido es solo para fines educativos y técnicos. No constituye asesoría financiera, legal ni de inversión. Las estrategias automatizadas pueden fallar por bugs, problemas de red, errores de configuración o condiciones extremas de mercado. El trading de contratos perpetuos con apalancamiento implica un riesgo elevado y puede causar pérdidas significativas. Evalúa tu experiencia técnica y tolerancia al riesgo antes de operar.