Operar con la API de GaiaEx: autenticación, órdenes y datos de mercado

GaiaEx es un exchange descentralizado construido sobre Hyperliquid L1, y su API te da acceso programático a todo lo que ofrece la plataforma — datos de mercado, gestión de órdenes, seguimiento de posiciones y streaming en tiempo real. Ya estés construyendo un bot de trading, un panel de cartera o un sistema de alertas personalizado, la API es tu punto de entrada.

La API se divide en dos protocolos complementarios:

• API REST — Endpoints de solicitud-respuesta para colocar órdenes, consultar saldos, obtener operaciones históricas y gestionar claves de API. Usa REST cuando necesites hacer algo o pedir algo concreto.
• API WebSocket — Conexiones de streaming persistentes para datos de mercado en tiempo real (operaciones, actualizaciones del libro de órdenes, tickers) y eventos privados de cuenta (ejecuciones de órdenes, cambios de posición). Usa WebSocket cuando necesites reaccionar a algo en el instante en que ocurre.

Por debajo, GaiaEx se conecta al libro de órdenes on-chain de Hyperliquid L1. Tus órdenes se emparejan on-chain con ejecución determinista, y tus fondos están protegidos por monederos MPC (Computación Multiparte) — es decir, ninguna parte única (ni siquiera GaiaEx) tiene tu clave privada completa. La API abstrae la complejidad de la blockchain: envías una solicitud JSON para colocar una orden, y la plataforma se encarga de la firma, el envío y la confirmación en L1.

La URL base de la API REST sigue las convenciones estándar: https://api.gaiaex.com/v1/. Las conexiones WebSocket se establecen en wss://api.gaiaex.com/ws/v1/. Todos los endpoints devuelven JSON, todas las marcas de tiempo están en milisegundos desde el epoch (UTC), y todos los valores monetarios son cadenas de texto para evitar problemas de precisión de coma flotante.

Para acceder a los endpoints privados (colocar órdenes, consultar tus saldos), necesitas un par de claves de API. Genera uno desde el panel de GaiaEx en Configuración → Claves de API. Recibirás dos valores:

• API Key — Un identificador público que se envía con cada solicitud. Piénsalo como tu nombre de usuario.
• API Secret — Una clave privada usada para firmar solicitudes. Nunca la compartas, nunca la subas a un control de versiones, nunca la envíes en una cabecera de solicitud.

GaiaEx usa firma HMAC-SHA256 para autenticar las solicitudes privadas. El proceso: concatena la marca de tiempo, el método HTTP, la ruta de la solicitud y el cuerpo en una sola cadena, y luego calcula una firma HMAC usando tu clave secreta. El servidor realiza el mismo cálculo y compara las firmas.

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

El componente de marca de tiempo evita los ataques de repetición (replay): el servidor rechaza cualquier solicitud cuya marca de tiempo se desvíe más de 30 segundos del reloj del servidor. Asegúrate de que el reloj de tu máquina esté sincronizado vía NTP.

Los endpoints de datos de mercado son públicos — no requieren autenticación. Ofrecen la información en bruto que necesitas para tomar decisiones de trading.

Libro de órdenes (order book) — Devuelve las posturas de compra y venta actuales de un símbolo dado. El parámetro depth controla cuántos niveles de precio se devuelven (por defecto 20, máximo 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}")

Operaciones recientes — Devuelve las últimas N operaciones ejecutadas para un símbolo. Cada operación incluye el precio, la cantidad, el lado (si el tomador compraba o vendía) y la marca de tiempo.

# 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 resumen del estado actual del mercado: último precio, máximo/mínimo de 24 h, volumen de 24 h, mejor bid/ask y cambio porcentual. Ideal para construir listas de seguimiento o rastrear volatilidad.

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

Para datos en tiempo real, usa los feeds de WebSocket en lugar de consultar estos endpoints repetidamente (polling). Los endpoints REST tienen límites de tasa e introducen latencia; el WebSocket entrega actualizaciones en el instante en que ocurren en Hyperliquid L1.

Colocar órdenes es la acción central de cualquier sistema de trading. GaiaEx admite tres tipos de orden a través del endpoint POST /orders:

Orden a mercado — Se ejecuta inmediatamente al mejor precio disponible. Úsala cuando la velocidad de ejecución importe más que la precisión del precio.

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

Orden límite — Se ejecuta solo al precio que especifiques o a uno mejor. Queda a la espera en el libro de órdenes hasta que se ejecute, se cancele o caduque.

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

Orden stop — Una orden condicional que se activa cuando el mercado alcanza un precio de disparo. Se usa para stop-loss y entradas de ruptura (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",
})

Para gestionar órdenes existentes: consulta las órdenes abiertas con GET /orders?status=open, cancela una orden concreta con DELETE /orders/{orderId}, o cancela todas las órdenes abiertas de un símbolo con DELETE /orders?symbol=BTC-USD. Para la gestión de posiciones, GET /positions devuelve todas las posiciones abiertas con precio de entrada, cantidad, PnL no realizado y precio de liquidación.

La API WebSocket de GaiaEx usa un modelo de suscripción/desuscripción. Tras conectarte, envías mensajes de suscripción especificando qué canales quieres recibir. Tanto los canales públicos (datos de mercado) como los privados (eventos de cuenta) están disponibles en la misma conexión.

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

El canal account.orders envía actualizaciones cada vez que una de tus órdenes se ejecuta, se ejecuta parcialmente o se cancela — eliminando la necesidad de consultar el endpoint REST repetidamente. El canal account.positions transmite actualizaciones de PnL y margen en tiempo real. Combinado con los canales públicos de datos de mercado, una única conexión WebSocket proporciona todo lo que necesita un bot de trading para operar.

Implementa siempre un mecanismo de heartbeat: GaiaEx envía frames de ping periódicos, y tu cliente debe responder con frames de pong. Si no se recibe ningún pong en 30 segundos, el servidor cierra la conexión. Por tu lado, si no llegan datos durante 30 segundos, asume que la conexión está muerta y reconéctate.

Vamos a juntarlo todo en un bot de trading mínimo pero funcional. El bot monitoriza el precio de BTC-USD vía WebSocket, y cuando el precio cae por debajo de un objetivo, coloca una orden límite de compra. Cuando la posición está abierta y el precio sube por encima de un nivel de toma de beneficios, cierra la posición.

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

Esto es deliberadamente sencillo. Un bot de producción añadiría: manejo de errores con try/except alrededor de cada llamada a la API y reconexión automática; lógica de reintentos con backoff exponencial para fallos transitorios; seguimiento de posiciones a través del canal WebSocket account.positions en lugar de un indicador booleano; límites de riesgo que detengan el trading tras alcanzar una pérdida diaria máxima; y registro (logging) que guarde cada decisión y respuesta de la API para el análisis posterior a las operaciones.

La arquitectura de monedero MPC de GaiaEx significa que tu bot nunca maneja claves privadas en bruto — la firma la gestiona la infraestructura de claves distribuidas de la plataforma. Esto reduce la superficie de seguridad en comparación con los bots que gestionan sus propias claves de monedero, donde un único compromiso puede vaciar todos los fondos. Combinado con la lista blanca de IP en la clave de API y la capa de autenticación HMAC, obtienes defensa en profundidad para el trading automatizado.

Empieza en pequeño: despliega con el tamaño de posición mínimo, monitoriza durante 48 horas, verifica que las ejecuciones coinciden con lo esperado, y luego escala gradualmente. Los mejores bots de trading se construyen de forma incremental, no en un solo sprint de programación.