Trader avec l'API GaiaEx : authentification, ordres et données de marché

GaiaEx est un exchange décentralisé construit sur Hyperliquid L1, et son API vous donne un accès programmatique à tout ce que la plateforme propose — données de marché, gestion des ordres, suivi des positions et streaming en temps réel. Que vous construisiez un bot de trading, un tableau de bord de portefeuille ou un système d'alerte personnalisé, l'API est votre point d'entrée.

L'API se divise en deux protocoles complémentaires :

• API REST — Des points de terminaison requête-réponse pour passer des ordres, interroger des soldes, récupérer l'historique des trades et gérer les clés API. Utilisez REST quand vous devez faire quelque chose ou demander quelque chose de précis.
• API WebSocket — Des connexions de streaming persistantes pour les données de marché en temps réel (trades, mises à jour du carnet d'ordres, tickers) et les événements privés du compte (exécutions d'ordres, changements de position). Utilisez WebSocket quand vous devez réagir à quelque chose au moment où cela se produit.

Sous le capot, GaiaEx se connecte au carnet d'ordres on-chain d'Hyperliquid L1. Vos ordres sont appariés on-chain avec une exécution déterministe, et vos fonds sont sécurisés par des portefeuilles MPC (calcul multipartite) — ce qui signifie qu'aucune partie unique (pas même GaiaEx) ne détient votre clé privée complète. L'API abstrait la complexité de la blockchain : vous envoyez une requête JSON pour passer un ordre, et la plateforme gère la signature, la soumission et la confirmation sur L1.

L'URL de base de l'API REST suit les conventions standards : https://api.gaiaex.com/v1/. Les connexions WebSocket s'établissent à wss://api.gaiaex.com/ws/v1/. Tous les points de terminaison renvoient du JSON, tous les horodatages sont en millisecondes depuis l'epoch (UTC), et toutes les valeurs monétaires sont des chaînes pour éviter les problèmes de précision en virgule flottante.

Pour accéder aux points de terminaison privés (passer des ordres, interroger vos soldes), vous avez besoin d'une paire de clés API. Générez-en une depuis le tableau de bord GaiaEx, sous Paramètres → Clés API. Vous recevrez deux valeurs :

• API Key — Un identifiant public envoyé avec chaque requête. Considérez-le comme votre nom d'utilisateur.
• API Secret — Une clé privée utilisée pour signer les requêtes. Ne la partagez jamais, ne la committez jamais dans un système de contrôle de version, ne l'envoyez jamais dans un en-tête de requête.

GaiaEx utilise la signature HMAC-SHA256 pour authentifier les requêtes privées. Le processus : concaténer l'horodatage, la méthode HTTP, le chemin de la requête et le corps en une seule chaîne, puis calculer une signature HMAC en utilisant votre secret. Le serveur effectue le même calcul et compare les signatures.

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()

Le composant horodatage empêche les attaques par rejeu (replay attacks) : le serveur rejette toute requête dont l'horodatage s'écarte de plus de 30 secondes de l'horloge du serveur. Assurez-vous que l'horloge de votre machine est synchronisée via NTP.

Les points de terminaison de données de marché sont publics — aucune authentification requise. Ils fournissent les informations brutes nécessaires pour prendre des décisions de trading.

Carnet d'ordres — Renvoie les offres d'achat et de vente actuelles pour un symbole donné. Le paramètre depth contrôle combien de niveaux de prix sont renvoyés (20 par défaut, 100 maximum).

# Récupérer le carnet d'ordres BTC-USD (top 10 niveaux)
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}")

Trades récents — Renvoie les N derniers trades exécutés pour un symbole. Chaque trade inclut le prix, la quantité, le côté (si le taker achetait ou vendait), et l'horodatage.

# Récupérer les 50 derniers trades ETH-USD
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 — Un résumé de l'état actuel du marché : dernier prix, plus haut/bas sur 24 h, volume sur 24 h, meilleure offre/demande, et variation en pourcentage. Idéal pour construire des listes de surveillance ou repérer la volatilité.

# Récupérer tous les 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']}%")

Pour des données en temps réel, utilisez les flux WebSocket plutôt que d'interroger ces points de terminaison. Les points de terminaison REST sont limités en débit et introduisent de la latence ; le WebSocket délivre les mises à jour à l'instant où elles se produisent sur Hyperliquid L1.

Le placement d'ordres est l'action centrale de tout système de trading. GaiaEx prend en charge trois types d'ordres via le point de terminaison POST /orders :

Ordre au marché — S'exécute immédiatement au meilleur prix disponible. À utiliser quand la vitesse d'exécution prime sur la précision du prix.

# Acheter 0,1 BTC au prix du marché
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "buy",
    "type": "market",
    "quantity": "0.1",
})
print(f"Filled at {order['avgPrice']}")

Ordre à cours limité — S'exécute uniquement à votre prix spécifié ou meilleur. Reste dans le carnet d'ordres jusqu'à exécution, annulation ou expiration.

# Vendre 2 ETH à 3 500 $ ou plus
order = signed_request("POST", "/orders", {
    "symbol": "ETH-USD",
    "side": "sell",
    "type": "limit",
    "price": "3500.00",
    "quantity": "2.0",
    "timeInForce": "GTC",  # Good Till Cancelled — valide jusqu'à annulation
})

Ordre stop — Un ordre conditionnel qui s'active lorsque le marché atteint un prix de déclenchement. Utilisé pour les stop-loss et les entrées sur cassure.

# Stop-loss : vendre 0,5 BTC si le prix descend à 58 000 $
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "sell",
    "type": "stop_market",
    "stopPrice": "58000.00",
    "quantity": "0.5",
})

Pour gérer les ordres existants : interrogez les ordres ouverts avec GET /orders?status=open, annulez un ordre spécifique avec DELETE /orders/{orderId}, ou annulez tous les ordres ouverts pour un symbole avec DELETE /orders?symbol=BTC-USD. Pour la gestion des positions, GET /positions renvoie toutes les positions ouvertes avec le prix d'entrée, la quantité, le PnL non réalisé, et le prix de liquidation.

L'API WebSocket de GaiaEx utilise un modèle d'abonnement/désabonnement. Après la connexion, vous envoyez des messages d'abonnement précisant quels canaux vous voulez recevoir. Les canaux publics (données de marché) et privés (événements de compte) sont disponibles sur la même connexion.

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:
        # Authentification pour les canaux privés
        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,
        }))

        # S'abonner aux canaux publics + privés
        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())

Le canal account.orders pousse des mises à jour chaque fois qu'un de vos ordres est exécuté, partiellement exécuté ou annulé — éliminant le besoin d'interroger le point de terminaison REST. Le canal account.positions diffuse le PnL et les mises à jour de marge en temps réel. Combinée aux canaux de données de marché publics, une seule connexion WebSocket fournit tout ce dont un bot de trading a besoin pour fonctionner.

Implémentez toujours un mécanisme de heartbeat : GaiaEx envoie des trames ping périodiques, et votre client doit répondre avec des trames pong. Si aucun pong n'est reçu dans les 30 secondes, le serveur ferme la connexion. De votre côté, si aucune donnée n'arrive pendant 30 secondes, supposez que la connexion est morte et reconnectez-vous.

Assemblons le tout dans un bot de trading minimal mais fonctionnel. Le bot surveille le prix BTC-USD via WebSocket, et lorsque le prix descend sous une cible, il place un ordre d'achat à cours limité. Quand la position est ouverte et que le prix dépasse un niveau de prise de profit, il clôture la 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 + abonnement (omis pour la concision)
        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())

Ceci est délibérément simple. Un bot de production ajouterait : une gestion des erreurs avec try/except autour de chaque appel API et une reconnexion automatique ; une logique de nouvelle tentative avec recul exponentiel pour les échecs transitoires ; un suivi de position via le canal WebSocket account.positions plutôt qu'un simple booléen ; des limites de risque qui stoppent le trading après une perte quotidienne maximale ; et une journalisation qui enregistre chaque décision et chaque réponse API pour l'analyse post-trade.

L'architecture de portefeuille MPC de GaiaEx signifie que votre bot ne manipule jamais de clés privées brutes — la signature est gérée par l'infrastructure de clés distribuée de la plateforme. Cela réduit la surface de sécurité par rapport aux bots qui gèrent leurs propres clés de portefeuille, où une seule compromission peut drainer tous les fonds. Combinée à la liste blanche d'IP sur les clés API et à la couche d'authentification HMAC, vous obtenez une défense en profondeur pour le trading automatisé.

Commencez petit : déployez avec la taille de position minimale, surveillez pendant 48 heures, vérifiez que les exécutions correspondent aux attentes, puis montez en puissance progressivement. Les meilleurs bots de trading se construisent de manière incrémentale, pas dans un seul sprint de code.