Hyperliquid REST vs WebSocket : quand utiliser quoi ?

Beaucoup de développeurs qui intègrent l’API Hyperliquid se posent la même question : ma stratégie doit-elle utiliser REST ou WebSocket ? Les deux interfaces reposent sur des mécanismes très différents et ne répondent pas aux mêmes besoins. Un mauvais choix peut simplement gaspiller de la bande passante, mais il peut aussi dégrader la réactivité de ta stratégie et provoquer plus de slippage que prévu.

Dans cet article, on décortique le fonctionnement de REST et de WebSocket sur Hyperliquid, leurs cas d’usage, leurs caractéristiques de latence et les pièges courants, afin de t’aider à choisir la bonne approche.

REST API : le modèle requête-réponse

REST, pour Representational State Transfer, est le modèle HTTP classique : le client envoie une requête, le serveur renvoie une réponse, puis la connexion se termine. C’est un échange ponctuel, en mode « question-réponse ».

Dans la documentation Hyperliquid, les endpoints REST se répartissent principalement en deux catégories.

Les endpoints Info (/info) gèrent les requêtes en lecture seule : métadonnées de marché, trades historiques, snapshot de positions, carnet d’ordres à un instant donné, etc. Ces requêtes ne nécessitent pas de signature et peuvent être appelées par n’importe quel client.

Les endpoints Exchange (/exchange) gèrent les opérations d’écriture : placement d’ordres, annulations, modification du levier, ajustement de marge, etc. Ces requêtes doivent être accompagnées d’une signature structurée EIP-712. Le serveur vérifie que la signature correspond bien à l’adresse du compte avant d’exécuter l’action.

Cas d’usage typiques de REST

REST est idéal pour les requêtes ponctuelles.

Par exemple : récupérer l’état des positions au démarrage d’une stratégie, vérifier périodiquement le solde d’un compte, consulter l’historique du funding rate d’un contrat, ou obtenir un snapshot du carnet d’ordres à un instant précis. Ces opérations n’exigent pas un flux temps réel : tu envoies une requête, tu reçois une réponse, et c’est suffisant.

Les ordres et annulations passent également par REST. Même si ta stratégie utilise WebSocket pour suivre les données de marché en temps réel, les instructions de trading elles-mêmes doivent être soumises via l’endpoint Exchange en REST. C’est une contrainte structurelle à prendre en compte.

REST convient aussi au téléchargement de données historiques en batch. Pour un backtest, par exemple, tu peux parcourir les données par pagination via les endpoints Info. Ce n’est pas le mode le plus réactif, mais c’est adapté à ce type de tâche.

Les limites de REST

La limite fondamentale de REST vient de son modèle « pull » : tu dois demander les données, encore et encore. Le serveur ne te prévient pas spontanément lorsqu’un marché bouge.

Si tu interroges le carnet d’ordres toutes les 100 ms, tu risques de heurter les limites de débit. Si tu réduis la fréquence à une requête par seconde, ta stratégie peut déjà être en retard dans un marché rapide. Pour les stratégies qui doivent réagir immédiatement aux changements de prix, de liquidité ou d’exécution, le polling REST devient vite inefficace et fragile.

WebSocket : connexion persistante et push temps réel

WebSocket est un protocole full-duplex : une fois la connexion établie, le serveur peut pousser des données vers le client sans que celui-ci ait besoin de renvoyer une requête à chaque fois.

L’endpoint WebSocket de Hyperliquid est :

wss://api.hyperliquid.xyz/ws

Après connexion, le client envoie un message de souscription pour indiquer les flux qui l’intéressent. Le serveur envoie ensuite les mises à jour correspondantes en continu, jusqu’à ce que la connexion soit fermée ou que le client se désabonne.

Cas d’usage typiques de WebSocket

Le suivi du carnet d’ordres en temps réel est le cas d’usage le plus évident. En s’abonnant au canal l2Book, ta stratégie reçoit les mises à jour du carnet et peut détecter les changements de profondeur de marché avec une latence bien plus faible qu’en polling REST.

Le flux de trades en temps réel, via le canal trades, est utile pour analyser le rythme des exécutions, les impulsions de marché et le sentiment court terme.

Les événements de compte, via userEvents, permettent de recevoir les informations importantes comme les exécutions, les confirmations ou certains événements liés au compte, sans devoir interroger l’état du compte en boucle.

Le suivi du funding rate est également important pour certaines stratégies d’arbitrage. WebSocket permet d’être notifié lorsqu’une donnée change, au lieu d’attendre le prochain cycle de polling REST.

Points d’attention avec WebSocket

La stabilité de connexion est le principal défi. Une coupure réseau, un redémarrage côté serveur ou une connexion restée inactive trop longtemps peuvent interrompre le flux. En production, il faut prévoir un mécanisme de heartbeat, généralement via ping/pong, ainsi qu’une logique de reconnexion automatique.

Après reconnexion, il faut aussi se réabonner à tous les canaux nécessaires et gérer les données potentiellement manquées pendant l’interruption.

La charge de traitement des messages ne doit pas être sous-estimée. Si tu t’abonnes à des flux très actifs, comme le carnet L2 d’un marché très liquide, le nombre de messages peut être élevé. Ton client doit parser, valider et traiter les messages assez vite. Sinon, la file d’attente s’accumule, les données prennent du retard, et ton flux « temps réel » cesse d’être réellement exploitable.

Comparaison rapide : REST vs WebSocket

Exemples de code

Requête REST pour obtenir un snapshot du carnet d’ordres

import requests

response = requests.post(
    "https://api.hyperliquid.xyz/info",
    json={"type": "l2Book", "coin": "ETH"}
)

book = response.json()

# Tu obtiens le carnet d’ordres à cet instant précis.
# Il ne se mettra pas à jour automatiquement.
print(book)

Souscription WebSocket au carnet d’ordres en temps réel

import asyncio
import websockets
import json

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

    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "l2Book", "coin": "ETH"}
        }))

        # Le client reçoit des messages à chaque mise à jour du carnet.
        async for message in ws:
            data = json.loads(message)

            # Traiter la mise à jour temps réel ici.
            print(data)

asyncio.run(stream_orderbook())

La différence est simple : REST récupère une photo à un instant donné ; WebSocket ouvre un flux continu qui reste actif jusqu’à la déconnexion.

Signature des ordres et intégration avec OneKey

Que tu utilises REST pour envoyer des ordres ou WebSocket pour surveiller les événements de compte, toute opération d’écriture implique une signature EIP-712. La sécurité de la clé de signature devient donc une limite de sécurité critique pour ton compte.

OneKey permet d’isoler la signature au niveau matériel : les clés privées restent stockées dans l’appareil, et les opérations de signature sont effectuées dans l’environnement sécurisé du wallet. Le code qui tourne sur ton ordinateur ne reçoit jamais la clé privée brute.

Pour un trader quantitatif ou un développeur de stratégie, cela réduit fortement le risque qu’une faille dans le code de trading permette d’exfiltrer directement la clé de signature.

Un workflow possible consiste à construire la requête côté stratégie, à envoyer la demande de signature vers OneKey via un flux compatible, puis à confirmer l’action sur l’appareil avant de soumettre la transaction signée à l’endpoint Exchange de Hyperliquid.

Ce modèle ajoute une étape de confirmation humaine. Il est donc mieux adapté aux stratégies manuelles, semi-automatisées ou de fréquence faible à moyenne. Pour des systèmes haute fréquence entièrement automatisés, il faut évaluer soigneusement l’usage d’un hot wallet dédié, séparé du compte principal, avec des limites de risque strictes.

Pour un usage plus direct, OneKey Perps est le workflow le plus pratique pour accéder à la liquidité Hyperliquid sans devoir gérer toute l’infrastructure API toi-même. Tu peux télécharger OneKey, connecter ton wallet et utiliser OneKey Perps pour trader des contrats perpétuels avec une approche plus simple, tout en gardant une attention claire sur les risques.

Architecture hybride : la meilleure pratique

En production, REST et WebSocket sont rarement des alternatives exclusives. Ils sont plutôt complémentaires.

Une architecture classique peut ressembler à ceci :

• WebSocket maintient une connexion longue pour suivre les données de marché : carnet L2, trades, événements de compte.
• REST soumet les ordres, annulations et autres instructions de trading.
• Au démarrage, REST récupère l’état initial du compte, les positions et certains snapshots de marché.
• À intervalles réguliers, REST refait une vérification complète de l’état du compte pour corriger d’éventuels écarts dus à une déconnexion WebSocket.

Cette approche hybride exploite les forces des deux modèles : REST pour les actions ponctuelles et fiables, WebSocket pour les flux temps réel.

FAQ

Q1 : Si je fais seulement une stratégie d’ordres programmés, ai-je besoin de WebSocket ?

Non. Pour une stratégie simple basée sur un horaire ou un déclenchement périodique, REST suffit généralement. Tu peux interroger le prix et l’état du compte au moment du déclenchement, construire l’ordre, puis le soumettre à l’endpoint Exchange.

WebSocket ajouterait surtout de la complexité opérationnelle si tu n’as pas besoin d’un flux continu.

Q2 : Après une déconnexion WebSocket, comment savoir quelles données j’ai manquées ?

C’est l’un des problèmes classiques du développement WebSocket. Une méthode robuste consiste à récupérer immédiatement un état complet via REST après reconnexion : snapshot du carnet, positions, ordres ouverts, solde, selon les besoins.

Tu utilises ensuite ce nouvel état comme référence. Pour certains flux historiques, comme les trades, tu peux aussi interroger les données sur la période de déconnexion afin de combler les trous.

Q3 : Quelle est la latence entre l’envoi d’un ordre REST et le retour d’exécution ?

La réponse REST confirme généralement que l’ordre a été reçu ou accepté. L’exécution effective doit ensuite être suivie via userEvents sur WebSocket, ou en interrogeant à nouveau l’état du compte.

La latence dépend des conditions réseau, du traitement côté Hyperliquid et du contexte de marché. Elle peut être très courte dans des conditions normales, mais des retards restent possibles lors de périodes extrêmes.

Q4 : Combien de connexions WebSocket faut-il ouvrir ?

Le plus raisonnable est de regrouper les souscriptions d’un même compte sur un petit nombre de connexions. Ouvrir trop de connexions parallèles peut compliquer la gestion des reconnexions et risquer de toucher des limites côté API.

Pour plusieurs stratégies internes, tu peux partager un même flux WebSocket via un bus de messages interne. Cela réduit le nombre de connexions externes et simplifie l’exploitation.

Q5 : Y a-t-il des précautions particulières dans Jupyter Notebook ?

Oui. Jupyter utilise déjà une boucle d’événements, ce qui peut poser problème avec asyncio.run(). Tu peux utiliser nest_asyncio et appeler nest_asyncio.apply() au début du notebook, ou déplacer le code WebSocket dans un script Python séparé pour éviter les conflits.

Conclusion

REST et WebSocket ne sont pas concurrents. Ce sont deux outils conçus pour des besoins différents.

Règle simple : utilise REST quand tu as besoin d’une donnée ou d’une action à un instant donné ; utilise WebSocket quand tu as besoin d’un flux temps réel. Et pour les opérations d’écriture comme les ordres ou annulations, REST reste le passage obligé.

Une fois cette séparation comprise, l’architecture Hyperliquid devient beaucoup plus claire. Pour une expérience plus accessible, OneKey Perps offre un workflow pratique pour utiliser Hyperliquid sans construire toute la pile technique toi-même. Tu peux essayer OneKey, connecter ton wallet et explorer OneKey Perps avec prudence, en gardant une gestion du risque adaptée.

Avertissement

Ce contenu est fourni à titre éducatif et technique uniquement. Il ne constitue pas un conseil financier, juridique ou en investissement. Les stratégies automatisées comportent des risques techniques, notamment bugs, erreurs de configuration, coupures réseau et comportements inattendus. Le trading de contrats perpétuels avec effet de levier est très risqué et peut entraîner des pertes importantes. Évalue toujours tes compétences, ton infrastructure et ta tolérance au risque avant de participer.