Construyendo un bot de trading en Hyperliquid: arquitectura, ejecución y controles de riesgo

Alcance y supuestos para un bot de trading en Hyperliquid

Esta guía cubre la ingeniería de un bot que opera futuros perpetuos y mercados spot de Hyperliquid a través de la API pública. Se asume que estás familiarizado con Python o JavaScript, que entiendes la mecánica de los futuros perpetuos (margen, financiamiento, liquidación) y que tienes una cuenta de Hyperliquid con acceso a la API. No recomienda una estrategia específica ni promete rentabilidad; la ejecución automatizada no elimina el riesgo de mercado.

Hyperliquid es un exchange descentralizado con un libro de órdenes on-chain y una API REST/WebSocket. Un bot normalmente necesita tres capacidades: colocación de órdenes autenticada, datos de mercado en tiempo real y reconciliación del estado de posiciones y cuenta. Las URL exactas de los endpoints y los detalles de autenticación están documentados por Hyperliquid; este artículo utiliza marcadores de posición como RPC_URL y PRIVATE_KEY. Para elecciones concretas de endpoints y proveedores, utiliza el RPC Assistant en lugar de codificar un endpoint público.

Antes de escribir código, decide si usarás una billetera de agente (billetera API) o la clave privada de la billetera principal. Las billeteras de agente son la opción operativa más segura porque pueden operar pero no retirar. Mantén las claves en variables de entorno o en un gestor de secretos, nunca en el control de versiones.

• Primero testnet: Hyperliquid proporciona una testnet con fondos de faucet; valida el ciclo completo allí.
• Mínimo privilegio: utiliza una billetera de agente para firmar órdenes cuando sea posible.
• Observabilidad: registra cada solicitud, respuesta y transición de estado con marcas de tiempo.
• Interruptor de emergencia: una única bandera que cancela órdenes abiertas y detiene nuevos envíos.

Modelo mental: plano de datos, plano de decisión y plano de ejecución

Separa tu bot en tres planos. El plano de datos ingiere los feeds de WebSocket (libro de órdenes, operaciones, ejecuciones) y mantiene una vista local del mercado. El plano de decisión ejecuta tu estrategia con un temporizador o en cada evento de mercado y emite intenciones como 'comprar 0.1 BTC a precio límite X'. El plano de ejecución traduce las intenciones en llamadas API firmadas, rastrea las confirmaciones y reconcilia con el estado del exchange.

Esta separación importa porque la mayoría de los fallos de los bots no son fallos de estrategia; son divergencias de estado. Si tu posición local dice plano pero el exchange dice largo, la siguiente orden puede duplicar tu exposición. El plano de ejecución debe obtener periódicamente las órdenes abiertas y las posiciones y compararlas con el estado local, registrando y corrigiendo las discrepancias.

Presupuesto de latencia: la entrega por WebSocket, el cálculo de la estrategia, la firma y el viaje de ida y vuelta HTTP se suman. Para estrategias sensibles a la posición en la cola o a movimientos de precio a corto plazo, mide cada segmento. Para estrategias más lentas (grid, DCA), unos cientos de milisegundos suelen ser aceptables, pero aún así debes medir en lugar de asumir.

Requisitos previos y configuración del entorno

Necesitas Python 3.10+ (o Node 18+), un cliente HTTP, un cliente WebSocket y el SDK de Hyperliquid o llamadas REST directas. El ejemplo siguiente utiliza Python con el SDK oficial hyperliquid-python-sdk, que maneja la firma y la gestión de nonces. Instálalo en un entorno virtual y fija las versiones para reproducibilidad.

Crea un archivo .env con tu clave de testnet y una bandera booleana. Nunca confirmes este archivo. Para producción, inyecta secretos a través del almacén de secretos de tu orquestador. Si ejecutas el bot en un servidor, restringe el acceso de red saliente a los endpoints que realmente utilizas y monitorea el tráfico de salida inesperado.

python -m venv .venv
source .venv/bin/activate
pip install hyperliquid-python-sdk python-dotenv websockets

# .env
HYPERLIQUID_PRIVATE_KEY=0xYOUR_AGENT_WALLET_PRIVATE_KEY
HYPERLIQUID_TESTNET=true
HYPERLIQUID_ACCOUNT_ADDRESS=0xYOUR_MAIN_WALLET_ADDRESS

Implementación de un bucle mínimo de datos de mercado y órdenes

El siguiente esbozo en Python se conecta a Hyperliquid, se suscribe al precio medio de un perpetuo y coloca una orden límite cuando se cumple una condición de umbral simple. Es deliberadamente pequeño para que puedas verificar cada paso. Reemplaza el bloque de estrategia con tu propia lógica. El código utiliza las clases Exchange e Info del SDK; verifica las firmas de los métodos de la versión del SDK porque evolucionan.

Detalles clave de implementación: utiliza un nonce entero que aumente monotónicamente, establece un time-in-force (por ejemplo, Gtc o Ioc) explícitamente e incluye un ID de orden de cliente para que puedas correlacionar las ejecuciones con las intenciones. Después de colocar una orden, consulta o suscríbete al estado de la orden y actualiza el estado local solo con ejecuciones confirmadas, no con el envío.

import os, time
from dotenv import load_dotenv
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants

load_dotenv()
base_url = constants.TESTNET_API_URL if os.getenv('HYPERLIQUID_TESTNET') == 'true' else constants.MAINNET_API_URL
account = os.environ['HYPERLIQUID_ACCOUNT_ADDRESS']
exchange = Exchange(os.environ['HYPERLIQUID_PRIVATE_KEY'], base_url, account_address=account)
info = Info(base_url, skip_ws=False)

coin = 'BTC'
last_mid = None
while True:
    mids = info.all_mids()
    mid = float(mids[coin])
    if last_mid is not None and mid > last_mid * 1.001:
        # Example intent: buy 0.001 BTC at mid with a small offset
        px = round(mid * 0.999, 1)
        order = exchange.order(coin, True, 0.001, px, {'limit': {'tif': 'Gtc'}}, reduce_only=False)
        print('submitted', order)
    last_mid = mid
    time.sleep(1)

Verificación de la ejecución: resultados esperados y tabla de medición

Antes de confiar en el bot con tamaño, realiza una pasada de verificación en testnet. Para cada orden, confirma que la confirmación del exchange contiene un ID de orden, que la orden aparece en las órdenes abiertas y que una ejecución actualiza tu posición. Luego realiza una medición controlada de latencia y tasas de error. Registra la siguiente tabla en tu propio runbook; no la rellenes con números inventados.

Ejecuta la medición durante al menos unas horas en diferentes condiciones de mercado. Si utilizas un proveedor de RPC o API alojado, mide desde la misma región que tu bot. Para la selección de proveedores, consulta la guía del RPC Assistant sobre endpoints de trading de baja latencia y las páginas de redes de OnFinality para las cadenas compatibles.

Controles de riesgo que pertenecen al código, no a tu cabeza

Aplica límites en el plano de ejecución para que no puedan ser eludidos por errores de la estrategia. Como mínimo: tamaño máximo de posición por activo, exposición nocional máxima, pérdida diaria máxima, tasa máxima de órdenes y un modo obligatorio de solo reducción cuando la reducción supere un umbral. Cada límite debe verificarse antes de firmar una orden y registrarse cuando se active.

Utiliza IDs de orden de cliente idempotentes y una ventana de deduplicación para evitar órdenes duplicadas después de un tiempo de espera. Si una solicitud HTTP expira, no reintentes a ciegas una orden de mercado; consulta primero el estado de la orden por ID de cliente. Para órdenes límite, un reintento con el mismo ID de cliente es más seguro si el exchange admite idempotencia; de lo contrario, reconcilia antes de reenviar.

El financiamiento y la liquidación son parte del riesgo. Rastrea los pagos de financiamiento y el ratio de margen. Un bot que ignora el financiamiento puede sangrar en una estrategia de carry. Un bot que ignora el margen puede ser liquidado durante un movimiento rápido incluso si su lógica de entrada era correcta.

• Límites máximos de posición y nocional, verificados antes de operar.
• Interruptor de pérdida diaria que cambia el bot a solo reducción.
• Limitador de tasa de órdenes con un cubo de tokens.
• Alertas por picos de rechazos, discrepancias de reconciliación y umbrales de ratio de margen.

Solución de problemas comunes de bots en Hyperliquid

La mayoría de los fallos se dividen en cuatro categorías: autenticación/firma, nonce y límites de tasa, divergencia de estado y conectividad. Comienza con el cuerpo de la respuesta del exchange; normalmente indica el error. Registra el ID de solicitud completo y la marca de tiempo para que puedas correlacionarlos con las páginas de estado del exchange.

Los errores de firma a menudo provienen de usar el tipo de billetera incorrecto o una dirección de cuenta que no coincide. Si usas una billetera de agente, la clave de firma y la dirección de la cuenta son diferentes; pasa ambas correctamente. Los errores de nonce ocurren cuando varios procesos comparten una clave o cuando el reloj se desvía. Usa un único proceso firmante y sincroniza la hora mediante NTP.

Los errores de límite de tasa requieren retroceso con jitter, no reintentos ajustados. La divergencia de estado requiere un trabajo de reconciliación que obtenga las órdenes abiertas y las posiciones y las compare con el estado local; ejecútalo de forma programada y después de cada reconexión. Los problemas de conectividad se manejan mejor con un supervisor que reinicie el WebSocket y vuelva a suscribirse, además de un latido que detecte bloqueos silenciosos.

import time, random

def with_backoff(fn, attempts=5):
    for i in range(attempts):
        try:
            return fn()
        except Exception as e:
            if i == attempts - 1:
                raise
            sleep = min(2 ** i, 30) + random.random()
            print(f'retry {i+1} after {sleep:.1f}s: {e}')
            time.sleep(sleep)

Limitaciones y compensaciones del trading automatizado en Hyperliquid

La automatización mejora la consistencia y la velocidad pero no crea ventaja. Los backtests se sobreajustan, la liquidez de testnet difiere de la de mainnet y el impacto de mercado crece con el tamaño. Un bot de grid que parece rentable en un rango acumulará inventario en una tendencia; un bot de DCA que promedia a la baja puede acumular pérdidas si la tendencia persiste. El tamaño y los límites de riesgo son la defensa principal.

La complejidad operativa es real: la gestión de claves, el monitoreo, las actualizaciones y la respuesta a incidentes requieren tiempo. Si no puedes cubrir esas tareas, un bot más simple con menos piezas móviles es más seguro que uno sofisticado que no puedes observar. También considera las obligaciones regulatorias y fiscales en tu jurisdicción; el trading on-chain no las elimina.

Finalmente, el comportamiento de la API puede cambiar. Fija las versiones del SDK, lee las notas de la versión y mantén una ruta de reversión. Trata el bot como software de producción, no como un script.

Próximos pasos: de testnet a un despliegue monitoreado

Una vez que pase la verificación en testnet, despliega con un tamaño pequeño en mainnet y un límite de pérdidas estricto. Agrega paneles para latencia, tasa de rechazo, posición y PnL. Configura alertas para discrepancias de reconciliación y ratio de margen. Realiza una revisión semanal de las ejecuciones frente a las intenciones para detectar fallos silenciosos.

Para la infraestructura, elige endpoints y nodos que coincidan con tus requisitos de latencia y confiabilidad. Revisa el servicio API de OnFinality, compara los planes de precios de RPC y explora las redes compatibles antes de comprometerte. Si necesitas rendimiento dedicado, evalúa nodos dedicados. Para una recomendación concreta de endpoint, consulta al RPC Assistant en lugar de adivinar.

Sigue iterando: mide, ajusta los límites y documenta los incidentes. Un bot que es aburrido de operar suele ser el que sobrevive.