Fare trading con l'API GaiaEx: autenticazione, ordini e dati di mercato

GaiaEx è un exchange decentralizzato costruito su Hyperliquid L1, e la sua API ti dà accesso programmatico a tutto ciò che la piattaforma offre — dati di mercato, gestione degli ordini, tracciamento delle posizioni e streaming in tempo reale. Che tu stia costruendo un trading bot, una dashboard di portafoglio o un sistema di alert personalizzato, l'API è il tuo punto di ingresso.

L'API è divisa in due protocolli complementari:

• API REST — endpoint di tipo richiesta-risposta per piazzare ordini, interrogare i saldi, recuperare la cronologia degli scambi e gestire le API key. Usa REST quando devi fare qualcosa o chiedere qualcosa di specifico.
• API WebSocket — connessioni di streaming persistenti per dati di mercato in tempo reale (scambi, aggiornamenti dell'order book, ticker) ed eventi privati sull'account (esecuzioni degli ordini, variazioni di posizione). Usa WebSocket quando devi reagire a qualcosa nel momento in cui accade.

Dietro le quinte, GaiaEx si connette all'order book on-chain di Hyperliquid L1. I tuoi ordini vengono abbinati on-chain con esecuzione deterministica, e i tuoi fondi sono protetti da wallet MPC (Multi-Party Computation) — il che significa che nessuna singola parte (nemmeno GaiaEx) detiene la tua chiave privata completa. L'API astrae la complessità della blockchain: invii una richiesta JSON per piazzare un ordine, e la piattaforma gestisce firma, invio e conferma su L1.

L'URL base per l'API REST segue le convenzioni standard: https://api.gaiaex.com/v1/. Le connessioni WebSocket vengono stabilite su wss://api.gaiaex.com/ws/v1/. Tutti gli endpoint restituiscono JSON, tutti i timestamp sono in millisecondi dall'epoch (UTC), e tutti i valori monetari sono stringhe per evitare problemi di precisione con i numeri in virgola mobile.

Per accedere agli endpoint privati (piazzare ordini, interrogare i tuoi saldi), hai bisogno di una coppia di API key. Generane una dalla dashboard GaiaEx sotto Impostazioni → API Key. Riceverai due valori:

• API Key — un identificatore pubblico inviato con ogni richiesta. Pensala come il tuo nome utente.
• API Secret — una chiave privata usata per firmare le richieste. Non condividerla mai, non caricarla mai nel controllo versione, non inviarla mai in un header di richiesta.

GaiaEx usa la firma HMAC-SHA256 per autenticare le richieste private. Il processo: concatena il timestamp, il metodo HTTP, il percorso della richiesta e il corpo in un'unica stringa, poi calcola una firma HMAC usando il tuo secret. Il server esegue lo stesso calcolo e confronta le firme.

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

La componente timestamp previene gli attacchi replay: il server rifiuta qualsiasi richiesta in cui il timestamp è più di 30 secondi distante dall'orologio del server. Assicurati che l'orologio della tua macchina sia sincronizzato tramite NTP.

Gli endpoint dei dati di mercato sono pubblici — non è richiesta autenticazione. Forniscono le informazioni grezze di cui hai bisogno per prendere decisioni di trading.

Order book — restituisce i bid e gli ask attuali per un dato simbolo. Il parametro depth controlla quanti livelli di prezzo vengono restituiti (default 20, massimo 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}")

Scambi recenti — restituisce gli ultimi N scambi eseguiti per un simbolo. Ogni scambio include il prezzo, la quantità, il lato (se il taker stava comprando o vendendo) e il timestamp.

# 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 — un riepilogo dello stato attuale del mercato: ultimo prezzo, massimo/minimo delle 24 ore, volume delle 24 ore, miglior bid/ask e variazione percentuale. Ideale per costruire watchlist o per individuare la volatilità.

# 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']}%")

Per i dati in tempo reale, usa i feed WebSocket invece di interrogare periodicamente questi endpoint. Gli endpoint REST sono soggetti a rate limit e introducono latenza; il WebSocket consegna gli aggiornamenti nell'istante in cui si verificano su Hyperliquid L1.

Piazzare un ordine è l'azione centrale in qualsiasi sistema di trading. GaiaEx supporta tre tipi di ordine tramite l'endpoint POST /orders:

Ordine market — esegue immediatamente al miglior prezzo disponibile. Usalo quando la velocità di esecuzione conta più della precisione del prezzo.

# 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']}")

Ordine limit — esegue solo al prezzo specificato o meglio. Rimane nell'order book finché non viene eseguito, annullato o scaduto.

# 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
})

Ordine stop — un ordine condizionale che diventa attivo quando il mercato raggiunge un prezzo trigger. Usato per stop-loss e per entrate su breakout.

# 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",
})

Per gestire gli ordini esistenti: interroga gli ordini aperti con GET /orders?status=open, annulla un ordine specifico con DELETE /orders/{orderId}, oppure annulla tutti gli ordini aperti per un simbolo con DELETE /orders?symbol=BTC-USD. Per la gestione delle posizioni, GET /positions restituisce tutte le posizioni aperte con prezzo di entrata, quantità, PnL non realizzato e prezzo di liquidazione.

L'API WebSocket di GaiaEx usa un modello subscribe/unsubscribe. Dopo la connessione, invii messaggi di iscrizione specificando quali canali vuoi ricevere. Sia i canali pubblici (dati di mercato) che quelli privati (eventi dell'account) sono disponibili sulla stessa connessione.

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

Il canale account.orders invia aggiornamenti ogni volta che uno dei tuoi ordini viene eseguito, parzialmente eseguito o annullato — eliminando la necessità di interrogare periodicamente l'endpoint REST. Il canale account.positions trasmette in streaming gli aggiornamenti del PnL e del margine in tempo reale. Combinato con i canali pubblici dei dati di mercato, un'unica connessione WebSocket fornisce tutto ciò di cui un trading bot ha bisogno per funzionare.

Implementa sempre un meccanismo di heartbeat: GaiaEx invia frame di ping periodici, e il tuo client deve rispondere con frame di pong. Se non viene ricevuto nessun pong entro 30 secondi, il server chiude la connessione. Sul tuo lato, se non arrivano dati per 30 secondi, presumi che la connessione sia morta e riconnettiti.

Uniamo tutto in un trading bot minimale ma funzionale. Il bot monitora il prezzo di BTC-USD via WebSocket, e quando il prezzo scende sotto un target, piazza un ordine limit di acquisto. Quando la posizione è aperta e il prezzo sale sopra un livello di take-profit, chiude la posizione.

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

Questo è deliberatamente semplice. Un bot in produzione aggiungerebbe: gestione degli errori con try/except attorno a ogni chiamata API e riconnessione automatica; logica di retry con backoff esponenziale per errori transitori; tracciamento delle posizioni tramite il canale WebSocket account.positions invece di un flag booleano; limiti di rischio che interrompono il trading dopo una perdita giornaliera massima; e logging che registra ogni decisione e risposta API per l'analisi post-trade.

L'architettura del wallet MPC di GaiaEx significa che il tuo bot non gestisce mai chiavi private grezze — la firma è gestita dall'infrastruttura distribuita di chiavi della piattaforma. Questo riduce la superficie di sicurezza rispetto ai bot che gestiscono le proprie chiavi di wallet, dove una singola compromissione può prosciugare tutti i fondi. Combinata con il whitelisting degli IP sulle API key e con lo strato di autenticazione HMAC, ottieni una defense-in-depth per il trading automatizzato.

Parti in piccolo: implementa con la dimensione minima di posizione, monitora per 48 ore, verifica che le esecuzioni corrispondano alle aspettative, poi scala gradualmente. I migliori trading bot vengono costruiti in modo incrementale, non in un unico sprint di codifica.