Débuter avec l’API Hyperliquid : guide 2026 pour les débutants

6 mai 2026

hyperliquid api
guide hyperliquid api
tutoriel API Hyperliquid
API de trading on-chain

Si tu veux participer au trading de contrats perpétuels on-chain de manière programmatique, l’API Hyperliquid fait partie des options les plus proches de l’expérience d’un exchange centralisé parmi les DEX on-chain. Elle donne accès aux données de marché, à la gestion de compte, aux ordres, ainsi qu’à des flux WebSocket en temps réel. De quoi couvrir des usages allant d’un simple bot quantitatif à une infrastructure de market making plus avancée.

Ce guide s’adresse aux développeurs qui découvrent l’API Hyperliquid. On va passer en revue la structure des endpoints, le modèle d’authentification, quelques exemples de démarrage et les erreurs fréquentes à éviter.

Ce que permet l’API Hyperliquid

D’après la documentation officielle d’Hyperliquid, l’API se divise principalement en trois catégories :

Info Endpoints : ces endpoints servent à récupérer les données de marché et de compte, comme le carnet d’ordres actuel, les transactions récentes, l’historique des funding rates, les positions d’un compte ou encore les ordres passés. Ils ne nécessitent pas de signature et sont accessibles publiquement.

Exchange Endpoints : ces endpoints permettent d’effectuer des actions d’écriture, comme placer un ordre, annuler un ordre, modifier l’effet de levier d’une position ou ajuster la marge. Ils nécessitent une signature wallet du corps de requête et demandent donc une attention particulière côté sécurité.

WebSocket en temps réel : le WebSocket permet de s’abonner aux mises à jour du carnet d’ordres, aux trades, aux événements de compte et à d’autres flux temps réel. C’est indispensable pour les stratégies qui ont besoin d’une latence plus faible.

URL de base et structure de l’API

L’URL de base de l’API REST Hyperliquid est :

https://api.hyperliquid.xyz

Toutes les requêtes utilisent la méthode POST, avec un corps JSON. Les endpoints de type Info sont envoyés vers /info, tandis que les endpoints de trading sont envoyés vers /exchange.

Les champs exacts et leur format doivent toujours être vérifiés dans la documentation officielle. Les exemples ci-dessous servent uniquement à comprendre la logique de base ; avant toute utilisation réelle, prends le temps de comparer avec la version la plus récente de la documentation.

Authentification

Les endpoints de trading d’Hyperliquid utilisent une signature de données structurées EIP-712, et non un modèle classique API Key + Secret. Concrètement :

tu as besoin d’une adresse compatible Ethereum comme identité ;
chaque requête de trading doit être signée avec la clé privée correspondante ;
la signature prouve directement que la requête vient du détenteur autorisé de cette adresse, sans passer par une clé API intermédiaire.

Ce modèle est plus robuste sur le principe : il n’y a pas de clé API centralisée à voler, et l’autorisation dépend directement de la signature cryptographique. Mais il augmente aussi l’importance de la gestion des clés privées. Si une clé privée est compromise, un attaquant peut générer des signatures valides et contrôler le compte concerné.

C’est précisément là que OneKey Wallet devient utile. Avec un hardware wallet OneKey, la clé privée reste isolée dans une puce sécurisée, et la signature se fait à l’intérieur de l’appareil. La clé privée n’est jamais exposée à l’ordinateur ou au réseau.

Pour les traders quantitatifs ou développeurs qui appellent fréquemment une API de trading, une approche prudente consiste à utiliser OneKey pour créer une clé dédiée ou un compte séparé destiné aux opérations API, sans exposer le compte principal.

Exemple de requête Info : Python + curl

Voici un exemple simple pour récupérer les métadonnées de tous les actifs tradables.

Avec curl :

curl -X POST https://api.hyperliquid.xyz/info \
-H "Content-Type: application/json" \
-d '{"type": "meta"}'

Avec Python et la bibliothèque requests :

import requests
import json

url = "https://api.hyperliquid.xyz/info"
payload = {"type": "meta"}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(json.dumps(data, indent=2))

La réponse contient les informations de base sur les contrats disponibles : nom de l’actif, effet de levier maximal, taille minimale d’ordre, etc. Ce type de requête est public et ne nécessite aucune authentification, ce qui en fait un excellent point de départ pour découvrir l’API Hyperliquid.

Consulter les positions d’un compte

La consultation de l’état des positions d’une adresse fait aussi partie des endpoints Info. Il suffit de fournir l’adresse du wallet :

payload = {
    "type": "clearinghouseState",
    "user": "0xYOUR_WALLET_ADDRESS"
}

response = requests.post(url, json=payload, headers=headers)

La réponse inclut notamment le solde de marge, les positions ouvertes par contrat et le PnL non réalisé. Attention : il s’agit de données on-chain publiquement consultables. N’importe qui peut interroger l’état des positions d’une adresse.

Abonnement WebSocket en temps réel

L’endpoint WebSocket est :

wss://api.hyperliquid.xyz/ws

Une fois la connexion ouverte, tu peux envoyer un message de souscription pour commencer à recevoir les données en temps réel :

import asyncio
import websockets
import json

async def subscribe_orderbook():
    uri = "wss://api.hyperliquid.xyz/ws"

    async with websockets.connect(uri) as ws:
        sub_msg = {
            "method": "subscribe",
            "subscription": {
                "type": "l2Book",
                "coin": "BTC"
            }
        }

        await ws.send(json.dumps(sub_msg))

        while True:
            msg = await ws.recv()
            data = json.loads(msg)
            print(data)

asyncio.run(subscribe_orderbook())

Les types de flux disponibles peuvent inclure le carnet d’ordres L2 (l2Book), les trades récents (trades), les événements de compte (userEvents, avec adresse authentifiée) et les données globales de funding rate.

Pièges fréquents

Format JSON incorrect
C’est l’une des causes d’erreur les plus courantes. L’API Hyperliquid est stricte sur le nommage et le type des champs JSON. Un entier envoyé sous forme de chaîne de caractères, ou un champ mal nommé, peut entraîner un rejet de la requête. Les messages d’erreur ne sont pas toujours évidents, donc il faut souvent revenir à la documentation officielle et vérifier champ par champ.

Construction de la signature
Les signatures EIP-712 impliquent des définitions de types, un domaine de signature et plusieurs détails faciles à mal implémenter. Si tu débutes, évite de tout recoder à la main. Il est préférable d’utiliser un SDK Hyperliquid maintenu par la communauté ou par l’équipe officielle, en Python ou JavaScript, afin de réduire le risque d’erreur.

Synchronisation de l’horloge
Les requêtes de trading nécessitent généralement un timestamp récent, avec une fenêtre de validité limitée. Si l’horloge locale de ta machine dérive trop par rapport au temps réseau, certaines requêtes peuvent être rejetées comme expirées.

Gestion des coupures réseau
En production, les déconnexions WebSocket et les erreurs REST temporaires sont normales. Ton code doit intégrer une logique de reconnexion automatique, de retry contrôlé et de gestion des états intermédiaires. Ne pars jamais du principe qu’une connexion restera stable indéfiniment.

Aperçu des limites de taux

Hyperliquid applique des limites de taux différentes selon les types d’endpoints. Les valeurs exactes doivent être vérifiées dans la version la plus récente de la documentation officielle.

En règle générale, les endpoints Info sont plus permissifs, tandis que les endpoints Exchange liés aux ordres sont plus stricts. Les stratégies qui placent et annulent des ordres très fréquemment doivent donc être conçues avec prudence.

Si tu reçois une erreur 429, il faut arrêter temporairement les requêtes et appliquer une stratégie d’exponential backoff, plutôt que de retenter immédiatement en boucle.

Recommandations pour l’environnement de développement

Avant de déployer une stratégie avec de vrais montants, il est fortement recommandé de :

Tester avec de très petites tailles de position
Ne lance pas directement une stratégie avec un capital important. Hyperliquid ne disposerait pas, à ce jour selon les informations disponibles, d’un testnet séparé pour tester le trading de perpétuels. Les premiers essais doivent donc se faire avec une exposition strictement limitée.

Séparer la clé de signature du compte principal
Crée une adresse ou un sous-compte dédié au trading API, avec un risque maximal que tu es prêt à accepter. Les fonctions de gestion multi-comptes de OneKey Wallet peuvent aider à organiser cette séparation entre compte principal, compte de test et compte de trading automatisé.

Utiliser OneKey Perps comme workflow pratique
Pour un usage plus simple et contrôlé, OneKey Perps peut servir de workflow pratique pour accéder au trading de perpétuels tout en gardant une logique de gestion de wallet claire. Si tu débutes, cela peut être plus lisible que de commencer directement par une infrastructure API complète.

Télécharger OneKey et préparer ton setup de sécurité
Tu peux essayer OneKey sur desktop ou mobile, puis configurer des comptes séparés selon tes usages : conservation long terme, opérations manuelles, tests API ou trading de perpétuels via OneKey Perps. L’objectif n’est pas de promettre de meilleures performances, mais de réduire les risques opérationnels liés à la gestion des clés.

Consulter les références open source
Le GitHub de OneKey peut aussi servir de référence pour comprendre comment intégrer la signature wallet de manière plus sûre au niveau applicatif.

FAQ

Q1 : Faut-il créer un compte pour utiliser l’API Hyperliquid ?

Pas au sens traditionnel. Tu as besoin d’une adresse compatible Ethereum. Une fois que cette adresse a effectué sa première opération sur Hyperliquid, par exemple un dépôt, elle peut être utilisée avec l’API. Le processus ne nécessite pas d’inscription par e-mail ni de KYC.

Q2 : Existe-t-il un SDK Python pour l’API Hyperliquid ?

Oui, il existe des SDK Python maintenus par la communauté et/ou par l’écosystème officiel. Le plus prudent est de consulter la page GitHub officielle d’Hyperliquid pour trouver la version actuellement maintenue. Utiliser un SDK simplifie fortement la signature EIP-712 et le formatage des requêtes.

Q3 : Comment reconnecter automatiquement un WebSocket ?

Il est recommandé d’implémenter un heartbeat, par exemple avec des pings réguliers, ainsi qu’une logique de reconnexion automatique. Après une déconnexion, attends brièvement — par exemple 1 à 5 secondes — avant de te reconnecter et de te réabonner aux canaux nécessaires. En production, une stratégie d’exponential backoff est préférable pour éviter de surcharger le service pendant une panne.

Q4 : Comment sécuriser les fonds utilisés pour le trading API ?

La sécurité dépend avant tout de la manière dont la clé privée est protégée. Un hardware wallet OneKey permet de signer sans exposer la clé privée à un appareil connecté, ce qui apporte une isolation matérielle importante. Il reste aussi recommandé de limiter la taille des positions sur le compte API, de surveiller régulièrement les ordres ouverts et de vérifier l’état des positions.

Q5 : L’API Hyperliquid prend-elle en charge les ordres conditionnels et les stop-loss ?

Hyperliquid prend en charge les Trigger Orders, qui peuvent couvrir des logiques de stop-loss et de take-profit. Les paramètres exacts et les conditions de déclenchement doivent être vérifiés dans la documentation officielle, notamment dans la section consacrée aux types d’ordres. Pour des logiques plus complexes, tu peux aussi les gérer au niveau de ta stratégie en surveillant les positions et le marché.

Conclusion

L’API Hyperliquid offre aux développeurs un ensemble d’outils complet pour interagir avec un DEX de perpétuels on-chain : données de marché via les endpoints Info, exécution via les endpoints Exchange, et flux temps réel via WebSocket.

Mais cette puissance vient avec des responsabilités. Le modèle de signature EIP-712 impose de prendre la gestion des clés privées très au sérieux. Utiliser OneKey Wallet comme base de signature peut aider à isoler les clés au niveau matériel, aussi bien pour les opérations manuelles que pour les workflows liés au trading API.

Si tu prépares tes premiers développements autour d’Hyperliquid, prends le temps de configurer un environnement propre : petits montants, comptes séparés, surveillance des erreurs et gestion prudente des signatures. Tu peux télécharger OneKey, configurer tes comptes, puis utiliser OneKey Perps comme workflow pratique pour explorer les perpétuels avec une meilleure hygiène de sécurité.

Avertissement

Ce contenu est fourni uniquement à titre technique et informatif. Il ne constitue pas un conseil financier, juridique ou d’investissement. Le trading via API comporte des risques d’automatisation : une erreur de stratégie, de code ou de configuration peut entraîner des pertes importantes et inattendues. Les contrats perpétuels utilisent souvent de l’effet de levier et présentent un niveau de risque élevé. Évalue soigneusement les risques techniques et de marché avant toute participation. Les performances passées d’une stratégie ne préjugent pas des résultats futurs.