Trading programático con el SDK de Hyperliquid

• hyperliquid sdk

• hyperliquid programmatic trade

• hyperliquid python sdk

• hyperliquid api trading programático

• bot de perpetuos on-chain

El trading programático dejó de ser una herramienta exclusiva de instituciones. Hoy, cualquier trader minorista con bases de programación puede automatizar órdenes, consultar posiciones y construir sistemas de ejecución relativamente avanzados. Hyperliquid, como exchange de perpetuos on-chain, ofrece interfaces REST y WebSocket completas, además de SDK mantenidos por la comunidad y por el ecosistema para varios lenguajes.

Con unas cuantas líneas de código puedes enviar órdenes, revisar margen, consultar posiciones y manejar errores comunes. En esta guía veremos cómo preparar el entorno y usar SDKs en Python o JavaScript para construir un flujo de trading programático más confiable. También explicaremos por qué, si vas a operar con fondos reales, usar una billetera hardware OneKey como capa de firma puede ser una pieza clave para proteger tus llaves.

Por qué elegir Hyperliquid para trading programático

Frente a un exchange centralizado, Hyperliquid tiene varias ventajas relevantes para traders cuantitativos y desarrolladores:

• La liquidación ocurre on-chain, por lo que no necesitas custodiar tus fondos con un tercero de la misma forma que en un CEX.
• Usa una arquitectura híbrida: matching de órdenes off-chain y liquidación on-chain, buscando combinar velocidad con transparencia.
• Sus APIs son relativamente simples y la documentación se mantiene actualizada.
• La comunidad de desarrolladores es activa y suele compartir herramientas, wrappers y ejemplos.

Para un trader algorítmico, esto significa que puedes conservar mayor control sobre tus fondos mientras accedes a una experiencia de trading cercana a la de un exchange centralizado.

Preparación del entorno e instalación del SDK

Entorno Python

Al momento de escribir este artículo, el SDK de Python mantenido por la comunidad puede instalarse con pip. Lo recomendable es trabajar dentro de un entorno virtual para evitar conflictos de dependencias:

python -m venv hl_env
source hl_env/bin/activate
pip install hyperliquid-python-sdk

El código fuente del SDK puede encontrarse en repositorios del ecosistema, incluyendo repositorios de colaboración de OneKey y organizaciones oficiales o comunitarias de Hyperliquid. Revisa siempre la documentación oficial para obtener la dirección más reciente del repositorio.

Entorno JavaScript/TypeScript

Si prefieres trabajar con Node.js:

npm install @nktkas/hyperliquid

También puedes usar el paquete mantenido oficialmente, tomando como referencia la versión más reciente publicada en npm registry.

Si trabajas con TypeScript, puedes importar definiciones de tipos para tener autocompletado y una mejor experiencia en tu IDE.

Conectar la API e inicializar el cliente

Método de autenticación

Hyperliquid autentica las solicitudes de trading mediante firmas con llave privada. Cada orden debe firmarse con la llave de la wallet usando mensajes estructurados EIP-712, lo que ayuda a garantizar que la solicitud no pueda ser falsificada.

Ejemplo en Python, en forma de pseudocódigo:

import os
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from eth_account import Account

# Lee la llave privada desde variables de entorno. Nunca la hardcodees.
private_key = os.environ["HL_PRIVATE_KEY"]

account = Account.from_key(private_key)

info = Info(base_url="https://api.hyperliquid.xyz")
exchange = Exchange(account, base_url="https://api.hyperliquid.xyz")

Para producción, es muy recomendable reemplazar una llave privada en software por una billetera hardware OneKey. La llave privada nunca sale del chip seguro del dispositivo, por lo que incluso si el servidor queda comprometido, el atacante no debería poder exportar la llave. Más adelante veremos esta arquitectura con más detalle.

Consultar datos de mercado y estado de la cuenta

Obtener un snapshot del mercado

# Obtiene metadatos de todos los perpetuos y precios actuales
meta_and_asset_ctx = info.meta_and_asset_ctxs()

# La respuesta incluye campos como markPx, funding, entre otros

Consultar posiciones y balance

user_state = info.user_state(account.address)

# user_state contiene marginSummary y assetPositions
for pos in user_state["assetPositions"]:
    print(
        pos["position"]["coin"],
        pos["position"]["szi"]
    )

Aquí puedes revisar el resumen de margen, el tamaño de cada posición, el par operado y otros datos relevantes para tu lógica de riesgo.

Enviar órdenes

Orden de mercado

order_result = exchange.market_open(
    coin="BTC",
    is_buy=True,
    sz=0.001,       # tamaño de la orden
    slippage=0.01   # deslizamiento máximo permitido: 1%
)

print(order_result)

Orden límite

order_result = exchange.order(
    coin="ETH",
    is_buy=False,
    sz=0.1,
    limit_px=3200.0,
    order_type={"limit": {"tif": "Gtc"}}
)

El campo tif admite opciones como:

• Gtc: Good Till Cancel, la orden queda activa hasta que se ejecute o canceles.
• Ioc: Immediate Or Cancel, ejecuta lo disponible de inmediato y cancela el resto.
• Alo: Add Liquidity Only, solo publica como maker.

La elección depende de tu estrategia: scalping, market making, grid trading o ejecución direccional.

Órdenes en lote

Estrategias como market making o grids suelen requerir enviar varias órdenes al mismo tiempo. El SDK permite usar interfaces de batch para reducir viajes de red:

orders = [
    {
        "coin": "BTC",
        "is_buy": True,
        "sz": 0.001,
        "limit_px": 60000,
        "order_type": {"limit": {"tif": "Gtc"}}
    },
    {
        "coin": "BTC",
        "is_buy": False,
        "sz": 0.001,
        "limit_px": 61000,
        "order_type": {"limit": {"tif": "Gtc"}}
    },
]

result = exchange.bulk_orders(orders)

Cancelar y modificar órdenes

# Para cancelar necesitas coin y oid, el ID de la orden
cancel_result = exchange.cancel(coin="BTC", oid=123456789)

# Modificar una orden suele equivaler a cancel + replace
modify_result = exchange.modify_order(
    oid=123456789,
    coin="BTC",
    is_buy=True,
    sz=0.002,
    limit_px=59500,
    order_type={"limit": {"tif": "Gtc"}}
)

Buenas prácticas para manejo de errores

En trading programático, el manejo de errores es tan importante como la lógica de la estrategia. Entre los errores comunes están:

• Fallas temporales de red.
• Timeouts de API.
• Respuestas de rate limit.
• Rechazos por margen insuficiente.
• Parámetros inválidos de orden.
• Diferencias entre el estado local del bot y el estado real de la cuenta.

Un patrón básico es aplicar reintentos con backoff exponencial:

import time


def place_with_retry(exchange, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return exchange.order(**kwargs)
        except Exception as e:
            if attempt == max_retries - 1:
                raise

            wait = 2 ** attempt  # 1s, 2s, 4s...
            time.sleep(wait)

En producción, conviene distinguir entre errores reintentables y errores definitivos. Por ejemplo, un timeout puede reintentarse, pero una orden rechazada por falta de margen no debería enviarse indefinidamente.

Escuchar fills en tiempo real con WebSocket

El polling por REST puede ser suficiente para estrategias de baja frecuencia. Para escenarios más sensibles a latencia, es mejor usar WebSocket:

from hyperliquid.websocket_manager import WebsocketManager


def on_fill(data):
    print("Callback de fill:", data)


ws = WebsocketManager(base_url="wss://api.hyperliquid.xyz")

ws.subscribe(
    {"type": "userFills", "user": account.address},
    callback=on_fill
)

ws.start()

Consulta la documentación oficial de Hyperliquid para ver el formato completo de suscripciones WebSocket, eventos disponibles y campos de respuesta.

Proteger un bot en producción con una billetera hardware OneKey

Una wallet de software o hot wallet guarda la llave privada en memoria, disco o variables de entorno. Si el servidor donde corre el bot es comprometido, los fondos podrían quedar expuestos rápidamente.

Para un bot que administra capital real, una arquitectura más prudente es:

1. Conectar una billetera hardware OneKey a un servidor de firma.
2. Hacer que la lógica del bot genere el mensaje de transacción u orden que debe firmarse.
3. Enviar el mensaje a OneKey para que la firma ocurra dentro del elemento seguro del hardware.
4. Devolver la firma al bot.
5. Enviar la orden firmada a Hyperliquid.

Con este diseño, la llave privada permanece siempre dentro del hardware y no puede exportarse desde la capa de software. Además, el estándar de firmas estructuradas EIP-712 permite que OneKey muestre información legible de lo que se va a firmar, para que puedas revisar manualmente las operaciones cuando sea necesario.

También es recomendable usar una wallet de API Agent dedicada para el bot, si tu configuración de Hyperliquid lo permite. De esta manera, puedes limitar el alcance operativo de la automatización y reducir la exposición de riesgo.

OneKey Perps como flujo práctico para operar perpetuos

Si todavía no quieres escribir código, o si prefieres validar tu idea de trading manualmente antes de automatizarla, OneKey Perps puede ser un punto de partida más directo. Desde la app de OneKey puedes acceder a una experiencia de trading de perpetuos con una interfaz clara, manteniendo un enfoque de autocustodia y seguridad de llaves.

Un flujo razonable sería:

1. Usar OneKey Perps para familiarizarte con el mercado, el margen, el funding y la mecánica de órdenes.
2. Definir reglas simples de entrada, salida y riesgo.
3. Probar esas reglas manualmente con tamaños pequeños.
4. Solo después, convertirlas en lógica programática usando el SDK de Hyperliquid.
5. Si pasas a producción, separar la lógica del bot de la capa de firma y usar OneKey como protección de llaves.

Este enfoque evita saltar demasiado rápido a un bot con capital real sin entender primero cómo se comportan las posiciones de perpetuos en condiciones de mercado cambiantes.

Herramientas y recursos útiles

• Documentación oficial de Hyperliquid: especificaciones de API, campos, límites y ejemplos.
• Sitio oficial de OneKey: información sobre billeteras hardware y productos de autocustodia.
• Documentación de WalletConnect: útil si necesitas conectar firmas mediante el protocolo WalletConnect.
• Repositorios del SDK: revisa siempre que estés usando paquetes actualizados y fuentes confiables.

Preguntas frecuentes

Q1: ¿Cuál es la diferencia entre usar el SDK y llamar directamente la REST API?

El SDK encapsula la lógica de firma, el formato de las solicitudes y parte del manejo común de errores, lo que reduce código repetitivo. Llamar directamente la REST API te da más flexibilidad, pero tendrás que implementar por tu cuenta la firma EIP-712 y el formateo exacto de cada request.

Si estás empezando, suele ser mejor usar el SDK. Cuando conozcas bien el flujo, puedes bajar a llamadas HTTP nativas si tu sistema lo necesita.

Q2: ¿El trading programático en Hyperliquid requiere KYC?

Hyperliquid es un protocolo descentralizado y, al momento de esta guía, se puede operar con una dirección de wallet sin pasar por KYC. Aun así, debes revisar las reglas y regulaciones aplicables en tu país o región. La responsabilidad de cumplimiento recae en cada usuario.

Q3: ¿Cómo puedo evitar que el bot pierda demasiado en condiciones extremas?

No existe una forma de eliminar el riesgo, pero sí puedes reducirlo con controles claros:

• Definir una pérdida máxima diaria o por sesión y pausar el bot al alcanzarla.
• Monitorear la relación entre pérdidas no realizadas y equity de la cuenta.
• Usar órdenes de stop loss cuando correspondan.
• Validar periódicamente que la posición real coincida con la posición esperada por el bot.
• Limitar el apalancamiento y el tamaño máximo por operación.
• Tener alertas externas si el bot deja de recibir datos o empieza a rechazar órdenes.

Q4: ¿Cómo se integra una billetera hardware OneKey con scripts automatizados?

Puedes usar SDKs o interfaces oficiales de OneKey para invocar firmas desde el hardware. También puedes combinar una conexión por USB o Bluetooth con métodos compatibles de firma, como eth_sign, según el flujo técnico disponible.

En despliegues de producción, lo más limpio suele ser separar el servicio de firma del motor de trading. Así reduces la superficie de ataque y evitas que el bot tenga acceso directo a material sensible.

Q5: ¿Las órdenes en lote tienen límites de frecuencia?

Sí, debes revisar la documentación oficial para conocer la política de rate limits más reciente. Como regla práctica, conviene agregar pausas razonables entre solicitudes e implementar un mecanismo como token bucket o sliding window para controlar la frecuencia. Esto ayuda a evitar rechazos por exceso de requests.

Conclusión: de un script funcional a un sistema de producción

El SDK de Hyperliquid reduce mucho la barrera de entrada para hacer trading programático on-chain. Pero pasar de “un script que corre” a “un sistema confiable” exige trabajar con cuidado en tres áreas: seguridad de firma, manejo de errores y gestión de riesgo.

Si quieres probar perpetuos on-chain sin escribir código desde el primer día, descarga o abre OneKey y prueba OneKey Perps como una forma práctica de operar con una interfaz clara y un enfoque de autocustodia. Si ya tienes un equipo técnico y quieres automatizar, integrar OneKey como backend de firma puede ayudarte a proteger mejor las llaves privadas del bot.

Riesgo: el trading programático implica riesgos técnicos y de mercado. Los perpetuos usan apalancamiento y pueden generar pérdidas significativas, incluso superiores al capital inicial en ciertos escenarios. Este contenido es solo una referencia técnica y no constituye asesoría financiera, legal ni de inversión. Opera únicamente si entiendes los riesgos y de acuerdo con tu propia tolerancia al riesgo. El rendimiento pasado no garantiza resultados futuros.