Guía completa de la API de historial de funding rate de Hyperliquid

La tasa de financiamiento o funding rate es uno de los mecanismos clave de precio en los mercados de perpetuos. Define directamente el costo de mantener posiciones long o short. Para investigadores cuantitativos, traders de arbitraje y equipos de gestión de riesgo, poder consultar datos históricos de funding de forma rápida y en lote es una capacidad básica.

Hyperliquid ofrece una API pública de consulta de información que permite acceder a muchos datos de mercado sin API Key. En esta guía verás cómo usar la API oficial de Hyperliquid para obtener el historial de funding rate, junto con ejemplos en Python para que puedas empezar de inmediato.

Por qué es importante el historial de funding rate

El historial de funding rate tiene varios usos prácticos:

• Identificar estructuras de mercado con sesgo long o short de forma persistente, como apoyo para lectura de tendencia.
• Calcular el rendimiento esperado histórico de estrategias de arbitraje de funding.
• Construir factores de funding para modelos cuantitativos de selección de activos o gestión de posiciones.
• Hacer backtesting de estrategias de cobertura spot-perpetuo bajo distintos entornos de tasas.

La arquitectura de Hyperliquid se basa en un libro de órdenes on-chain. Las operaciones y liquidaciones pueden verificarse en la blockchain, lo que aporta una mayor trazabilidad a los datos históricos.

Arquitectura básica de la API de Hyperliquid

Hyperliquid ofrece dos tipos principales de endpoints:

• Info Endpoint: solo lectura. Sirve para consultar datos de mercado, estado de cuentas e historiales. No requiere firma.
• Exchange Endpoint: para operaciones de escritura, como colocar o cancelar órdenes. Requiere firma con wallet.

La consulta del historial de funding rate es una operación de solo lectura, por lo que usa el Info Endpoint:

POST https://api.hyperliquid.xyz/info

Todas las solicitudes se envían como POST, con cuerpo JSON y Content-Type igual a application/json.

Estructura de la solicitud para consultar funding history

Para obtener el historial de funding rate de un activo específico, usa el tipo fundingHistory:

{
  "type": "fundingHistory",
  "coin": "BTC",
  "startTime": 1700000000000,
  "endTime": 1700086400000
}

Campos principales:

• type: debe ser fundingHistory.
• coin: símbolo del activo, por ejemplo BTC o ETH.
• startTime: timestamp Unix en milisegundos.
• endTime: timestamp Unix en milisegundos.

Los timestamps deben estar en milisegundos. Si no envías endTime, la API devuelve datos desde startTime hasta el momento actual, sujeto al límite de registros por solicitud.

Formato de respuesta

La API devuelve un arreglo. Cada registro incluye campos como:

[
  {
    "coin": "BTC",
    "fundingRate": "0.0001",
    "premium": "0.00012",
    "time": 1700000000000
  }
]

En Hyperliquid, el funding rate se liquida cada hora. Para más detalles sobre el mecanismo, puedes revisar la sección de Perpetuals en la documentación oficial de Hyperliquid.

Ejemplo completo en Python

El siguiente código obtiene el historial de funding rate de BTC de los últimos 30 días y calcula una tasa anualizada simple:

import requests
import time
import pandas as pd

ENDPOINT = "https://api.hyperliquid.xyz/info"


def get_funding_history(coin: str, days: int = 30) -> pd.DataFrame:
    end_ms = int(time.time() * 1000)
    start_ms = end_ms - days * 24 * 3600 * 1000

    payload = {
        "type": "fundingHistory",
        "coin": coin,
        "startTime": start_ms,
        "endTime": end_ms,
    }

    resp = requests.post(ENDPOINT, json=payload, timeout=15)
    resp.raise_for_status()

    data = resp.json()
    df = pd.DataFrame(data)

    df["time"] = pd.to_datetime(df["time"], unit="ms", utc=True)
    df["fundingRate"] = df["fundingRate"].astype(float)
    df["annualized"] = df["fundingRate"] * 24 * 365  # liquidación por hora

    return df.sort_values("time")


if __name__ == "__main__":
    df = get_funding_history("BTC", days=30)
    print(df.tail(10).to_string(index=False))
    print(f"\nFunding rate anualizado promedio de 30 días: {df['annualized'].mean():.2%}")

Ten en cuenta que esta anualización es una extrapolación lineal simple. El resultado real puede verse afectado por capitalización, slippage, costos de préstamo, comisiones, cambios de liquidez y ejecución.

Cómo consultar varios activos en lote

Si necesitas obtener funding rates de varios activos al mismo tiempo, puedes hacer llamadas concurrentes:

import concurrent.futures

COINS = ["BTC", "ETH", "SOL", "ARB", "DOGE"]

with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
    futures = {executor.submit(get_funding_history, c, 7): c for c in COINS}
    results = {}

    for future in concurrent.futures.as_completed(futures):
        coin = futures[future]
        results[coin] = future.result()

# Combinar en un solo DataFrame
combined = pd.concat(results.values(), ignore_index=True)

pivot = combined.pivot_table(
    index="time",
    columns="coin",
    values="fundingRate",
    aggfunc="mean"
)

Este enfoque es útil para construir dashboards, escáneres de oportunidades o modelos que comparen el funding entre distintos mercados.

Recomendaciones para almacenar los datos

Si vas a consultar estos datos con frecuencia, conviene guardar el historial en una base de datos local, como SQLite o TimescaleDB. Así evitas repetir solicitudes innecesarias a la API y puedes hacer consultas más rápidas para backtesting.

import sqlite3

conn = sqlite3.connect("funding_rates.db")
df.to_sql("funding_history", conn, if_exists="append", index=False)
conn.close()

Hyperliquid también mantiene un SDK oficial de Python en GitHub, que encapsula flujos de autenticación y firma. Puede ser útil si además de consultar datos quieres ejecutar operaciones desde código.

Cómo gestionar activos de Hyperliquid con OneKey

El análisis de datos es solo el primer paso. Cuando pasas a ejecutar una estrategia, la gestión segura de tus claves y fondos se vuelve igual de importante.

OneKey te permite conectarte a Hyperliquid con protección de wallet de hardware: tus claves privadas se mantienen en un dispositivo offline, lo que ayuda a reducir riesgos asociados con filtraciones de API Key, phishing o entornos comprometidos.

Si después de analizar el funding encuentras una posible estrategia de arbitraje o cobertura spot-perpetuo, puedes usar OneKey Perps como flujo práctico para acceder a Hyperliquid, mantener protección de clave privada a nivel hardware y operar perpetuos con una experiencia más fluida.

Puedes descargar OneKey y probar OneKey Perps para gestionar tus operaciones de perpetuos con un enfoque más seguro y basado en datos. Hazlo con criterio: valida tus supuestos, controla el tamaño de posición y considera siempre los riesgos de mercado.

Preguntas frecuentes

Q1: ¿La API de funding rate de Hyperliquid requiere registro?

No. El Info Endpoint es público y no requiere API Key ni cuenta. Cualquier persona puede llamarlo directamente para obtener datos históricos de funding rate.

Q2: ¿Cuántos registros se pueden obtener en una sola solicitud?

La documentación oficial de Hyperliquid no especifica claramente un límite único para todas las consultas. En la práctica, las solicitudes con rangos de tiempo largos pueden venir truncadas. Lo recomendable es consultar por segmentos, por ejemplo cada 7 días, e implementar lógica de paginación o reintentos en tu código.

Q3: ¿El funding rate puede ser positivo o negativo?

Sí. Cuando el funding rate es positivo, los longs pagan a los shorts. Cuando es negativo, los shorts pagan a los longs. En mercados alcistas o de mayor apetito por riesgo, las tasas positivas suelen ser más comunes, ya que reflejan una prima long agregada.

Q4: ¿Cómo puedo usar el historial de funding para evaluar oportunidades de arbitraje?

Puedes calcular media, desviación estándar y percentiles históricos del funding rate. Si la tasa actual está claramente por encima de su media histórica, por ejemplo más de una desviación estándar, una estrategia teórica podría ser short en perpetuo y long en spot para intentar capturar el funding. Aun así, esto no es asesoría financiera: debes considerar slippage, comisiones, liquidez, riesgo de base, costos de capital y movimientos bruscos del mercado.

Q5: ¿Cuál es la diferencia entre premium y fundingRate?

premium representa la prima entre el precio de marca y el índice spot. Es uno de los insumos para calcular el siguiente funding rate. En cambio, fundingRate es la tasa ya liquidada para el periodo correspondiente, determinada por la prima promedio y la referencia de tasa de interés.

Riesgos

Este artículo es solo para fines técnicos y educativos. No constituye asesoría de inversión, financiera, legal ni fiscal. El trading de perpetuos implica alto riesgo, incluida la posibilidad de pérdidas significativas. El rendimiento histórico del funding rate no garantiza resultados futuros. Antes de operar, asegúrate de entender el producto, la mecánica de liquidación, el apalancamiento y los riesgos de ejecución.