Guía de la API de Hyperliquid: Python, WebSocket y Tracking de Wallets (2026)

Respuesta rápida: la API de Hyperliquid es una interfaz pública y gratuita con tres superficies: el endpoint Info (POST https://api.hyperliquid.xyz/info) para leer datos de mercado y de cuentas, el endpoint Exchange para enviar órdenes y un WebSocket (wss://api.hyperliquid.xyz/ws) para streams en tiempo real. Con el SDK oficial de Python puedes obtener fills, posiciones y PnL de cualquier wallet en minutos — o saltarte el código por completo y trackear el PnL de cualquier wallet de Hyperliquid, con fees y funding, al instante con Hyperfolio, el tracker gratuito de wallets de Hyperliquid.

Cada posición, fill y liquidación en Hyperliquid vive on-chain y es legible públicamente a través de la API. Eso es raro en crypto: la mayoría de exchanges esconden sus order books y los datos de cuenta detrás de endpoints privados. Hyperliquid los expone a cualquiera, y por eso builders, traders cuantitativos y herramientas de analítica como Hyperfolio leen todos los mismos datos en bruto.

El problema es que la documentación oficial es material de referencia, no un tutorial. Acabas saltando entre el GitBook, el repositorio del SDK de Python y issues antiguos de GitHub para reconstruir cómo funciona de verdad. Esta guía te da la versión que funciona: endpoints, código, rate limits y las trampas que te hacen perder horas — y después te muestra qué merece la pena construir tú mismo y qué resuelve ya un tracker hecho.

¿Qué es la API de Hyperliquid?

La API se divide en tres superficies, y cada una tiene un trabajo distinto:

• Endpoint Info (REST, solo lectura): datos de mercado, estado del order book, fills de un usuario, posiciones, valor de cuenta, funding, liquidaciones y datos del leaderboard.
• Endpoint Exchange (REST, autenticado): enviar, cancelar y modificar órdenes, además de retiros — firmado con una agent wallet.
• WebSocket: push en tiempo real de trades, actualizaciones del order book, allMids, fills de usuario, funding y más, sin hacer polling.

Todos los ejemplos de la documentación oficial usan la URL base de mainnet https://api.hyperliquid.xyz; la equivalente en testnet es https://api.hyperliquid-testnet.xyz.

Superficie	URL	Auth	Casos de uso
Info (REST)	POST api.hyperliquid.xyz/info	Ninguna	Leer cualquier wallet, mercado, leaderboard
Exchange (REST)	POST api.hyperliquid.xyz/exchange	Firma de agent wallet	Enviar/cancelar órdenes, retirar
WebSocket	wss://api.hyperliquid.xyz/ws	Ninguna (lectura), acciones firmadas	Trades, books y fills en tiempo real

Inicio rápido: SDK de Python en 5 minutos

Hyperliquid mantiene un SDK oficial de Python (github.com/hyperliquid-dex/hyperliquid-python-sdk), y la comunidad tiene también SDKs en Rust y TypeScript. Instálalo y consulta el mid price de cualquier moneda:

pip install hyperliquid-python-sdk

from hyperliquid.info import Info

info = Info("https://api.hyperliquid.xyz")
mids = info.all_mids()
print(mids["BTC"])   # p.ej. "98452.3"

La clase Info envuelve todos los endpoints de solo lectura con métodos tipados, así que rara vez tocas HTTP en bruto. Para cualquier cosa que el SDK no cubra, puedes hacer POST con JSON directamente al endpoint Info — al fin y al cabo es una API HTTP.

Leer cualquier wallet con el endpoint Info

Esta es la parte que la mayoría de guías se saltan y la que más importa para el tracking: cómo leer el estado de cualquier wallet, no solo la tuya. Como el order book y el estado de las cuentas de Hyperliquid están on-chain, todas las wallets son públicas. Los tipos de request clave son:

• clearinghouseState — posiciones abiertas, resumen de margen y valor de cuenta de un usuario.
• userFills — los últimos 2.000 fills, cada uno con px, sz, side, time, fee, feeToken, dir, startPosition y closedPnl.
• userFillsByTime — fills en un rango de tiempo, paginados; 2.000 por respuesta y solo están disponibles los 10.000 fills más recientes.
• allMids — mid prices de todos los perpetuos.
• userRateLimit — la cuota de API de una wallet y su uso actual.

import requests

r = requests.post("https://api.hyperliquid.xyz/info", json={
    "type": "userFills",
    "user": "0xTU_DIRECCION_O_CUALQUIERA"   # cualquier dirección de 42 caracteres
})
fills = r.json()
for f in fills[:3]:
    print(f["coin"], f["dir"], f["px"], "fee:", f["fee"], "closedPnl:", f["closedPnl"])

Dos trampas que pican a todo el mundo:

• Usa la dirección real de la cuenta. Si consultas la dirección de una agent wallet obtienes un resultado vacío — pasa la dirección de la cuenta master o sub-account.
• La paginación tiene tope. Las respuestas por rango de tiempo devuelven como máximo 500 elementos o bloques; usa el último timestamp como siguiente startTime para paginar. Los fills se limitan a los 10.000 más recientes.

Datos en tiempo real con WebSocket

Hacer polling al endpoint Info funciona para apps pequeñas, pero el WebSocket es la herramienta correcta para tracking en vivo. Conéctate a wss://api.hyperliquid.xyz/ws (mainnet) o wss://api.hyperliquid-testnet.xyz/ws (testnet) y suscríbete:

from hyperliquid.info import Info
from hyperliquid.utils import constants

info = Info(constants.MAINNET_API_URL, skip_ws=False)
info.subscribe({"type": "trades", "coin": "BTC"}, callback=print)

O en bruto con la librería websockets:

import asyncio, json, websockets

async def main():
    async with websockets.connect("wss://api.hyperliquid.xyz/ws") as ws:
        await ws.send(json.dumps({"method": "subscribe",
                                  "subscription": {"type": "trades", "coin": "BTC"}}))
        async for msg in ws:
            print(msg)

asyncio.run(main())

Los tipos de suscripción incluyen trades, allMids, l2Book, userFills, userEvents (funding, liquidaciones, órdenes), activeAssetCtx y candle, entre otros.

Gestiona las reconexiones. La documentación es explícita: el servidor desconecta periódicamente y sin aviso. Los usuarios automatizados deben detectar la desconexión y reconectarse con elegancia — los datos perdidos aparecen en el snapshot ack al reconectar, y puedes rellenar huecos con las requests Info correspondientes.

Exchange API y agent wallets

Si quieres operar de forma programática, el endpoint Exchange acepta payloads de acción firmados (order, cancel, withdraw…). Nunca firmas con tu wallet principal: creas una agent wallet que puede operar pero no puede retirar fondos — un diseño que limita el daño si se filtran tus claves.

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

account = Account.from_key("0xTU_CLAVE_PRIVADA_DE_AGENT")
exchange = Exchange(account, constants.MAINNET_API_URL)
result = exchange.order("BTC", True, 1.0, 99000.0, {"limit": {"tif": "Gtc"}})
print(result)

El envío de órdenes está documentado al detalle en el GitBook, en la sección Exchange endpoint, con los esquemas exactos de los payloads. Para cualquier cosa más allá de un bot personal, lee las reglas de rate limits de abajo antes de escribir tu primer bucle.

Rate limits y las trampas que te hacen perder horas

La API REST pública tiene un tope de aproximadamente 1.200 de peso de request por minuto por IP, y la mayoría de requests Info cuestan unos 20 puntos más recargos por elemento — así que un bucle de polling ingenuo choca con el techo muy rápido. Además, las consultas por rango de tiempo devuelven solo 500 elementos por página, y los fills más allá de los 10.000 recientes desaparecen de la API.

Las consecuencias prácticas para un tracker:

• Vigilar muchas wallets exige batching cuidadoso y backoff, o recibirás respuestas 429.
• El histórico largo de PnL necesita archivado continuo — no puedes recuperar retroactivamente un año entero de fills.
• Los pagos de funding y las liquidaciones son tipos de evento separados que hay que fusionar con los fills para calcular el PnL real.
• Las fees se cobran en el feeToken del fill e incluyen builder fees, así que tu matemática de PnL debe restarlas correctamente.

Conclusión: leer datos de Hyperliquid es fácil. Leerlos correctamente — histórico completo, fees, funding, liquidaciones, paginación, reconexiones — es un pequeño proyecto de ingeniería.

Montar tu propio tracker vs. Hyperfolio

Si tu objetivo es un bot de trading o un backtester personalizado, la API es la base correcta. Si tu objetivo es el tracking — tu propio PnL, una wallet que copias o smart money —, montarlo tú mismo significa hacerte dueño de todos los problemas de arriba. Esta es la matemática honesta:

Capacidad	DIY con la API de Hyperliquid	Hyperfolio
Tiempo de setup	Días o semanas	< 1 minuto, sin registro
Código a escribir	300–800+ líneas (paginación, merge, almacenamiento)	0 líneas
Rate limits	1.200 peso/min/IP — gestionas el batching	Ninguno visible — lee cualquier wallet cuando quieras
Histórico de fills	Solo los últimos 10.000 vía API	Tracking continuo con desglose completo de PnL
PnL con fees + funding	Implementas tú la matemática	Integrado, por venue y por wallet
Multi-venue (AsterDEX, Lighter, Robinhood Chain)	Integración separada por venue	Portfolio unificado listo para usar
Alertas push de fills/liquidaciones	Tú construyes el pipeline de notificaciones	Alertas push integradas
Precio	Tus horas de desarrollo	Gratis

Hyperfolio está construido sobre los mismos datos públicos, pero resuelve la capa de tracking para que tú no tengas que hacerlo: conecta tu wallet o busca cualquier dirección de Hyperliquid y obtienes el PnL desglosado por fees y funding, posiciones abiertas, smart money radar y alertas push — sin registro y sin infraestructura.

Dónde gana todavía la API en bruto

Para ser honestos: la API es la mejor opción cuando tu objetivo es un bot de trading, un motor de backtesting propio o datasets de investigación a escala. Hyperfolio no sustituye al código — sustituye al dashboard de tracking que tendrías que construirte tú. Si necesitas ejecución de órdenes, indicadores personalizados o archivos legibles por máquina, usa el SDK y el endpoint Exchange. Si necesitas saber qué ha hecho una wallet, cuánto ha ganado y cuánto ha pagado en fees, Hyperfolio te lo da al instante.

FAQ

¿La API de Hyperliquid es gratuita?

Sí. Los endpoints Info y WebSocket son públicos y gratuitos, sujetos a rate limits (~1.200 de peso de request por minuto por IP). Solo pagas fees de trading al enviar órdenes por el endpoint Exchange.

¿Cuál es la URL del WebSocket de Hyperliquid?

Mainnet es wss://api.hyperliquid.xyz/ws y testnet es wss://api.hyperliquid-testnet.xyz/ws. Envía un mensaje subscribe con el tipo de suscripción (p.ej. trades, allMids, userFills) y gestiona las reconexiones.

¿Puedo trackear el PnL de otra wallet con la API de Hyperliquid?

Sí — todas las wallets son públicas en Hyperliquid. Consulta userFills y clearinghouseState con la dirección de la wallet y calcula el PnL a partir de closedPnl menos fees y funding. O busca la dirección en Hyperfolio y obtén el desglose al instante, sin código.

¿Qué es una agent wallet en Hyperliquid?

Es una clave separada que autorizas para operar en nombre de tu cuenta principal. Puede enviar y cancelar órdenes, pero nunca retirar fondos, lo que protege tu saldo si la clave se ve comprometida.

¿La API devuelve fees y funding por separado?

Los fills incluyen el campo fee (y builderFee), mientras que los pagos de funding llegan como eventos separados. Combinar ambos con closedPnl es exactamente lo que Hyperfolio hace automáticamente para mostrarte tu PnL real.

Empieza a trackear sin escribir una línea de código

La API de Hyperliquid es un regalo para los builders, pero no todas las preguntas necesitan un codebase. Si quieres tu PnL real — después de fees y funding — para tu propia wallet o para cualquier dirección que estés vigilando, abre Hyperfolio, conecta tu wallet o pega cualquier dirección de Hyperliquid y mira el desglose completo gratis. Sin registro, sin API keys, sin 429s.

Y si estás construyendo, combina esta guía con nuestro análisis a fondo sobre cómo calcular el PnL real con fees y funding para que tu matemática coincida con lo que el exchange liquida de verdad.