Trading mit der GaiaEx-API: Authentifizierung, Orders und Marktdaten

GaiaEx ist eine dezentrale Börse (DEX), die auf Hyperliquid L1 aufbaut, und ihre API gibt dir programmatischen Zugriff auf alles, was die Plattform bietet — Marktdaten, Orderverwaltung, Positionsverfolgung und Echtzeit-Streaming. Ob du einen Trading-Bot, ein Portfolio-Dashboard oder ein maßgeschneidertes Benachrichtigungssystem baust — die API ist dein Einstiegspunkt.

Die API ist in zwei sich ergänzende Protokolle unterteilt:

• REST-API — Request-Response-Endpunkte zum Platzieren von Orders, Abfragen von Guthaben, Abrufen historischer Trades und Verwalten von API-Keys. Nutze REST, wenn du etwas tun oder etwas Konkretes abfragen willst.
• WebSocket-API — Dauerhafte Streaming-Verbindungen für Echtzeit-Marktdaten (Trades, Orderbuch-Updates, Ticker) und private Kontoereignisse (Order-Fills, Positionsänderungen). Nutze WebSocket, wenn du auf etwas reagieren musst, sobald es passiert.

Im Hintergrund verbindet sich GaiaEx mit dem On-Chain-Orderbuch von Hyperliquid L1. Deine Orders werden on-chain mit deterministischer Ausführung gematcht, und deine Gelder werden durch MPC-Wallets (Multi-Party Computation) gesichert — das heißt, keine einzelne Partei (nicht einmal GaiaEx) hält deinen vollständigen privaten Schlüssel. Die API abstrahiert die Blockchain-Komplexität: Du sendest einen JSON-Request, um eine Order zu platzieren, und die Plattform übernimmt Signierung, Übermittlung und Bestätigung auf L1.

Die Basis-URL für die REST-API folgt den gängigen Konventionen: https://api.gaiaex.com/v1/. WebSocket-Verbindungen werden unter wss://api.gaiaex.com/ws/v1/ aufgebaut. Alle Endpunkte liefern JSON, alle Zeitstempel sind in Millisekunden seit der Epoche (UTC) angegeben, und alle Geldwerte sind Strings, um Präzisionsprobleme durch Fließkommazahlen zu vermeiden.

Um auf private Endpunkte zuzugreifen (Orders platzieren, Guthaben abfragen), brauchst du ein API-Key-Paar. Erzeuge eines im GaiaEx-Dashboard unter Einstellungen → API-Keys. Du erhältst zwei Werte:

• API Key — Ein öffentlicher Identifikator, der mit jedem Request gesendet wird. Betrachte ihn wie deinen Benutzernamen.
• API Secret — Ein privater Schlüssel, der zum Signieren von Requests verwendet wird. Teile ihn niemals, committe ihn niemals in die Versionskontrolle, sende ihn niemals in einem Request-Header.

GaiaEx nutzt HMAC-SHA256-Signierung, um private Requests zu authentifizieren. Der Ablauf: Zeitstempel, HTTP-Methode, Request-Pfad und Body werden zu einem einzigen String verknüpft, dann wird eine HMAC-Signatur mit deinem Secret berechnet. Der Server führt dieselbe Berechnung aus und vergleicht die Signaturen.

import hmac, hashlib, time, requests, json

API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
BASE_URL = "https://api.gaiaex.com/v1"

def signed_request(method, path, body=None):
    timestamp = str(int(time.time() * 1000))
    body_str = json.dumps(body) if body else ""
    message = timestamp + method.upper() + path + body_str
    signature = hmac.new(
        API_SECRET.encode(), message.encode(), hashlib.sha256
    ).hexdigest()

    headers = {
        "X-API-Key": API_KEY,
        "X-Timestamp": timestamp,
        "X-Signature": signature,
        "Content-Type": "application/json",
    }

    resp = requests.request(method, BASE_URL + path, headers=headers,
                            data=body_str if body else None)
    return resp.json()

Die Zeitstempel-Komponente verhindert Replay-Angriffe: Der Server lehnt jeden Request ab, bei dem der Zeitstempel mehr als 30 Sekunden von der Serveruhr abweicht. Achte darauf, dass die Uhr deines Rechners per NTP synchronisiert ist.

Marktdaten-Endpunkte sind öffentlich — keine Authentifizierung erforderlich. Sie liefern die Rohinformationen, die du für Handelsentscheidungen brauchst.

Orderbuch — Liefert die aktuellen Bids und Asks für ein bestimmtes Symbol. Der Parameter depth steuert, wie viele Preisebenen zurückgegeben werden (Standard 20, maximal 100).

# Fetch the BTC-USD order book (top 10 levels)
resp = requests.get(f"{BASE_URL}/orderbook/BTC-USD?depth=10")
book = resp.json()

best_bid = book["bids"][0]  # [price, quantity]
best_ask = book["asks"][0]
spread = float(best_ask[0]) - float(best_bid[0])
print(f"Spread: ${spread:.2f}")

Letzte Trades — Liefert die letzten N ausgeführten Trades für ein Symbol. Jeder Trade enthält Preis, Menge, Seite (ob der Taker gekauft oder verkauft hat) und Zeitstempel.

# Fetch the last 50 ETH-USD trades
resp = requests.get(f"{BASE_URL}/trades/ETH-USD?limit=50")
trades = resp.json()["trades"]
avg_price = sum(float(t["price"]) for t in trades) / len(trades)
print(f"Average of last 50 trades: ${avg_price:.2f}")

Ticker — Eine Zusammenfassung des aktuellen Marktzustands: letzter Preis, 24h-Hoch/-Tief, 24h-Volumen, bester Bid/Ask und prozentuale Veränderung. Ideal, um Watchlists aufzubauen oder nach Volatilität zu scannen.

# Fetch all tickers
resp = requests.get(f"{BASE_URL}/tickers")
for ticker in resp.json():
    if float(ticker["change24h"]) > 5.0:
        print(f"{ticker['symbol']}: +{ticker['change24h']}%")

Für Echtzeitdaten nutze die WebSocket-Feeds statt diese Endpunkte per Polling abzufragen. Die REST-Endpunkte sind ratenbegrenzt und bringen Latenz mit sich; der WebSocket liefert Updates in dem Moment, in dem sie auf Hyperliquid L1 passieren.

Die Orderplatzierung ist die Kernaktion in jedem Handelssystem. GaiaEx unterstützt drei Order-Typen über den Endpunkt POST /orders:

Market Order (Marktorder) — Wird sofort zum besten verfügbaren Preis ausgeführt. Nutze diese, wenn Ausführungsgeschwindigkeit wichtiger ist als Preisgenauigkeit.

# Buy 0.1 BTC at market price
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "buy",
    "type": "market",
    "quantity": "0.1",
})
print(f"Filled at {order['avgPrice']}")

Limit Order (Limitorder) — Wird nur zu deinem angegebenen Preis oder besser ausgeführt. Bleibt im Orderbuch, bis sie gefüllt, storniert oder abgelaufen ist.

# Sell 2 ETH at $3,500 or higher
order = signed_request("POST", "/orders", {
    "symbol": "ETH-USD",
    "side": "sell",
    "type": "limit",
    "price": "3500.00",
    "quantity": "2.0",
    "timeInForce": "GTC",  # Good Till Cancelled
})

Stop Order — Eine bedingte Order, die aktiv wird, sobald der Markt einen Trigger-Preis erreicht. Wird für Stop-Loss und Breakout-Einstiege genutzt.

# Stop-loss: sell 0.5 BTC if price drops to $58,000
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "sell",
    "type": "stop_market",
    "stopPrice": "58000.00",
    "quantity": "0.5",
})

Um bestehende Orders zu verwalten: Frage offene Orders mit GET /orders?status=open ab, storniere eine bestimmte Order mit DELETE /orders/{orderId}, oder storniere alle offenen Orders für ein Symbol mit DELETE /orders?symbol=BTC-USD. Für die Positionsverwaltung liefert GET /positions alle offenen Positionen mit Einstiegspreis, Menge, unrealisiertem PnL und Liquidationspreis.

Die GaiaEx-WebSocket-API nutzt ein Subscribe/Unsubscribe-Modell. Nach dem Verbinden sendest du Subscription-Nachrichten, die angeben, welche Channels du empfangen willst. Sowohl öffentliche (Marktdaten) als auch private (Kontoereignisse) Channels sind auf derselben Verbindung verfügbar.

import asyncio, json, hmac, hashlib, time
import websockets

async def connect_gaiaex():
    uri = "wss://api.gaiaex.com/ws/v1"
    async with websockets.connect(uri) as ws:
        # Authenticate for private channels
        ts = str(int(time.time() * 1000))
        sig = hmac.new(API_SECRET.encode(),
                       (ts + "websocket_auth").encode(),
                       hashlib.sha256).hexdigest()
        await ws.send(json.dumps({
            "method": "auth",
            "apiKey": API_KEY,
            "timestamp": ts,
            "signature": sig,
        }))

        # Subscribe to public + private channels
        await ws.send(json.dumps({
            "method": "subscribe",
            "channels": [
                "trades.BTC-USD",
                "orderbook.BTC-USD",
                "account.orders",
                "account.positions",
            ]
        }))

        async for msg in ws:
            data = json.loads(msg)
            ch = data.get("channel", "")
            if ch == "account.orders":
                print(f"Order update: {data['status']} {data['orderId']}")
            elif ch == "trades.BTC-USD":
                print(f"Trade: {data['price']} x {data['quantity']}")

asyncio.run(connect_gaiaex())

Der Channel account.orders sendet Updates, sobald eine deiner Orders gefüllt, teilweise gefüllt oder storniert wird — das macht das Polling des REST-Endpunkts überflüssig. Der Channel account.positions streamt PnL- und Margin-Updates in Echtzeit. Zusammen mit den öffentlichen Marktdaten-Channels liefert eine einzige WebSocket-Verbindung alles, was ein Trading-Bot zum Betrieb braucht.

Implementiere immer einen Heartbeat-Mechanismus: GaiaEx sendet periodische Ping-Frames, und dein Client muss mit Pong-Frames antworten. Kommt innerhalb von 30 Sekunden kein Pong an, schließt der Server die Verbindung. Auf deiner Seite: Kommen 30 Sekunden lang keine Daten an, geh davon aus, dass die Verbindung tot ist, und verbinde neu.

Fügen wir alles zu einem minimalen, aber funktionierenden Trading-Bot zusammen. Der Bot überwacht den BTC-USD-Preis per WebSocket, und wenn der Preis unter ein Ziel fällt, platziert er eine Limit-Buy-Order. Ist die Position offen und der Preis steigt über ein Take-Profit-Niveau, schließt er die Position.

import asyncio, json
import websockets

TARGET_BUY = 60000.0
TAKE_PROFIT = 63000.0
QUANTITY = "0.05"
position_open = False

async def trading_bot():
    global position_open
    uri = "wss://api.gaiaex.com/ws/v1"

    async with websockets.connect(uri) as ws:
        # Auth + subscribe (omitted for brevity)
        await ws.send(json.dumps({
            "method": "subscribe",
            "channels": ["trades.BTC-USD"]
        }))

        async for msg in ws:
            data = json.loads(msg)
            if data.get("channel") != "trades.BTC-USD":
                continue

            price = float(data["price"])

            if not position_open and price <= TARGET_BUY:
                order = signed_request("POST", "/orders", {
                    "symbol": "BTC-USD", "side": "buy",
                    "type": "limit", "price": str(TARGET_BUY),
                    "quantity": QUANTITY,
                })
                print(f"BUY order placed: {order['orderId']}")
                position_open = True

            elif position_open and price >= TAKE_PROFIT:
                order = signed_request("POST", "/orders", {
                    "symbol": "BTC-USD", "side": "sell",
                    "type": "market", "quantity": QUANTITY,
                })
                print(f"SELL order placed: {order['orderId']}")
                position_open = False

asyncio.run(trading_bot())

Das ist bewusst simpel gehalten. Ein Produktions-Bot würde zusätzlich brauchen: Fehlerbehandlung mit try/except um jeden API-Call und automatischer Wiederverbindung; Retry-Logik mit exponentiellem Backoff für vorübergehende Ausfälle; Positionsverfolgung über den WebSocket-Channel account.positions statt eines booleschen Flags; Risikolimits, die den Handel nach einem maximalen Tagesverlust stoppen; und Logging, das jede Entscheidung und API-Antwort für die Analyse nach dem Trade festhält.

Die MPC-Wallet-Architektur von GaiaEx bedeutet, dass dein Bot niemals rohe private Schlüssel verarbeitet — die Signierung übernimmt die verteilte Key-Infrastruktur der Plattform. Das reduziert die Angriffsfläche im Vergleich zu Bots, die ihre eigenen Wallet-Keys verwalten, wo eine einzige Kompromittierung alle Gelder abziehen kann. Zusammen mit IP-Whitelisting für API-Keys und der HMAC-Authentifizierungsebene erhältst du gestaffelte Sicherheit (Defense in Depth) für automatisierten Handel.

Fang klein an: Setze mit der minimalen Positionsgröße ein, überwache 48 Stunden, verifiziere, dass die Fills den Erwartungen entsprechen, und skaliere dann schrittweise. Die besten Trading-Bots werden inkrementell gebaut, nicht in einem einzigen Coding-Sprint.