Récupérer les données historiques Hyperliquid via API

6 mai 2026

hyperliquid historical data
hyperliquid data api
hyperliquid données historiques
hyperliquid données K-line
hyperliquid historique funding rate

La donnée est la base de toute recherche quantitative. Que tu veuilles backtester une stratégie, analyser les régimes de funding rate ou étudier la microstructure du marché, il te faut des données historiques fiables et aussi complètes que possible.

Hyperliquid, en tant que plateforme de contrats perpétuels on-chain, expose plusieurs jeux de données via son API REST : chandeliers OHLCV, historique des funding rates, trades, exécutions utilisateur, ordres et liquidations. Dans ce guide, on passe en revue les principales méthodes de récupération, les paramètres utiles, les stratégies de pagination et les bonnes pratiques de stockage local. Pour les endpoints nécessitant une authentification ou une signature, un hardware wallet OneKey peut t’aider à signer de manière plus sûre, sans exposer ta clé privée à tes scripts.

Vue d’ensemble de l’API de données historiques Hyperliquid

D’après la documentation officielle Hyperliquid, la majorité des endpoints de données historiques passent par POST /info. Le champ type dans le corps de la requête permet de choisir le type de données à récupérer.

Tous les timestamps sont exprimés en Unix timestamp en millisecondes, donc sous forme d’entiers à 13 chiffres.

Récupérer les données K-line / OHLCV

Format de requête

import requests

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

def fetch_candles(coin, interval, start_ms, end_ms):
    """
    coin      : paire de trading, par exemple "BTC"
    interval  : granularité, par exemple "1m", "5m", "1h", "1d"
    start_ms  : heure de début, en timestamp millisecondes
    end_ms    : heure de fin, en timestamp millisecondes
    """
    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()

# Exemple : récupérer les chandeliers BTC en 1h sur les 7 derniers jours
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)

Champs retournés

Chaque chandelier contient généralement les champs suivants, selon la nomenclature de la documentation officielle :

t : heure de début du chandelier, en millisecondes
o : prix d’ouverture, open
h : plus haut, high
l : plus bas, low
c : prix de clôture, close
v : volume
n : nombre de trades

Stratégie de pagination

Une requête unique a en général une limite de résultats. Pour récupérer une longue période, il vaut mieux découper la plage temporelle en plusieurs segments :

import time

def fetch_candles_paginated(coin, interval, start_ms, end_ms, page_size_ms):
    """
    Découpe la plage temporelle en plusieurs blocs, puis fusionne les résultats.

    page_size_ms : durée de chaque bloc en millisecondes, à ajuster selon l'intervalle.
    """
    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 page suivante commence juste après le timestamp du dernier chandelier
        cursor = batch[-1]["t"] + 1

        time.sleep(0.2)  # évite de déclencher trop facilement le rate limit

    return all_candles

Historique des funding rates

Le funding rate est un mécanisme central des contrats perpétuels. Son historique est utile pour analyser le sentiment de marché, étudier le coût de portage ou construire des modèles d’arbitrage.

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()

Les données retournées incluent en général la valeur du funding rate pour chaque période de règlement, avec le timestamp correspondant. Cet historique peut servir à :

analyser l’évolution de la pression long / short ;
repérer des périodes de sentiment extrême ;
estimer le coût de détention d’une position perpétuelle ;
comparer différents régimes de marché.

Trades utilisateur et historique d’ordres

Les données publiques de marché ne nécessitent généralement pas d’authentification. En revanche, les données privées liées à un utilisateur peuvent demander une adresse de wallet, et certains endpoints peuvent nécessiter une signature.

C’est là qu’un hardware wallet OneKey devient utile : il peut signer les requêtes d’authentification de manière plus sûre, tandis que la clé privée reste stockée dans l’élément sécurisé du wallet et n’est pas exposée au script de collecte.

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()

Les exécutions utilisateur peuvent inclure des champs comme l’ID d’ordre, le sens de l’ordre, le prix d’exécution, la taille, les frais ou encore le marché concerné. C’est une base importante pour calculer le PnL réel, mesurer le slippage et évaluer la qualité d’exécution d’une stratégie.

Données de liquidations

Les liquidations au niveau du marché sont utiles pour étudier les phases de stress, les cascades de liquidation et certaines caractéristiques de la microstructure.

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()

Ces données peuvent aider à identifier des périodes d’excès de levier, mais elles doivent être interprétées avec prudence : une liquidation passée ne constitue pas à elle seule un signal de trading fiable.

Stockage des données : CSV ou base de données

Stocker en CSV

Pour un prototype rapide, le CSV reste la solution la plus 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})

Le CSV est pratique pour explorer rapidement les données avec Python, pandas ou un tableur. En revanche, il devient moins confortable dès que tu accumules plusieurs marchés, plusieurs timeframes et des millions de lignes.

Stocker dans une base de données

Pour un volume plus important ou des requêtes plus efficaces, SQLite peut suffire en local. Pour une stack plus robuste en production, PostgreSQL est souvent préférable.

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 clé primaire PRIMARY KEY (coin, interval, t) évite d’insérer deux fois le même chandelier. C’est particulièrement utile si tu fais des mises à jour incrémentales ou si tu relances un job après une erreur réseau.

Rate limits et points d’attention

L’API Hyperliquid applique des limites de fréquence. Les détails peuvent évoluer : réfère-toi toujours à la documentation officielle au moment de développer ton intégration.

Bonnes pratiques :

ajoute un délai entre les requêtes en boucle, par exemple 200 à 500 ms ;
implémente un mécanisme de retry avec backoff exponentiel ;
en cas de HTTP 429, attends avant de relancer la requête ;
récupère les gros historiques plutôt en dehors des périodes de forte activité ;
mets en cache localement ce que tu as déjà téléchargé ;
évite de redemander plusieurs fois la même plage temporelle.

Pour une stratégie quantitative, la fiabilité du pipeline de données compte autant que le modèle. Un dataset incomplet ou mal aligné peut produire des résultats de backtest trompeurs.

Comparaison avec d’autres sources de données

L’avantage principal de l’API native Hyperliquid est d’accéder à la source la plus directe pour les données de la plateforme, avec une latence faible et une cohérence forte avec les marchés Hyperliquid.

Pour des projets de recherche multi-exchanges, tu peux aussi combiner ces données avec d’autres sources. Les documentations de dYdX et GMX proposent également leurs propres endpoints historiques. Le design des APIs diffère, mais les concepts restent proches : chandeliers, trades, funding, positions, liquidations et données utilisateur.

Utiliser OneKey Perps dans ton workflow

Une fois tes données collectées et analysées, tu peux passer de la recherche à l’exécution avec un workflow plus simple via OneKey Perps. L’idée n’est pas de promettre une performance, mais de réduire les frictions entre :

la protection de tes actifs avec OneKey ;
l’analyse des données Hyperliquid ;
l’exécution de positions perpétuelles ;
le suivi de tes trades et de ton risque.

Si tu veux tester ce flux de travail, télécharge l’application OneKey, connecte ton wallet, puis utilise OneKey Perps pour accéder aux marchés perpétuels compatibles. Commence avec de petites tailles, vérifie chaque signature et garde en tête que l’effet de levier augmente fortement le risque de perte.

FAQ

Q1 : Quelle est la plus petite granularité disponible pour les K-lines ?

Réponse : consulte l’endpoint candleSnapshot dans la documentation officielle Hyperliquid. À ce jour, plusieurs granularités sont prises en charge, notamment des intervalles en minutes, en heures et en jours. Les valeurs exactes de interval doivent être vérifiées dans la documentation, et l’API renverra une erreur si le paramètre n’est pas valide.

Q2 : Jusqu’où peut-on remonter dans l’historique ?

Réponse : en principe, les données disponibles depuis le lancement des marchés concernés peuvent être récupérées via l’API. En pratique, la profondeur dépend de la date de mise en ligne de chaque marché et des données réellement disponibles. Si aucune donnée n’existe sur une période donnée, l’API peut retourner un tableau vide.

Q3 : Combien de temps faut-il pour récupérer un gros historique ?

Réponse : cela dépend de la période, de la granularité et de ta stratégie de pagination. Pour des chandeliers 1h sur un long historique, en tenant compte des limites de fréquence, le téléchargement peut prendre de quelques minutes à plusieurs dizaines de minutes. Le mieux est de stocker les données localement, puis de faire des mises à jour incrémentales.

Q4 : À quoi sert OneKey dans la récupération de données ?

Réponse : les données publiques comme les chandeliers ou les funding rates ne nécessitent généralement pas d’authentification. En revanche, les données privées, comme les exécutions ou l’historique d’ordres d’un utilisateur, peuvent demander une vérification par signature. Un hardware wallet OneKey permet de signer plus sûrement ce type de requête sans exposer la clé privée au serveur ou au script de collecte.

Q5 : Comment gérer les trous de données ?

Réponse : des erreurs réseau, des timeouts ou des limitations API peuvent créer des gaps. Enregistre les plages temporelles déjà récupérées, scanne régulièrement ta base pour repérer les trous, puis relance des jobs ciblés pour les combler. Avant tout backtest sérieux, fais une vérification d’intégrité : timestamps manquants, doublons, chandeliers incohérents, volumes anormaux.

Conclusion

L’API de données historiques Hyperliquid fournit une base solide pour la recherche quantitative : chandeliers OHLCV, funding rates, exécutions utilisateur et liquidations peuvent être intégrés avec quelques dizaines de lignes de Python. En ajoutant un stockage propre, une pagination robuste et une gestion prudente des rate limits, tu peux construire un pipeline exploitable pour l’analyse et le backtesting.

Pour les données privées ou les flux nécessitant une signature, OneKey peut renforcer la sécurité en gardant ta clé privée hors de tes scripts. Et si tu veux ensuite passer de l’analyse à l’exécution, OneKey Perps offre un workflow pratique pour trader des perpétuels depuis l’écosystème OneKey. Télécharge OneKey, connecte ton wallet et teste OneKey Perps avec prudence, en gardant le contrôle de ton risque.

Avertissement sur les risques : les données historiques reflètent uniquement les conditions de marché passées et ne préjugent pas des performances futures. Les stratégies quantitatives basées sur l’historique peuvent être sur-optimisées, et les résultats réels peuvent différer fortement des backtests. Le trading de contrats perpétuels comporte un risque élevé et peut entraîner une perte de capital. Ce contenu est fourni à des fins d’apprentissage technique uniquement et ne constitue pas un conseil financier, juridique ou d’investissement.