Cómo extraer datos históricos de Hyperliquid con su API

6 may 2026

hyperliquid historical data
hyperliquid data api
hyperliquid datos históricos
hyperliquid datos de velas
hyperliquid historial de funding rate

La base de cualquier investigación cuantitativa es la data. Ya sea que quieras hacer backtesting de una estrategia, analizar patrones de funding rate o estudiar microestructura de mercado, necesitas datos históricos confiables y completos. Hyperliquid, como exchange on-chain de contratos perpetuos, ofrece mediante su REST API varios endpoints útiles para datos históricos: velas OHLCV, funding rates, trades, fills de usuario, historial de órdenes y eventos de liquidación.

En esta guía veremos cómo obtener esos datos, qué parámetros usar, cómo paginar consultas largas y cuáles son buenas prácticas para guardar la información localmente. Para los endpoints que requieran autenticación o firma, una hardware wallet OneKey puede ayudarte a firmar de forma segura sin exponer tu llave privada al script de recolección de datos.

Panorama general de la API de datos históricos de Hyperliquid

Según la documentación oficial de Hyperliquid, gran parte de los datos históricos se consulta mediante el endpoint POST /info. El tipo de información se define con el campo type dentro del cuerpo de la petición.

Todos los timestamps usan formato Unix en milisegundos, es decir, enteros de 13 dígitos.

Cómo obtener velas OHLCV

Formato de la petición

import requests

BASE_URL = "https://api.hyperliquid.xyz"

def fetch_candles(coin, interval, start_ms, end_ms):
    """
    coin      : par de trading, por ejemplo "BTC"
    interval  : temporalidad, por ejemplo "1m", "5m", "1h", "1d"
    start_ms  : hora de inicio en timestamp de milisegundos
    end_ms    : hora de fin en timestamp de milisegundos
    """
    payload = {
        "type": "candleSnapshot",
        "req": {
            "coin": coin,
            "interval": interval,
            "startTime": start_ms,
            "endTime": end_ms
        }
    }

    resp = requests.post(f"{BASE_URL}/info", json=payload)
    resp.raise_for_status()
    return resp.json()

# Ejemplo: obtener velas de 1 hora de BTC de los últimos 7 días
import time

end_ms = int(time.time() * 1000)
start_ms = end_ms - 7 * 24 * 3600 * 1000

candles = fetch_candles("BTC", "1h", start_ms, end_ms)

Campos de respuesta

Cada vela incluye campos similares a los siguientes, sujetos a la definición exacta de la documentación oficial:

t: hora de inicio de la vela, en timestamp de milisegundos
o: precio de apertura, u open
h: precio máximo, o high
l: precio mínimo, o low
c: precio de cierre, o close
v: volumen negociado, o volume
n: número de trades

Estrategia de paginación

Una sola petición suele tener límites de cantidad de datos devueltos. Para rangos largos, conviene dividir el periodo en bloques y traerlos por partes:

import time

def fetch_candles_paginated(coin, interval, start_ms, end_ms, page_size_ms):
    """
    Divide el rango de tiempo en tramos, consulta cada tramo y combina resultados.

    page_size_ms: tamaño de cada tramo en milisegundos.
                  Debe ajustarse según el interval usado.
    """
    all_candles = []
    cursor = start_ms

    while cursor < end_ms:
        batch_end = min(cursor + page_size_ms, end_ms)
        batch = fetch_candles(coin, interval, cursor, batch_end)

        all_candles.extend(batch)

        if not batch:
            break

        # La siguiente página empieza en el timestamp de la última vela + 1 ms
        cursor = batch[-1]["t"] + 1

        # Pausa para reducir el riesgo de tocar límites de rate limit
        time.sleep(0.2)

    return all_candles

Historial de funding rate

El funding rate es uno de los mecanismos centrales en los contratos perpetuos. Su historial sirve para analizar sentimiento de mercado, estudiar sesgos entre longs y shorts, y estimar costos de mantener posiciones.

def fetch_funding_history(coin, start_ms, end_ms):
    payload = {
        "type": "fundingHistory",
        "req": {
            "coin": coin,
            "startTime": start_ms,
            "endTime": end_ms
        }
    }

    resp = requests.post(f"{BASE_URL}/info", json=payload)
    resp.raise_for_status()
    return resp.json()

La respuesta incluye el valor del funding rate para cada periodo de liquidación y su timestamp correspondiente. Esta data puede usarse para:

Analizar cambios en la presión de longs y shorts
Detectar señales de sentimiento extremo
Calcular el costo histórico de mantener una posición

Fills de usuario e historial de órdenes

Los endpoints que consultan datos privados de usuario suelen requerir una dirección de wallet y, en algunos casos, autenticación mediante firma. Una hardware wallet OneKey puede aportar una capa de seguridad importante para este flujo: la llave privada se mantiene dentro del elemento seguro del dispositivo y no queda expuesta al script que hace las consultas.

def fetch_user_fills(address, start_ms, end_ms):
    payload = {
        "type": "userFills",
        "req": {
            "user": address,
            "startTime": start_ms,
            "endTime": end_ms
        }
    }

    resp = requests.post(f"{BASE_URL}/info", json=payload)
    resp.raise_for_status()
    return resp.json()

Los fills suelen incluir campos como ID de orden, dirección de la operación, precio de ejecución, tamaño y comisiones. Esta información es clave para calcular PnL real, medir slippage y evaluar la calidad de ejecución de una estrategia.

Registros de liquidaciones

La data de liquidaciones a nivel de mercado ayuda a estudiar estructura de mercado y episodios de alta volatilidad:

def fetch_liquidations(start_ms, end_ms):
    payload = {
        "type": "liquidations",
        "req": {
            "startTime": start_ms,
            "endTime": end_ms
        }
    }

    resp = requests.post(f"{BASE_URL}/info", json=payload)
    resp.raise_for_status()
    return resp.json()

Almacenamiento de datos: CSV y base de datos

Guardar en CSV

Para una etapa de prototipado rápido, CSV suele ser la opción más simple:

import csv

def save_candles_to_csv(candles, filepath):
    if not candles:
        return

    fieldnames = ["t", "o", "h", "l", "c", "v", "n"]

    with open(filepath, "w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=fieldnames)
        writer.writeheader()

        for candle in candles:
            writer.writerow({k: candle.get(k, "") for k in fieldnames})

Guardar en una base de datos

Para volúmenes grandes o consultas frecuentes, conviene usar SQLite en local o PostgreSQL en producción:

import sqlite3

def init_db(db_path):
    conn = sqlite3.connect(db_path)

    conn.execute("""
    CREATE TABLE IF NOT EXISTS candles (
        coin     TEXT,
        interval TEXT,
        t        INTEGER,
        o        REAL,
        h        REAL,
        l        REAL,
        c        REAL,
        v        REAL,
        n        INTEGER,
        PRIMARY KEY (coin, interval, t)
    )
    """)

    conn.commit()
    return conn

def insert_candles(conn, coin, interval, candles):
    rows = [
        (coin, interval, c["t"], c["o"], c["h"], c["l"], c["c"], c["v"], c["n"])
        for c in candles
    ]

    conn.executemany(
        "INSERT OR IGNORE INTO candles VALUES (?,?,?,?,?,?,?,?,?)",
        rows
    )

    conn.commit()

La clave primaria PRIMARY KEY (coin, interval, t) evita duplicados si vuelves a consultar el mismo rango y facilita las actualizaciones incrementales.

Rate limits y puntos a cuidar

La API de Hyperliquid tiene límites de frecuencia. Para valores exactos y actualizados, consulta siempre la documentación oficial. En la práctica, considera estas recomendaciones:

Agrega una pausa razonable entre peticiones en bucle, por ejemplo de 200 ms a 500 ms
Implementa reintentos con backoff exponencial y espera automática cuando recibas HTTP 429
Haz descargas históricas grandes en horarios menos congestionados para no competir con flujos de trading en tiempo real
Cachea localmente los datos ya descargados para evitar pedir el mismo rango una y otra vez

Comparación con otras fuentes de datos

La ventaja de la API nativa de Hyperliquid es que la data proviene directamente del protocolo y suele ser la fuente más cercana al mercado. Para investigaciones que requieren datos de varios exchanges o protocolos, puedes combinarla con otras fuentes. La documentación de dYdX y la documentación de GMX también ofrecen endpoints históricos, con diseños de API distintos, pero conceptos similares.

Preguntas frecuentes

P1: ¿Cuál es la temporalidad mínima de las velas?

Consulta la documentación oficial de Hyperliquid para el endpoint candleSnapshot. Al momento de referencia de este artículo, se admiten varias temporalidades, incluidas de minutos, horas y días. Los valores exactos de interval deben verificarse en la documentación; si envías un parámetro inválido, la API debería devolver un error.

P2: ¿Qué tan atrás llega el historial?

En principio, los datos disponibles desde el lanzamiento de cada mercado pueden consultarse vía API. En la práctica, el rango depende de cuándo se listó cada activo y de la disponibilidad real de datos. Si un periodo no tiene información, la API puede devolver un arreglo vacío.

P3: ¿Cuánto tarda descargar una gran cantidad de datos históricos?

Depende del rango, la temporalidad y la estrategia de paginación. Por ejemplo, para velas de 1 hora en un historial amplio, considerando límites de frecuencia, el proceso puede tomar desde varios minutos hasta decenas de minutos. Lo más eficiente suele ser guardar la data en una base de datos y luego hacer actualizaciones incrementales.

P4: ¿Qué papel cumple OneKey al obtener datos?

Los datos públicos de mercado, como velas y funding rates, normalmente no requieren autenticación. En cambio, los endpoints con datos privados, como fills o historial de órdenes, pueden requerir firma. Una hardware wallet OneKey puede firmar estas solicitudes de forma segura, evitando que tu llave privada quede expuesta en el servidor o script que recolecta los datos.

P5: ¿Cómo manejar gaps o huecos en la data?

Errores de red, fallas temporales de la API o cortes durante la descarga pueden dejar huecos. Una buena práctica es registrar en tu base de datos qué rangos ya fueron descargados, escanear periódicamente intervalos faltantes y volver a pedirlos. Si haces backtesting, valida la integridad de los datos antes de usarlos, porque un gap puede distorsionar señales y métricas.

Conclusión

La API de datos históricos de Hyperliquid ofrece una base sólida para investigación cuantitativa. Con unas cuantas funciones en Python puedes armar un pipeline para descargar velas, funding rates, fills de usuario y liquidaciones, y luego guardarlos en CSV o en una base de datos.

Si además necesitas consultar datos privados o firmar solicitudes, OneKey puede ayudarte a mantener una separación más segura entre tus scripts y tus llaves privadas. Y si quieres pasar de análisis a ejecución de manera práctica, OneKey Perps es un flujo recomendado para operar perpetuos desde el ecosistema de OneKey con una experiencia más directa.

Puedes probar o descargar OneKey y usar OneKey Perps como parte de tu flujo de investigación y trading, siempre verificando los datos, los parámetros y los riesgos antes de operar.

Aviso de riesgo: los datos históricos solo reflejan condiciones pasadas del mercado y no indican resultados futuros. Las estrategias cuantitativas basadas en backtesting pueden sufrir sobreajuste, y su desempeño en vivo puede diferir de forma significativa. El trading de contratos perpetuos es de alto riesgo y puede causar pérdidas de capital. Este contenido es solo para aprendizaje técnico y no constituye asesoría financiera, legal ni de inversión.