Faire du trading programmatique avec le SDK Hyperliquid

6 mai 2026

hyperliquid sdk
hyperliquid programmatic trade
hyperliquid python sdk
hyperliquid api trading programmatique
bot de contrats perpétuels on-chain

Le trading programmatique n’est plus réservé aux desks institutionnels. Aujourd’hui, toute personne à l’aise avec un minimum de code peut automatiser une partie de son activité de trading. Hyperliquid, en tant que plateforme de contrats perpétuels on-chain, propose des interfaces REST et WebSocket complètes, ainsi que des SDK maintenus par l’équipe officielle et la communauté. En quelques dizaines de lignes, tu peux passer des ordres, consulter tes positions, gérer les erreurs et construire un flux de trading automatisé.

Dans cet article, on part de l’environnement de développement, puis on voit comment utiliser les SDK Python ou JavaScript pour bâtir un workflow de trading programmatique plus fiable. On explique aussi pourquoi, en production, intégrer un hardware wallet OneKey comme couche de signature est une étape importante pour protéger tes fonds.

Pourquoi choisir Hyperliquid pour le trading programmatique

Par rapport à une plateforme centralisée, Hyperliquid présente plusieurs avantages : le règlement des transactions se fait on-chain, les fonds n’ont pas besoin d’être confiés à un tiers, et l’architecture combine un carnet d’ordres off-chain avec un règlement on-chain. L’objectif est de rapprocher l’expérience de trading de celle d’un exchange centralisé, tout en conservant davantage de transparence et de souveraineté sur les actifs.

Pour les traders quantitatifs et les développeurs, cela signifie qu’il est possible de construire des stratégies automatisées tout en gardant une logique de self-custody. Les API sont relativement simples à utiliser, la documentation est régulièrement mise à jour, et l’écosystème développeur autour d’Hyperliquid reste actif.

Préparer l’environnement et installer le SDK

Environnement Python

À ce jour, un SDK Python maintenu par la communauté peut être installé via pip. Il est recommandé de travailler dans un environnement virtuel afin d’éviter les conflits de dépendances :

python -m venv hl_env
source hl_env/bin/activate
pip install hyperliquid-python-sdk

Le code source du SDK est hébergé dans des dépôts liés à l’écosystème OneKey ainsi que dans l’organisation officielle Hyperliquid. Consulte toujours la documentation officielle pour obtenir l’adresse du dépôt la plus récente.

Environnement JavaScript / TypeScript

Si tu préfères Node.js :

npm install @nktkas/hyperliquid
# ou utilise le package officiellement maintenu, selon la dernière version disponible sur npm

Les développeurs TypeScript peuvent importer directement les définitions de types, ce qui rend l’autocomplétion dans l’IDE plus confortable.

Connexion à l’API et initialisation du client

Authentification

Hyperliquid utilise une signature par clé privée pour authentifier les requêtes de trading. Chaque ordre doit être signé avec la clé privée du wallet selon le format structuré EIP-712, afin de garantir que la requête ne puisse pas être falsifiée.

Exemple Python, sous forme de pseudo-code :

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

# Lis la clé privée depuis une variable d’environnement. Ne la mets jamais en dur dans le code.
private_key = os.environ["HL_PRIVATE_KEY"]

account = Account.from_key(private_key)

info = Info(base_url="https://api.hyperliquid.xyz")
exchange = Exchange(account, base_url="https://api.hyperliquid.xyz")

En environnement de production, il est fortement recommandé de remplacer la clé privée logicielle par un hardware wallet OneKey. La clé privée ne quitte jamais la puce sécurisée du wallet, ce qui limite fortement le risque d’exfiltration même si le serveur est compromis. On y revient plus loin.

Consulter les données de marché et l’état du compte

Récupérer un snapshot du marché

# Récupère les métadonnées de tous les contrats perpétuels et les prix actuels
meta_and_asset_ctx = info.meta_and_asset_ctxs()

# La réponse contient notamment des champs comme markPx, funding, etc.

Consulter les positions et le solde

user_state = info.user_state(account.address)

# user_state contient marginSummary et assetPositions
for pos in user_state["assetPositions"]:
    print(pos["position"]["coin"], pos["position"]["szi"])  # paire et taille de position

Passer des ordres

Ordre au marché

order_result = exchange.market_open(
    coin="BTC",
    is_buy=True,
    sz=0.001,      # taille de l’ordre
    slippage=0.01  # slippage maximum autorisé : 1 %
)

print(order_result)

Ordre limite

order_result = exchange.order(
    coin="ETH",
    is_buy=False,
    sz=0.1,
    limit_px=3200.0,  # prix limite
    order_type={"limit": {"tif": "Gtc"}}  # Good Till Cancel
)

Le champ tif prend en charge plusieurs options, notamment Gtc pour un ordre valable jusqu’à annulation, Ioc pour exécution immédiate ou annulation, et Alo pour un ordre uniquement maker. Choisis l’option en fonction de la logique de ta stratégie.

Ordres groupés

Les stratégies de market making ou de grid trading ont souvent besoin de soumettre plusieurs ordres en une seule fois. Le SDK prend en charge les ordres groupés, ce qui réduit les allers-retours réseau :

orders = [
    {"coin": "BTC", "is_buy": True,  "sz": 0.001, "limit_px": 60000, "order_type": {"limit": {"tif": "Gtc"}}},
    {"coin": "BTC", "is_buy": False, "sz": 0.001, "limit_px": 61000, "order_type": {"limit": {"tif": "Gtc"}}},
]

result = exchange.bulk_orders(orders)

Annuler ou modifier un ordre

# L’annulation nécessite coin et oid, l’identifiant de l’ordre
cancel_result = exchange.cancel(coin="BTC", oid=123456789)

# Modification d’un ordre : cancel + replace
modify_result = exchange.modify_order(
    oid=123456789,
    coin="BTC",
    is_buy=True,
    sz=0.002,
    limit_px=59500,
    order_type={"limit": {"tif": "Gtc"}}
)

Bonnes pratiques de gestion des erreurs

En trading programmatique, la gestion des erreurs est aussi importante que la stratégie elle-même. Les problèmes fréquents incluent les erreurs réseau, les timeouts, les rejets d’ordre, les limites de fréquence ou les écarts de prix trop importants.

Exemple de logique de retry avec backoff exponentiel :

import time

def place_with_retry(exchange, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return exchange.order(**kwargs)
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)

En production, ajoute aussi des journaux détaillés, des alertes, un suivi des ordres en attente et des règles de coupure automatique si le comportement du bot s’écarte de ce qui est prévu.

Utiliser WebSocket pour suivre les exécutions en temps réel

Le polling REST peut suffire pour des stratégies peu fréquentes. Pour des scénarios plus réactifs, il vaut mieux utiliser les flux WebSocket :

from hyperliquid.websocket_manager import WebsocketManager

def on_fill(data):
    print("Callback d’exécution :", data)

ws = WebsocketManager(base_url="wss://api.hyperliquid.xyz")

ws.subscribe(
    {"type": "userFills", "user": account.address},
    callback=on_fill
)

ws.start()

Pour le format complet des abonnements WebSocket, réfère-toi à la documentation officielle d’Hyperliquid.

Protéger un bot de production avec un hardware wallet OneKey

Avec un wallet logiciel, la clé privée est stockée en mémoire ou sur disque. Si le serveur est compromis, les fonds peuvent être vidés très rapidement. Pour un bot de production qui gère des fonds réels, une architecture plus prudente consiste à :

connecter un hardware wallet OneKey à un serveur de signature ;
laisser la logique du bot générer les messages à signer ;
envoyer ces messages à OneKey pour signature dans l’élément sécurisé ;
renvoyer la signature au bot, qui soumet ensuite la requête à Hyperliquid.

Dans cette architecture, la clé privée reste dans le hardware wallet et ne peut pas être exportée par la couche logicielle. Le format de signature structurée EIP-712 permet aussi d’afficher les informations de la transaction sur l’écran OneKey, afin qu’un utilisateur puisse vérifier ce qui est signé lorsque le flux opérationnel le prévoit.

Il est également conseillé d’utiliser un wallet API Agent dédié pour le bot, lorsque la configuration Hyperliquid le permet. Le but est de limiter ce compte à des opérations spécifiques sur le compte concerné, afin de mieux contrôler l’exposition au risque.

Outils et ressources utiles

Documentation officielle Hyperliquid : spécifications d’API et description des champs
Site officiel OneKey : présentation des hardware wallets et de l’écosystème
Documentation WalletConnect : utile si tu dois intégrer une couche de signature via WalletConnect

FAQ

Q1 : Quelle est la différence entre utiliser un SDK et appeler directement l’API REST ?

Le SDK encapsule la logique de signature, le formatage des requêtes et une partie de la gestion des erreurs. Cela réduit le code répétitif. L’appel direct à l’API REST donne plus de flexibilité, mais tu dois implémenter toi-même la signature EIP-712. Pour démarrer, le SDK est généralement plus simple ; ensuite, tu peux passer à des appels HTTP natifs si ton architecture l’exige.

Q2 : Le trading programmatique sur Hyperliquid nécessite-t-il un KYC ?

Hyperliquid est un protocole décentralisé et, à ce jour, l’accès se fait via une adresse de wallet sans KYC. Cela dit, les obligations réglementaires varient selon les juridictions. Tu dois te renseigner sur les règles applicables dans ton pays ou ta région et assumer tes propres responsabilités de conformité.

Q3 : Comment éviter qu’un bot perde trop en conditions de marché extrêmes ?

Il est recommandé d’implémenter plusieurs protections au niveau de la stratégie : seuil de perte maximale avec arrêt automatique, suivi du ratio entre perte latente et valeur nette du compte, utilisation d’ordres stop-loss lorsque c’est adapté, et vérifications régulières pour confirmer que les positions réelles correspondent aux positions attendues.

Q4 : Comment intégrer un hardware wallet OneKey à un script automatisé ?

Tu peux utiliser le SDK officiel OneKey pour appeler les fonctions de signature du hardware wallet, ou connecter l’appareil en USB/Bluetooth avec une interface de type eth_sign, selon l’architecture retenue. En production, le modèle le plus propre consiste souvent à isoler le service de signature du moteur de trading, afin de réduire la surface d’attaque.

Q5 : L’interface d’ordres groupés a-t-elle des limites de fréquence ?

Consulte la documentation officielle pour connaître la politique de rate limit la plus récente. En pratique, il est préférable d’ajouter des délais raisonnables entre les requêtes et de mettre en place un mécanisme de type token bucket ou sliding window pour éviter que les ordres échouent à cause d’un dépassement de limite.

Conclusion : du script au système de production

Le SDK Hyperliquid réduit nettement la barrière d’entrée du trading programmatique. Mais passer d’un script qui fonctionne à un système de production fiable demande un vrai travail sur la sécurité de signature, la gestion des erreurs, la surveillance et les règles de risque.

Si tu veux découvrir le trading de contrats perpétuels on-chain sans écrire de code, OneKey Perps offre un point d’entrée plus simple, avec une interface claire et l’intégration de la sécurité OneKey. Et si tu développes déjà tes propres bots, utiliser OneKey comme backend de signature peut être une approche solide pour mieux gérer tes clés dans une architecture de trading on-chain.

Tu peux essayer ou télécharger OneKey depuis le site officiel, puis utiliser OneKey Perps pour explorer un workflow de trading perpétuel plus sécurisé et plus accessible.

Avertissement sur les risques : le trading programmatique implique des risques techniques et de marché importants. Les contrats perpétuels utilisent souvent de l’effet de levier et peuvent entraîner des pertes supérieures au capital initial engagé. Cet article est fourni à titre informatif et technique uniquement ; il ne constitue pas un conseil financier, juridique ou d’investissement. Assure-toi de comprendre les risques et d’agir selon ta propre tolérance au risque. Les marchés crypto sont très volatils, et les performances passées ne préjugent pas des résultats futurs.