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.