Hyperliquid REST vs. WebSocket: Wann du welche API nutzen solltest
Viele Entwickler, die Hyperliquid anbinden, stehen vor derselben Frage: Soll meine Strategie REST oder WebSocket nutzen? Beide API-Typen funktionieren technisch sehr unterschiedlich und eignen sich für unterschiedliche Aufgaben. Die falsche Wahl kann im besten Fall Bandbreite verschwenden – und im schlechtesten Fall dazu führen, dass deine Strategie zu spät reagiert und Orders mit deutlich mehr Slippage ausgeführt werden als erwartet.
In diesem Artikel schauen wir uns an, wie REST und WebSocket bei Hyperliquid funktionieren, wofür sie jeweils geeignet sind, welche Latenz- und Stabilitätsfragen wichtig sind und welche typischen Fehler du vermeiden solltest.
REST API: Request-Response-Modell
REST steht für „Representational State Transfer“ und ist das klassische HTTP-Modell: Der Client schickt eine Anfrage, der Server antwortet, danach ist der einzelne Request abgeschlossen. Bei Hyperliquid lassen sich die REST-Endpunkte grob in zwei Kategorien einteilen.
Info-Endpunkte (/info) sind für reine Leseabfragen gedacht, zum Beispiel Markt-Metadaten, historische Trades oder Snapshots von Account-Positionen. Diese Requests benötigen keine Signatur und können von jedem Client gestellt werden.
Exchange-Endpunkte (/exchange) verarbeiten Schreiboperationen, darunter Orders platzieren, Orders canceln, Leverage anpassen oder Margin ändern. Diese Requests müssen mit einer EIP-712-Signatur versehen sein. Der Server prüft, ob die Signatur zur jeweiligen Account-Adresse passt, bevor die Aktion ausgeführt wird.
Typische Einsatzfälle für REST
REST ist ideal für einmalige Datenabfragen. Beispiele: Beim Start einer Strategie den aktuellen Positionsstatus abrufen, regelmäßig den Account-Balance prüfen oder bei Bedarf die Funding-Historie eines bestimmten Perp-Markts laden. Diese Vorgänge müssen nicht permanent live aktualisiert werden – ein Request, eine Antwort, fertig.
Auch Order- und Cancel-Requests laufen über REST. Selbst wenn deine Strategie Marktdaten per WebSocket empfängt, müssen die eigentlichen Trading-Anweisungen über den Exchange-Endpunkt per REST eingereicht werden. Das ist kein optionales Designmuster, sondern Teil der Hyperliquid-API-Architektur.
Für größere historische Datenabfragen ist REST ebenfalls passend. Wenn du zum Beispiel für ein Backtesting viele historische Trades oder Candles laden musst, kannst du die Info-Endpunkte paginiert abfragen. Das ist nicht „real time“, aber für historische Datensätze völlig ausreichend.
Grenzen von REST
Die zentrale Einschränkung von REST ist das Pull-Modell: Du weißt nicht, wann sich der Markt ändert, also musst du regelmäßig nachfragen. Wenn du alle 100 ms das Orderbook pollst, riskierst du Rate Limits und unnötige Last. Wenn du nur einmal pro Sekunde pollst, kann deine Strategie in schnellen Marktphasen bereits zu spät sein.
Für Strategien, die sofort auf Marktveränderungen reagieren müssen, ist häufiges Polling ineffizient und oft nicht zuverlässig genug.
WebSocket: Persistente Verbindung und Echtzeit-Updates
WebSocket ist ein Full-Duplex-Protokoll. Nach dem Verbindungsaufbau kann der Server Daten aktiv an den Client senden, ohne dass der Client ständig neue Requests starten muss. Der WebSocket-Endpunkt von Hyperliquid lautet:
wss://api.hyperliquid.xyz/ws
Nach dem Verbindungsaufbau sendet der Client eine Subscribe-Nachricht und gibt an, welche Daten er erhalten möchte. Der Server pusht anschließend fortlaufend Updates zu diesen Daten, bis die Verbindung getrennt oder das Abo beendet wird.
Typische Einsatzfälle für WebSocket
Der wichtigste Einsatzfall ist das Monitoring des Orderbooks in Echtzeit. Wenn du den l2Book-Channel abonnierst, erhältst du Updates, sobald sich das Orderbook verändert. Dadurch kann eine Strategie Marktliquidität und Tiefe wesentlich schneller erfassen als über REST-Polling.
Der Trade-Stream (trades) eignet sich, um Market Impact, Ausführungstempo und kurzfristiges Sentiment zu beobachten. Für viele Strategien ist das ein nützliches Signal, auch wenn es allein keine Handelsentscheidung ersetzen sollte.
Über Account-Events (userEvents) kannst du Execution Reports, Liquidation Notices und andere wichtige accountbezogene Ereignisse live empfangen. Das spart zusätzliches Polling des Account-Zustands.
Auch für das Tracking von Funding-Daten kann WebSocket sinnvoll sein, insbesondere bei Arbitrage- oder Carry-Strategien. Änderungen werden dann zeitnah gemeldet, statt erst beim nächsten REST-Abfragezyklus sichtbar zu werden.
Worauf du bei WebSocket achten musst
Die größte Herausforderung ist die Verbindungsstabilität. Netzwerkprobleme, Server-Restarts oder lange Inaktivität können dazu führen, dass eine WebSocket-Verbindung getrennt wird. In einer produktiven Umgebung brauchst du deshalb Heartbeats, also Ping/Pong-Mechanismen, sowie automatisches Reconnect-Handling.
Nach einem Reconnect musst du alle relevanten Channels erneut abonnieren. Außerdem solltest du davon ausgehen, dass während der Unterbrechung Daten verloren gegangen sein können.
Ein zweiter Punkt ist die Verarbeitungsgeschwindigkeit. Bei hochfrequenten Datenquellen, etwa L2-Orderbooks großer Märkte, kann die Nachrichtenrate sehr hoch sein. Dein Client muss JSON-Parsing, Queueing und Strategie-Logik schnell genug verarbeiten. Wenn sich Nachrichten in einer Queue stauen, arbeitest du irgendwann mit veralteten Daten – dann bringt dir WebSocket keinen Echtzeitvorteil mehr.
REST vs. WebSocket im Vergleich
Codebeispiele
REST: Orderbook-Snapshot abfragen (Python)
import requests
response = requests.post(
"https://api.hyperliquid.xyz/info",
json={"type": "l2Book", "coin": "ETH"}
)
book = response.json()
# Du erhältst einen Snapshot des Orderbooks zu diesem Zeitpunkt.
# Danach wird dieser Snapshot nicht automatisch aktualisiert.
WebSocket: Orderbook-Updates abonnieren (Python)
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"}
}))
# Du erhältst fortlaufend neue Nachrichten,
# sobald sich das Orderbook verändert.
async for message in ws:
data = json.loads(message)
print(data)
asyncio.run(stream_orderbook())
Der Unterschied ist klar: REST liefert dir einen einmaligen Snapshot. WebSocket hält eine Verbindung offen und liefert Updates, bis die Verbindung endet.
Order-Signaturen und OneKey-Integration
Egal ob du Marktdaten per WebSocket überwachst oder Orders per REST platzierst: Sobald eine Schreiboperation im Spiel ist, brauchst du eine EIP-712-Signatur. Die Sicherheit des Signaturschlüssels ist damit direkt ein Teil deiner Account-Sicherheit.
OneKey Wallet bietet dafür eine Hardware-basierte Signatur-Isolation. Private Keys bleiben im Secure Element des Geräts, und Signaturen werden intern auf dem Gerät erzeugt. Der Host-Rechner und dein Strategie-Code erhalten nie den rohen Private Key.
Für quantitative Trader ist das wichtig: Selbst wenn dein Strategy-Code oder deine lokale Umgebung Schwachstellen hat, kann ein Angreifer nicht einfach den Private Key auslesen. Das reduziert eine zentrale Risikofläche, ersetzt aber natürlich keine saubere Infrastruktur- und Wallet-Trennung.
Ein typischer Workflow sieht so aus:
- Deine Strategie baut den zu signierenden Order-Request.
- Die Signaturanfrage wird über WalletConnect an OneKey gesendet.
- Du prüfst und bestätigst die Anfrage auf dem OneKey-Gerät.
- Die Signatur wird an den Strategy-Code zurückgegeben.
- Der signierte Request wird an den Hyperliquid-Exchange-Endpunkt gesendet.
Dieser Ablauf fügt eine manuelle Bestätigung hinzu und passt daher eher zu niedriger bis mittlerer Handelsfrequenz. Für vollautomatische High-Frequency-Strategien solltest du genau prüfen, ob du mit einem dedizierten Hot Wallet arbeitest und dieses strikt vom Hauptvermögen trennst.
OneKey ist für Desktop und Mobile verfügbar. Der Open-Source-Code auf GitHub kann Entwicklern außerdem helfen, Signatur-Integrationen besser nachzuvollziehen.
OneKey Perps als praktischer Workflow
Wenn du Hyperliquid nutzen möchtest, ohne direkt eine eigene API-Infrastruktur, WebSocket-Reconnects und Signatur-Flows zu bauen, ist OneKey Perps der pragmatischere Einstieg. Du kannst Perps aus der OneKey-Umgebung heraus nutzen und dabei von einer Wallet-first-Erfahrung profitieren, bei der Key-Sicherheit und Trading-Workflow enger zusammenliegen.
Für Entwickler bleibt die API-Integration relevant, wenn du eigene Strategien, Bots oder Monitoring-Systeme bauen willst. Für viele Nutzer ist es aber sinnvoller, zunächst OneKey herunterzuladen, die Wallet sicher einzurichten und OneKey Perps als kontrollierten Einstieg in Hyperliquid-Liquidität zu verwenden – ohne daraus eine Garantie für Gewinne oder geringeres Marktrisiko abzuleiten.
Hybrid-Architektur: Best Practice
In der Praxis sind REST und WebSocket selten Konkurrenten. Meist ergänzen sie sich. Eine typische Architektur für eine Trading-Strategie kann so aussehen:
- WebSocket hält Live-Subscriptions für Marktdaten wie L2-Orderbook, Trades und Account-Events.
- REST sendet Orders, Cancels und andere Trading-Anweisungen.
- Beim Start ruft REST einmalig Account-Status, Balances und aktuelle Positionen ab.
- In regelmäßigen Abständen, zum Beispiel stündlich, prüft REST den vollständigen Account-Zustand erneut.
- Nach einem WebSocket-Reconnect holt REST einen frischen Snapshot, damit die lokale State-Machine wieder sauber synchronisiert ist.
Diese Kombination nutzt die Stärken beider Schnittstellen: WebSocket für Live-Daten, REST für verlässliche Snapshots und Schreiboperationen.
FAQ
Q1: Brauche ich WebSocket für eine einfache zeitgesteuerte Order-Strategie?
Nein. Wenn deine Strategie nur zu festen Zeiten Orders platzieren soll, reichen REST-Requests meist aus. Du kannst beim Trigger den aktuellen Preis und Account-Zustand per REST abfragen, die Order bauen und über den Exchange-Endpunkt einreichen. WebSocket würde in diesem Fall vor allem zusätzliche Komplexität bringen.
Q2: Wie weiß ich nach einem WebSocket-Disconnect, welche Daten ich verpasst habe?
Das ist ein klassisches Problem bei WebSocket-Systemen. Üblich ist: Nach dem Reconnect holst du per REST den aktuellen vollständigen Zustand, etwa Orderbook-Snapshot und Account-Positionen, und verwendest diesen als neue Basis. Für historische Trades kannst du den Zeitraum der Unterbrechung nachträglich abfragen, falls du diese Daten für deine Strategie brauchst.
Q3: Wie groß ist die Latenz zwischen REST-Order und Execution Report?
Die REST-Antwort bestätigt in der Regel, dass die Order angenommen wurde. Die tatsächliche Ausführung erhältst du über den userEvents-Channel per WebSocket oder durch erneutes Polling des Account-Zustands. Die Gesamtlatenz hängt von Netzwerkbedingungen und der Verarbeitung auf Hyperliquid-Seite ab. Unter normalen Bedingungen wird sie häufig als sehr kurz beschrieben, in extremen Marktphasen kann es aber Verzögerungen geben.
Q4: Wie viele WebSocket-Verbindungen sollte ich öffnen?
Am besten bündelst du Subscriptions eines Accounts auf möglichst wenigen Verbindungen. Zu viele parallele Connections können Limits auslösen und machen Reconnect-Handling unnötig kompliziert. Die konkreten Grenzwerte solltest du immer in der aktuellen offiziellen Dokumentation prüfen. Mehrere interne Strategien können sich eine WebSocket-Verbindung über einen internen Message Bus teilen.
Q5: Was muss ich beim Debugging in Jupyter Notebook beachten?
Jupyter nutzt bereits einen eigenen Event Loop, was mit asyncio.run() kollidieren kann. Eine gängige Lösung ist nest_asyncio: installieren, im Notebook nest_asyncio.apply() ausführen und dann den WebSocket-Code starten. Alternativ verschiebst du den WebSocket-Code in ein separates Python-Skript.
Fazit
REST und WebSocket sind keine konkurrierenden Optionen, sondern Werkzeuge für unterschiedliche Aufgaben. Kurz gesagt: Wenn du Daten „jetzt einmalig“ brauchst, nimm REST. Wenn du Daten „laufend in Echtzeit“ brauchst, nimm WebSocket. Schreiboperationen laufen bei Hyperliquid über REST.
Wenn du diese Rollen sauber trennst, verstehst du den Kern der Hyperliquid-API-Architektur. In Kombination mit OneKey als Signatur-Backend kannst du eine robustere Trading-Umgebung aufbauen, ohne Private Keys unnötig deiner lokalen Infrastruktur auszusetzen.
Wenn du Hyperliquid praktisch nutzen möchtest, lade OneKey herunter, richte deine Wallet sorgfältig ein und teste OneKey Perps mit einem klaren Risikobewusstsein. Nutze nur Kapital, dessen Verlust du verkraften kannst, und prüfe jeden Workflow, bevor du ihn mit größeren Beträgen verwendest.
Disclaimer
Dieser Artikel dient nur der technischen Information und ist keine Finanz-, Anlage-, Rechts- oder Steuerberatung. Automatisierte Trading-Strategien können durch Codefehler, Netzwerkprobleme, falsche Signaturen oder Systemausfälle zu unerwarteten Verlusten führen. Perpetual Futures und gehebeltes Trading sind hochriskant und können schnell zu erheblichen Verlusten führen. Prüfe deine technische Kompetenz und Risikotoleranz sorgfältig, bevor du teilnimmst.
