La plateforme Hyperliquid se distingue comme un échange décentralisé haute performance pour les contrats à terme perpétuels, offrant un trading à faible latence et des fonctionnalités avancées pour les développeurs. Les développeurs se tournent fréquemment vers l'API Hyperliquid pour automatiser les transactions, surveiller les marchés et créer des applications personnalisées.
Vous commencez par comprendre les composants essentiels de l'API Hyperliquid. L'API se divise en catégories clés : l'API d'information (Info API) pour interroger les données de marché, l'API d'échange (Exchange API) pour les actions de trading, et WebSocket pour les mises à jour en temps réel. De plus, les SDK dans des langages comme Python et Node.js simplifient les interactions. Au fur et à mesure, vous verrez comment de petits ajustements dans les paramètres de requête conduisent à des améliorations significatives de l'efficacité d'exécution.
Qu'est-ce que l'API Hyperliquid ?
L'API Hyperliquid permet un accès programmatique à l'échange décentralisé de contrats perpétuels d'Hyperliquid. Elle prend en charge les opérations sur les environnements mainnet et testnet. Vous vous connectez à mainnet et à testnet z. L'API utilise JSON pour les requêtes et les réponses, s'appuyant sur HTTP POST pour la plupart des actions et sur WebSocket pour les abonnements.
Vous vous authentifiez en utilisant des clés privées plutôt que des clés API traditionnelles dans certains cas, mais Hyperliquid propose également des portefeuilles API pour une délégation sécurisée. Ces portefeuilles agissent au nom de votre compte principal sans autorisations de retrait, améliorant la sécurité pour le trading automatisé. Par exemple, vous générez un portefeuille API via l'application Hyperliquid, l'autorisez et utilisez sa clé privée dans vos scripts.
Ensuite, considérez les types de données. L'API utilise des structs et des enums spécifiques. Les actifs sont identifiés par des indices de la liste d'univers, les côtés des ordres utilisent des booléens (vrai pour l'achat, faux pour la vente), et les options de durée de validité incluent 'Gtc' pour "good 'til canceled" (bon jusqu'à annulation). Vous récupérez ces détails à partir des points de terminaison de métadonnées pour garantir la précision de vos requêtes.
Avec cette base, vous passez à la configuration de votre environnement de développement. Une configuration appropriée prévient les erreurs courantes et accélère l'itération.
Configuration de votre environnement pour l'API Hyperliquid
Vous commencez la configuration en choisissant votre langage de programmation et en installant le SDK pertinent. Pour les utilisateurs de Python, le hyperliquid-python-sdk offre un point de départ robuste. Installez-le via pip avec la commande pip install hyperliquid-python-sdk. Ce SDK gère les connexions, l'authentification et les opérations courantes.
Vous configurez ensuite vos identifiants. Créez un fichier config.json avec l'adresse de votre compte (clé publique) et votre clé secrète (clé privée). Pour des raisons de sécurité, vous générez un portefeuille API dédié. Naviguez vers l'application Hyperliquid, sélectionnez "Plus > API", entrez un nom pour la clé, collez l'adresse de votre portefeuille et cliquez sur "Générer". Autorisez le portefeuille API et copiez sa clé privée dans votre configuration.
Le SDK importe des constantes pour les URL, telles que constants.TESTNET_API_URL pour les tests. Vous initialisez les clients comme ceci :
from hyperliquid.info import Info
from hyperliquid.utils import constants
info = Info(constants.TESTNET_API_URL, skip_ws=True)
Cette configuration ignore initialement WebSocket, se concentrant sur HTTP. Vous testez la connexion en interrogeant l'état de l'utilisateur :
user_state = info.user_state("your_account_address")
print(user_state)
Si la réponse affiche les détails de votre compte, votre environnement fonctionne correctement. Cependant, si vous rencontrez des erreurs, vérifiez votre clé privée et la sélection du réseau.
Pour Node.js, vous utilisez le package @nktkas/hyperliquid. Installez-le avec npm, puis configurez les transports et les clients en utilisant ethers pour la gestion du portefeuille. Vous spécifiez isTestnet: true pour éviter d'utiliser des fonds réels pendant le développement.
Des outils comme Apidog complètent cette configuration. Vous importez les spécifications de l'API Hyperliquid dans Apidog, vous authentifiez avec vos clés et simulez des requêtes. Cette approche révèle rapidement les structures de réponse, ce qui permet de gagner du temps sur le codage manuel.
Une fois configuré, vous passez aux méthodes d'authentification. Une authentification appropriée garantit que vos actions s'exécutent en toute sécurité.
Authentification avec l'API Hyperliquid
Vous vous authentifiez principalement par signature de clé privée, car Hyperliquid fonctionne sur un système basé sur la blockchain. Les SDK gèrent la signature automatiquement lorsque vous fournissez une instance de portefeuille.
Pour les appels API directs sans SDK, vous signez les payloads en utilisant votre clé privée. Le corps de la requête inclut un nonce pour la protection contre la relecture, et vous postez vers les points de terminaison /exchange ou /info.
Les portefeuilles API ajoutent de la flexibilité. Vous en créez un en le nommant, en le liant à l'adresse de votre portefeuille principal, en générant la clé et en l'autorisant. Ce portefeuille effectue des transactions mais ne peut pas retirer de fonds, réduisant ainsi les risques pour les bots. Dans le code, vous utilisez la clé privée du portefeuille API tout en spécifiant l'adresse du compte principal.
Vous testez l'authentification en envoyant une simple requête d'information. Si non autorisé, l'API renvoie une erreur comme "L'utilisateur ou le portefeuille API n'existe pas." Pour corriger cela, assurez-vous que votre portefeuille détient un collatéral minimum, tel que de l'USDC pour les perpétuels.
La sécurité reste primordiale. Vous stockez les clés dans des variables d'environnement ou des coffres-forts sécurisés, les faites pivoter périodiquement et surveillez toute activité inhabituelle. Une fois l'authentification en place, vous explorez les points de terminaison de l'API d'information.
Exploration des points de terminaison de l'API d'information
L'API d'information (Info API) fournit un accès en lecture seule aux données de marché et de compte. Vous l'utilisez pour récupérer des métadonnées, des prix, des ordres, et plus encore, sans authentification pour les données publiques.
Vous commencez par le point de terminaison meta, qui renvoie l'univers des actifs et les contextes. En Node.js :
const [meta] = await infoClient.metaAndAssetCtxs();
Ceci produit un tableau d'actifs avec des noms, des indices et des spécifications comme le levier maximal. Vous utilisez l'indice de l'actif dans les requêtes de trading.
Ensuite, vous interrogez les prix médians avec allMids, qui renvoie les points médians actuels pour toutes les paires. Les ordres ouverts proviennent de openOrders, nécessitant votre adresse.
D'autres points de terminaison incluent :
- userState : Récupère les positions, les marges et les soldes.
- fundingHistory : Affiche les taux de financement au fil du temps.
- l2Book : Fournit le carnet d'ordres de niveau 2 pour une pièce.
Vous envoyez des requêtes POST avec des corps JSON comme {"type": "meta"} à /info. Les réponses utilisent des structures cohérentes, avec "data" contenant les résultats.
Apidog aide ici—vous configurez une collection pour l'API d'information, ajoutez des requêtes pour chaque type et paramétrez les pièces ou les adresses. Cette visualisation facilite la compréhension du flux de données.
Au fur et à mesure que vous collectez des données, vous passez à l'API d'échange pour exécuter des transactions.
Utilisation des points de terminaison de l'API d'échange pour le trading
L'API d'échange gère des actions comme la passation, l'annulation et la modification d'ordres. Vous authentifiez toutes les requêtes avec des charges utiles signées.
Vous passez des ordres en définissant des paramètres : indice de l'actif, côté, prix, taille, drapeau "reduce-only" et type (limite ou marché). Pour une vente à cours limité :
En Elixir (d'après la documentation du SDK) :
Hyperliquid.Api.Exchange.place_order(order)
Où "order" est une map avec a : actif, b : false (vente), p : "100", s : "0.1", r : false, t : {limit: {tif: "Gtc"}}.
La réponse inclut le statut et l'ID de l'ordre en cas de succès.
Vous annulez les ordres en utilisant l'actif et l'oid (ID de l'ordre) :
Hyperliquid.Api.Exchange.cancel_order(asset, oid)
Pour les lots, vous utilisez cancel_orders avec une liste.
Les modifications suivent un processus similaire : spécifiez l'oid et les nouveaux paramètres.
D'autres actions incluent la mise à jour du levier :
Hyperliquid.Api.Exchange.update_leverage(asset, is_cross, leverage)
Et les transferts, comme spot_perp_transfer pour déplacer des fonds entre les comptes.
Vous gérez les erreurs en vérifiant le statut de la réponse — "ok" pour le succès, sinon des détails comme une marge insuffisante.
Des exemples démontrent une utilisation pratique. Par exemple, vous construisez un bot qui place un ordre d'achat lorsque le prix tombe en dessous d'un seuil, en utilisant l'API d'information pour les vérifications de prix et l'API d'échange pour le placement.
De plus, vous intégrez WebSocket pour des mises à jour en temps réel afin d'améliorer la réactivité.
Intégration de WebSocket pour les données en temps réel
Vous vous connectez à WebSocket pour les flux en direct. Utilisez wss://api.hyperliquid.xyz/ws pour le mainnet ou l'équivalent testnet.
Vous vous abonnez en envoyant du JSON : {"method": "subscribe", "subscription": {"type": "trades", "coin": "SOL"}}.
Le serveur répond par une confirmation, puis envoie des mises à jour comme de nouvelles transactions.
Vous gérez des sujets tels que le carnet d'ordres, les événements utilisateur et les notifications. Dans le SDK Python, définissez skip_ws=False pour activer.
Cette capacité en temps réel vous permet de réagir instantanément aux changements du marché, comme l'ajustement des ordres lors des exécutions.
Les points de terminaison étant couverts, vous examinez le SDK Python en profondeur.
Tirer parti du SDK Python Hyperliquid
Le SDK Python abstrait les appels API en classes. Vous importez Info pour les requêtes et Exchange pour les actions.
Vous passez un ordre de base comme ceci (d'après les exemples) :
Tout d'abord, chargez la configuration :
import json
def address_and_private_key():
with open("examples/config.json") as f:
config = json.load(f)
return config["account_address"], config["secret_key"]
Ensuite, initialisez l'échange :
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
address, private = address_and_private_key()
exchange = Exchange(address, private, base_url=constants.TESTNET_API_URL)
Passez l'ordre :
order_result = exchange.order("BTC", True, 0.02, 30000, {"limit": {"tif": "Gtc"}})
print(order_result)
Ceci achète 0,02 BTC à 30 000 $ en ordre limite.
Vous étendez cela pour des fonctionnalités avancées, comme les ordres groupés ou les annulations.
Le SDK prend également en charge les adresses de coffre-fort pour les comptes gérés.
Les exemples dans le dépôt couvrent basic_order, user_state, et plus encore, démontrant des flux de travail complets.
Au fur et à mesure que vous construisez, vous intégrez les meilleures pratiques pour optimiser les performances.
Bonnes pratiques pour l'utilisation de l'API Hyperliquid
Vous surveillez les limites de débit pour éviter la limitation—Hyperliquid applique des limites par IP et par compte.
Vous utilisez le testnet pour tout développement afin de prévenir les pertes financières.
La gestion des erreurs implique la journalisation des détails et la nouvelle tentative des échecs transitoires avec un délai d'attente exponentiel.
Pour l'évolutivité, vous regroupez les requêtes lorsque cela est possible, comme plusieurs annulations.
La sécurité s'étend à l'utilisation de portefeuilles API et aux principes du moindre privilège.
Vous versionnez également votre code avec les mises à jour du SDK, car Hyperliquid suit la gestion sémantique des versions.
Des outils comme Apidog aident à simuler des réponses pour les tests unitaires.
Le dépannage intervient ensuite lorsque des problèmes surviennent.
Dépannage des problèmes courants de l'API Hyperliquid
Vous rencontrez "Marge insuffisante" lorsque le collatéral est faible—déposez de l'USDC pour résoudre le problème.
Si "Actif introuvable", vérifiez les indices à partir des métadonnées.
Les erreurs d'authentification proviennent de clés invalides—régénérez et autorisez les portefeuilles API.
Les problèmes de réseau nécessitent de vérifier les URL et d'utiliser des proxys si nécessaire.
Vous déboguez avec Apidog en rejouant les requêtes échouées.
Les journaux des SDK fournissent des horodatages et des charges utiles pour l'analyse.
Grâce à ces conseils, vous maintenez des intégrations fiables.
Cas d'utilisation avancés avec l'API Hyperliquid
Vous construisez des bots de trading qui surveillent le l2Book et placent des ordres sur les déséquilibres.
Les stratégies impliquent les taux de financement historiques pour les opportunités d'arbitrage.
Les sous-comptes permettent un trading ségrégué : créez avec un nom, transférez des fonds et tradez séparément.
Les transferts de coffre-fort prennent en charge les pools de liquidité partagés.
Vous simulez avec des données historiques de l'API pour le backtesting.
L'intégration avec Apidog permet un débogage collaboratif en équipe.
Enfin, vous concluez en considérant les améliorations futures.
Conclusion : Maîtriser l'API Hyperliquid pour le trading décentralisé
Vous possédez désormais les connaissances nécessaires pour utiliser efficacement l'API Hyperliquid. De la configuration et l'authentification aux points de terminaison et aux SDK, ce guide vous équipe pour construire des applications sophistiquées. N'oubliez pas que les raffinements incrémentiels de votre code produisent des gains de performance substantiels. Expérimentez sur le testnet, tirez parti d'outils comme Apidog et restez informé des documents d'Hyperliquid. À mesure que la plateforme évolue, vos compétences vous positionnent pour capitaliser sur les nouvelles fonctionnalités.