La plataforma Hyperliquid se destaca como un exchange descentralizado de alto rendimiento para futuros perpetuos, ofreciendo operaciones de baja latencia y características avanzadas para desarrolladores. Los desarrolladores recurren frecuentemente a la API de Hyperliquid para automatizar operaciones, monitorear mercados y construir aplicaciones personalizadas.
Comienzas por comprender los componentes centrales de la API de Hyperliquid. La API se divide en categorías clave: la API de Información para consultar datos de mercado, la API de Exchange para acciones de trading y WebSocket para actualizaciones en tiempo real. Además, los SDK en lenguajes como Python y Node.js simplifican las interacciones. A medida que avances, verás cómo pequeños ajustes en los parámetros de solicitud conducen a mejoras significativas en la eficiencia de ejecución.
¿Qué es la API de Hyperliquid?
La API de Hyperliquid permite el acceso programático al exchange de futuros perpetuos descentralizado de Hyperliquid. Admite operaciones tanto en entornos de mainnet como de testnet. Te conectas a mainnet y testnet. La API utiliza JSON para solicitudes y respuestas, basándose en HTTP POST para la mayoría de las acciones y WebSocket para suscripciones.
En algunos casos, te autenticas usando claves privadas en lugar de las tradicionales claves API, pero Hyperliquid también ofrece carteras API para una delegación segura. Estas carteras actúan en nombre de tu cuenta principal sin permisos de retiro, mejorando la seguridad para el trading automatizado. Por ejemplo, generas una cartera API a través de la aplicación Hyperliquid, la autorizas y usas su clave privada en tus scripts.
A continuación, considera los tipos de datos. La API emplea estructuras y enumeraciones específicas. Los activos se identifican por índices de la lista universal, los lados de la orden usan booleanos (verdadero para comprar, falso para vender), y las opciones de tiempo en vigor incluyen 'Gtc' para "good 'til canceled" (válida hasta su cancelación). Recuperas estos detalles de los puntos finales de metadatos para asegurar la precisión en tus solicitudes.
Con esta base, pasas a configurar tu entorno de desarrollo. Una configuración adecuada previene errores comunes y acelera la iteración.
Configuración de tu entorno para la API de Hyperliquid
Comienzas la configuración eligiendo tu lenguaje de programación e instalando el SDK relevante. Para los usuarios de Python, el SDK `hyperliquid-python-sdk` proporciona un sólido punto de partida. Instálalo a través de pip con el comando pip install hyperliquid-python-sdk. Este SDK maneja conexiones, autenticación y operaciones comunes.
Luego configuras tus credenciales. Crea un archivo `config.json` con la dirección de tu cuenta (clave pública) y la clave secreta (clave privada). Por seguridad, generas una cartera API dedicada. Navega a la aplicación Hyperliquid, selecciona "Más > API", introduce un nombre para la clave, pega la dirección de tu cartera y haz clic en "Generar". Autoriza la cartera API y copia su clave privada en tu configuración.
El SDK importa constantes para URLs, como constants.TESTNET_API_URL para pruebas. Inicializas clientes de esta manera:
from hyperliquid.info import Info
from hyperliquid.utils import constants
info = Info(constants.TESTNET_API_URL, skip_ws=True)
Esta configuración omite WebSocket inicialmente, centrándose en HTTP. Pruebas la conexión consultando el estado del usuario:
user_state = info.user_state("your_account_address")
print(user_state)
Si la respuesta muestra los detalles de tu cuenta, tu entorno funciona correctamente. Sin embargo, si encuentras errores, verifica tu clave privada y la selección de red.
Para Node.js, usas el paquete `@nktkas/hyperliquid`. Instálalo con npm, luego configura transportes y clientes usando `ethers` para la gestión de carteras. Especificas isTestnet: true para evitar fondos reales durante el desarrollo.
Herramientas como Apidog complementan esta configuración. Importas las especificaciones de la API de Hyperliquid en Apidog, te autenticas con tus claves y simulas solicitudes. Este enfoque revela rápidamente las estructuras de respuesta, ahorrando tiempo en la codificación manual.
Una vez configurado, avanzas a los métodos de autenticación. Una autenticación adecuada asegura que tus acciones se ejecuten de forma segura.
Autenticación con la API de Hyperliquid
Te autenticas principalmente a través de la firma con clave privada, ya que Hyperliquid opera en un sistema basado en blockchain. Los SDK manejan la firma automáticamente cuando proporcionas una instancia de cartera.
Para llamadas directas a la API sin SDK, firmas las cargas útiles usando tu clave privada. El cuerpo de la solicitud incluye un nonce para la protección contra repetición, y publicas en los puntos finales `/exchange` o `/info`.
Las carteras API añaden flexibilidad. Creas una dándole un nombre, vinculándola a la dirección de tu cartera principal, generando la clave y autorizándola. Esta cartera realiza operaciones pero no puede retirar fondos, lo que reduce el riesgo para los bots. En el código, usas la clave privada de la cartera API mientras especificas la dirección de la cuenta principal.
Pruebas la autenticación enviando una simple solicitud de información. Si no está autorizada, la API devuelve un error como "El usuario o la cartera API no existe". Para solucionarlo, asegúrate de que tu cartera tenga un colateral mínimo, como USDC para perpetuos.
La seguridad sigue siendo primordial. Almacenas las claves en variables de entorno o bóvedas seguras, las rotas periódicamente y monitoreas cualquier actividad inusual. Con la autenticación en su lugar, exploras los puntos finales de la API de Información.
Explorando los puntos finales de la API de Información
La API de Información proporciona acceso de solo lectura a datos de mercado y de cuenta. La usas para obtener metadatos, precios, órdenes y más, sin necesidad de autenticación para datos públicos.
Comienzas con el punto final `meta`, que devuelve el universo de activos y los contextos. En Node.js:
const [meta] = await infoClient.metaAndAssetCtxs();
Esto produce un array de activos con nombres, índices y especificaciones como el apalancamiento máximo. Usas el índice del activo en las solicitudes de trading.
A continuación, consultas los precios medios con `allMids`, que devuelve los puntos medios actuales para todos los pares. Las órdenes abiertas provienen de `openOrders`, que requiere tu dirección.
Otros puntos finales incluyen:
- userState: Recupera posiciones, márgenes y saldos.
- fundingHistory: Muestra las tasas de financiación a lo largo del tiempo.
- l2Book: Proporciona el libro de órdenes de nivel 2 para una moneda.
Envías solicitudes POST con cuerpos JSON como `{"type": "meta"}` a `/info`. Las respuestas utilizan estructuras consistentes, con "data" conteniendo los resultados.
Apidog ayuda aquí: configuras una colección para la API de Información, añades solicitudes para cada tipo y parametrizas monedas o direcciones. Esta visualización ayuda a comprender el flujo de datos.
A medida que recopilas datos, pasas a la API de Exchange para ejecutar operaciones.
Uso de los puntos finales de la API de Exchange para trading
La API de Exchange maneja acciones como realizar, cancelar y modificar órdenes. Autenticas todas las solicitudes con cargas útiles firmadas.
Realizas órdenes definiendo parámetros: índice del activo, lado, precio, tamaño, bandera de solo reducción y tipo (límite o mercado). Para una venta límite:
En Elixir (de la documentación del SDK):
Hyperliquid.Api.Exchange.place_order(order)
Donde `order` es un mapa con: `a`: activo, `b`: `false` (venta), `p`: "100", `s`: "0.1", `r`: `false`, `t`: `{limit: {tif: "Gtc"}}`.
La respuesta incluye el estado y el ID de la orden si tiene éxito.
Cancela órdenes usando el activo y `oid` (ID de la orden):
Hyperliquid.Api.Exchange.cancel_order(asset, oid)
Para lotes, usas `cancel_orders` con una lista.
Las modificaciones siguen un patrón similar: especificas `oid` y los nuevos parámetros.
Otras acciones incluyen la actualización del apalancamiento:
Hyperliquid.Api.Exchange.update_leverage(asset, is_cross, leverage)
Y transferencias, como `spot_perp_transfer` para mover fondos entre cuentas.
Manejas los errores verificando el estado de la respuesta: "ok" para éxito, de lo contrario, detalles como margen insuficiente.
Los ejemplos demuestran el uso práctico. Por ejemplo, construyes un bot que coloca una orden de compra cuando el precio cae por debajo de un umbral, usando `info` para verificar precios y `exchange` para la colocación.
Además, integras WebSocket para actualizaciones en tiempo real para mejorar la capacidad de respuesta.
Integrando WebSocket para datos en tiempo real
Te conectas a WebSocket para flujos de datos en vivo. Usa `wss://api.hyperliquid.xyz/ws` para mainnet o el equivalente de testnet.
Te suscribes enviando JSON: `{"method": "subscribe", "subscription": {"type": "trades", "coin": "SOL"}}`.
El servidor responde con una confirmación, luego envía actualizaciones como nuevas operaciones.
Manejas temas como el libro de órdenes, eventos de usuario y notificaciones. En el SDK de Python, establece `skip_ws=False` para habilitarlo.
Esta capacidad en tiempo real te permite reaccionar instantáneamente a los cambios del mercado, como ajustar órdenes en las ejecuciones.
Con los puntos finales cubiertos, examinamos el SDK de Python en profundidad.
Aprovechando el SDK de Python de Hyperliquid
El SDK de Python abstrae las llamadas a la API en clases. Importas `Info` para consultas y `Exchange` para acciones.
Realizas una orden básica así (de los ejemplos):
Primero, carga la configuración:
import json
def address_and_private_key():
with open("examples/config.json") as f:
config = json.load(f)
return config["account_address"], config["secret_key"]
Luego, inicializa `Exchange`:
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
address, private = address_and_private_key()
exchange = Exchange(address, private, base_url=constants.TESTNET_API_URL)
Realiza la orden:
order_result = exchange.order("BTC", True, 0.02, 30000, {"limit": {"tif": "Gtc"}})
print(order_result)
Esto compra 0.02 BTC a un límite de $30,000.
Extiendes esto para características avanzadas, como órdenes o cancelaciones por lotes.
El SDK también admite direcciones de bóveda para cuentas gestionadas.
Los ejemplos en el repositorio cubren `basic_order`, `user_state` y más, demostrando flujos de trabajo completos.
A medida que construyes, incorporas las mejores prácticas para optimizar el rendimiento.
Mejores prácticas para el uso de la API de Hyperliquid
Monitoreas los límites de velocidad para evitar la limitación: Hyperliquid impone límites por IP y por cuenta.
Usas testnet para todo el desarrollo para prevenir pérdidas financieras.
El manejo de errores implica registrar detalles y reintentar fallos transitorios con retroceso exponencial.
Para la escalabilidad, agrupas las solicitudes siempre que sea posible, como múltiples cancelaciones.
La seguridad se extiende al uso de carteras API y principios de mínimo privilegio.
También versionas tu código con las actualizaciones del SDK, ya que Hyperliquid sigue el versionado semántico.
Herramientas como Apidog ayudan a simular respuestas para pruebas unitarias.
La resolución de problemas viene después cuando surgen problemas.
Resolución de problemas comunes de la API de Hyperliquid
Encuentras "Margen insuficiente" cuando el colateral es bajo; deposita USDC para resolverlo.
Si "Activo no encontrado", verifica los índices desde `meta`.
Los errores de autenticación provienen de claves inválidas; regenera y autoriza las carteras API.
Los problemas de red requieren verificar las URL y usar proxies si es necesario.
Depuras con Apidog reproduciendo solicitudes fallidas.
Los registros de los SDK proporcionan marcas de tiempo y cargas útiles para el análisis.
Con estos consejos, mantendrás integraciones fiables.
Casos de uso avanzados con la API de Hyperliquid
Construyes bots de trading que monitorean `l2Book` y colocan órdenes en desequilibrios.
Las estrategias implican tasas de financiación del historial para oportunidades de arbitraje.
Las subcuentas permiten el trading segregado: créalas con un nombre, transfiere fondos y opera por separado.
Las transferencias de bóveda admiten fondos de liquidez compartidos.
Simulas con datos históricos de la API para realizar backtesting.
La integración con Apidog permite la depuración colaborativa en equipos.
Finalmente, concluyes considerando futuras mejoras.
Conclusión: Dominando la API de Hyperliquid para el trading descentralizado
Ahora posees el conocimiento para usar eficazmente la API de Hyperliquid. Desde la configuración y autenticación hasta los puntos finales y los SDK, esta guía te equipa para construir aplicaciones sofisticadas. Recuerda, las mejoras incrementales en tu código producen ganancias sustanciales en el rendimiento. Experimenta en testnet, aprovecha herramientas como Apidog y mantente actualizado con la documentación de Hyperliquid. A medida que la plataforma evoluciona, tus habilidades te posicionan para capitalizar las nuevas características.