Hyperliquid API para principiantes: guía 2026 para empezar

6 may 2026

hyperliquid api
hyperliquid api guide
tutorial de Hyperliquid API
API de trading on-chain

Si alguna vez pensaste en participar de forma programática en el trading de perpetuos on-chain, la API de Hyperliquid es una de las opciones dentro de los DEX que más se acerca a la experiencia de un exchange centralizado. Ofrece endpoints para consultar mercado, gestionar cuentas y enviar órdenes, además de WebSocket para datos en tiempo real. Con eso puedes cubrir desde estrategias cuantitativas simples hasta sistemas de market making más complejos.

Esta guía está pensada para desarrolladores que se acercan por primera vez a Hyperliquid API. Veremos su estructura, autenticación, ejemplos básicos y errores comunes. También hablaremos de seguridad operativa y de cuándo tiene más sentido usar un flujo práctico con OneKey Perps en vez de operar directamente desde código.

Qué puedes hacer con Hyperliquid API

Según la documentación oficial de Hyperliquid, la API se divide principalmente en tres categorías:

Info Endpoints: sirven para consultar datos de mercado, como snapshots del order book, trades recientes, historial de funding rates, posiciones de una cuenta y órdenes históricas. Estos endpoints no requieren firma y son públicos.

Exchange Endpoints: se usan para acciones de escritura, como colocar órdenes, cancelarlas, modificar apalancamiento o ajustar margen. Estos endpoints requieren firmar el cuerpo de la solicitud con una wallet, por lo que la seguridad es crítica.

WebSocket en tiempo real: permite suscribirte a cambios del libro de órdenes, flujo de trades, eventos de cuenta y otros datos en vivo. Es especialmente útil para estrategias que necesitan reaccionar con baja latencia.

URL base y estructura de la API

La URL base de la REST API de Hyperliquid es:

https://api.hyperliquid.xyz

Todas las solicitudes usan el método POST y el cuerpo va en formato JSON. Los endpoints de tipo Info se envían a /info, mientras que los de trading se envían a /exchange.

Los campos exactos pueden cambiar, así que siempre debes revisar la documentación oficial antes de usar la API en producción. Los ejemplos de esta guía son solo una introducción práctica.

Autenticación

Los endpoints de trading de Hyperliquid usan firmas EIP-712 con datos estructurados, no el modelo tradicional de API Key + Secret. Esto implica que:

necesitas una dirección compatible con Ethereum como identidad;
cada solicitud de trading debe firmarse con la clave privada correspondiente;
la firma demuestra que la solicitud fue autorizada por el titular de esa dirección, sin depender de una capa intermedia.

Este diseño puede ser más seguro que una API key tradicional porque no existe una clave API estática que pueda robarse y reutilizarse. Pero también eleva mucho la importancia de la gestión de claves privadas. Si una clave privada se filtra, un atacante podría construir firmas válidas y operar tu cuenta.

Aquí es donde OneKey aporta valor. Una hardware wallet OneKey mantiene la clave privada aislada dentro del dispositivo, y las firmas se realizan internamente sin exponer la clave al equipo ni a internet. Para traders cuantitativos o desarrolladores que necesitan operar con API, una práctica prudente es usar cuentas separadas o subcuentas dedicadas a trading, evitando mezclar el capital principal con la cuenta operativa.

Si no necesitas automatizar todo desde código, OneKey Perps puede ser un flujo más directo para operar perpetuos desde una interfaz preparada para trading, manteniendo una separación más clara entre gestión de wallet, ejecución y control de riesgo.

Ejemplo de consulta: Python + curl

Un buen punto de partida es consultar la metadata de todos los activos disponibles para trading.

Con curl:

curl -X POST https://api.hyperliquid.xyz/info \
-H "Content-Type: application/json" \
-d '{"type": "meta"}'

Con Python usando requests:

import requests
import json

url = "https://api.hyperliquid.xyz/info"
payload = {"type": "meta"}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(json.dumps(data, indent=2))

La respuesta incluye información básica de los contratos disponibles, como nombre del activo, apalancamiento máximo y tamaño mínimo de orden. Este tipo de consulta es pública y no requiere autenticación, por lo que es una buena forma de familiarizarte con la API.

Consultar posiciones de una cuenta

Consultar el estado de posiciones de una dirección también pertenece a los Info Endpoints. Solo necesitas indicar la wallet:

payload = {
    "type": "clearinghouseState",
    "user": "0xYOUR_WALLET_ADDRESS"
}

response = requests.post(url, json=payload, headers=headers)

La respuesta puede incluir balance de margen, posiciones por contrato, PnL no realizado y otros datos de cuenta. Ten en cuenta que esta información es pública en el contexto on-chain: cualquier persona puede consultar el estado de una dirección.

Suscripción en tiempo real con WebSocket

El endpoint WebSocket es:

wss://api.hyperliquid.xyz/ws

Una vez establecida la conexión, puedes enviar un mensaje de suscripción para empezar a recibir datos en tiempo real:

import asyncio
import websockets
import json

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

    async with websockets.connect(uri) as ws:
        sub_msg = {
            "method": "subscribe",
            "subscription": {
                "type": "l2Book",
                "coin": "BTC"
            }
        }

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

        while True:
            msg = await ws.recv()
            data = json.loads(msg)
            print(data)

asyncio.run(subscribe_orderbook())

Entre los tipos de datos que se pueden suscribir están el libro de órdenes L2 (l2Book), trades recientes (trades), eventos de usuario (userEvents, asociados a una dirección) y datos globales como funding rates.

Errores comunes al empezar

Formato incorrecto de la solicitud

Uno de los problemas más frecuentes viene de errores en el JSON. Hyperliquid API suele ser estricta con tipos y nombres de campos. Por ejemplo, enviar un número como string cuando se espera un entero puede hacer que la solicitud sea rechazada. A veces el mensaje de error no es tan obvio, así que conviene comparar cuidadosamente contra la documentación oficial.

Firmas EIP-712 mal construidas

La firma es otro punto delicado. EIP-712 incluye detalles como definición de tipos, dominio y estructura exacta del mensaje. Implementarlo manualmente puede generar errores difíciles de depurar.

En la práctica, suele ser mejor usar un SDK mantenido por la comunidad o por el equipo oficial de Hyperliquid, ya sea en Python o JavaScript. Esto reduce el riesgo de errores de firma y evita reinventar partes sensibles de la infraestructura.

Desfase de tiempo

Las solicitudes de trading normalmente incluyen timestamp y tienen una ventana de validez limitada. Si el reloj local está muy desfasado respecto al tiempo de red, la solicitud puede rechazarse por expirada. Para producción, sincroniza el servidor con una fuente confiable de tiempo.

Manejo de fallos de red

En un entorno real, las conexiones WebSocket pueden caerse y las solicitudes REST pueden fallar temporalmente. Tu bot o sistema de trading debe tener lógica de reconexión, reintentos controlados y manejo de errores. No asumas que una conexión abierta se mantendrá estable para siempre.

Límites de tasa

Hyperliquid aplica distintos límites de tasa según el tipo de endpoint. Los valores concretos deben revisarse en la documentación oficial actualizada. Como regla general, los endpoints de consulta suelen ser más permisivos, mientras que los endpoints de trading son más estrictos.

Si recibes un error 429, no conviene reintentar de inmediato en bucle. Lo más prudente es pausar las solicitudes y aplicar una estrategia de backoff exponencial para evitar empeorar el bloqueo o saturar el servicio.

Recomendaciones para el entorno de desarrollo

Antes de desplegar una estrategia con dinero real, considera lo siguiente:

Empieza con tamaño reducido. No lances una estrategia nueva directamente con capital grande. Hyperliquid no debe tratarse como un entorno libre de riesgo; las pruebas iniciales deben hacerse con exposición controlada.
Separa la clave de firma del capital principal. Usa una cuenta, subcuenta o dirección dedicada para API trading. Así limitas el daño potencial si tu código falla o si hay un problema operativo.
Usa una wallet segura para firmar. OneKey te ayuda a mantener la clave privada fuera del equipo conectado a internet. Esto es especialmente relevante si desarrollas o ejecutas herramientas que firman transacciones con frecuencia.
Considera OneKey Perps para la operación diaria. Si tu objetivo no es construir infraestructura de trading desde cero, OneKey Perps puede ser una alternativa más práctica para operar perpetuos y monitorear posiciones desde un flujo más directo, sin asumir toda la complejidad de una API propia.
Revisa órdenes y posiciones con frecuencia. Automatizar no significa desentenderse. Las estrategias pueden comportarse de forma inesperada ante liquidez baja, movimientos bruscos o cambios en la API.

El código abierto de OneKey en GitHub también puede servir como referencia para entender cómo integrar firmas de wallet de forma más segura a nivel de aplicación.

FAQ

Q1: ¿Necesito registrar una cuenta para usar Hyperliquid API?

No en el sentido tradicional. Necesitas una wallet compatible con Ethereum. Después de que esa dirección haya realizado las acciones necesarias en Hyperliquid, como fondear la cuenta, puede usarse con la API. No funciona como un exchange tradicional con email, contraseña y API key.

Q2: ¿Hay SDK de Python para Hyperliquid API?

Sí, existen SDKs en Python mantenidos por la comunidad y/o referencias oficiales. Lo más recomendable es revisar el GitHub oficial de Hyperliquid y elegir una versión activa y actualizada. Usar un SDK ayuda mucho con la construcción de firmas y el formato correcto de las solicitudes.

Q3: ¿Cómo reconecto un WebSocket si se corta?

Implementa detección de heartbeat, por ejemplo con ping, y lógica de reconexión automática. Si la conexión se cae, espera unos segundos antes de reconectar y vuelve a suscribirte a los canales necesarios. En producción, es preferible usar backoff exponencial para evitar enviar demasiadas solicitudes durante una interrupción del servicio.

Q4: ¿Cómo protejo los fondos al hacer trading por API?

La seguridad depende principalmente de cómo proteges la clave privada. Firmar con una hardware wallet OneKey ayuda a que la clave no se exponga al dispositivo conectado. Además, conviene usar una cuenta dedicada para API, limitar el tamaño de posiciones, revisar órdenes abiertas y no mantener más capital del necesario en la cuenta operativa.

Q5: ¿Hyperliquid API soporta órdenes condicionales y stop loss?

Hyperliquid soporta órdenes tipo trigger, incluyendo lógicas de stop loss y take profit. Los parámetros exactos deben revisarse en la documentación oficial, especialmente en la sección de tipos de orden. Para lógicas más complejas, también puedes implementarlas a nivel de estrategia monitoreando posiciones y mercado.

Conclusión

Hyperliquid API ofrece una base sólida para construir herramientas de datos, monitoreo y trading automatizado en un DEX de perpetuos. Los Info Endpoints son útiles para dashboards, análisis y seguimiento de mercado; los Exchange Endpoints, junto con WebSocket, permiten crear estrategias automatizadas más avanzadas.

Pero la parte técnica no debe separarse de la seguridad. Al usar firmas EIP-712, la gestión de claves privadas se vuelve una responsabilidad central. OneKey puede ayudarte a aislar claves y reducir riesgos operativos, mientras que OneKey Perps ofrece un flujo más práctico para quienes quieren operar perpetuos sin construir toda la infraestructura desde cero.

Si estás explorando Hyperliquid o el trading de perpetuos on-chain, puedes probar OneKey, descargar la app y usar OneKey Perps como punto de partida operativo. Hazlo con tamaño controlado, entiende los riesgos y evita delegar decisiones críticas a código que no hayas probado cuidadosamente.

---Aviso legal---

Este contenido es solo una referencia técnica y educativa. No constituye asesoría financiera, legal ni de inversión. El trading por API implica riesgos de automatización: errores de estrategia, fallos de código o problemas de conectividad pueden causar pérdidas significativas. Los perpetuos usan apalancamiento y son productos de alto riesgo. Evalúa cuidadosamente tu situación y comprende los riesgos antes de participar. El rendimiento pasado de cualquier estrategia no garantiza resultados futuros.