Negociando com a API da GaiaEx: Um Guia para Desenvolvedores

A GaiaEx é uma corretora descentralizada construída na Hyperliquid L1, e sua API te dá acesso programático a tudo o que a plataforma oferece — dados de mercado, gestão de ordens, rastreamento de posições e streaming em tempo real. Seja você construindo um bot de negociação, um dashboard de portfólio ou um sistema de alertas personalizado, a API é seu ponto de entrada.

A API é dividida em dois protocolos complementares:

• API REST — Endpoints de requisição-resposta para colocar ordens, consultar saldos, buscar histórico de negociações e gerenciar chaves de API. Use REST quando você precisar fazer algo ou pedir algo específico.
• API WebSocket — Conexões de streaming persistentes para dados de mercado em tempo real (negociações, atualizações do livro de ofertas, tickers) e eventos privados de conta (execuções de ordens, mudanças de posição). Use WebSocket quando você precisar reagir a algo no exato momento em que acontece.

Por baixo dos panos, a GaiaEx se conecta ao livro de ofertas on-chain da Hyperliquid L1. Suas ordens são casadas on-chain com execução determinística, e seus fundos são protegidos por carteiras MPC (Computação Multipartidária) — o que significa que nenhuma parte única (nem mesmo a GaiaEx) detém sua chave privada completa. A API abstrai a complexidade da blockchain: você envia uma requisição JSON para colocar uma ordem, e a plataforma cuida da assinatura, do envio e da confirmação na L1.

A URL base para a API REST segue as convenções padrão: https://api.gaiaex.com/v1/. Conexões WebSocket são estabelecidas em wss://api.gaiaex.com/ws/v1/. Todos os endpoints retornam JSON, todos os timestamps estão em milissegundos desde a epoch (UTC), e todos os valores monetários são strings para evitar problemas de precisão de ponto flutuante.

Para acessar endpoints privados (colocar ordens, consultar seus saldos), você precisa de um par de chaves de API. Gere uma no dashboard da GaiaEx em Configurações → Chaves de API. Você receberá dois valores:

• API Key — Um identificador público enviado em toda requisição. Pense nele como seu nome de usuário.
• API Secret — Uma chave privada usada para assinar requisições. Nunca a compartilhe, nunca a envie para controle de versão, nunca a envie em um cabeçalho de requisição.

A GaiaEx usa assinatura HMAC-SHA256 para autenticar requisições privadas. O processo: concatene o timestamp, o método HTTP, o caminho da requisição e o corpo em uma única string, então calcule uma assinatura HMAC usando seu secret. O servidor executa o mesmo cálculo e compara as assinaturas.

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

O componente de timestamp evita ataques de repetição (replay attacks): o servidor rejeita qualquer requisição em que o timestamp esteja a mais de 30 segundos do relógio do servidor. Certifique-se de que o relógio da sua máquina esteja sincronizado via NTP.

Os endpoints de dados de mercado são públicos — sem necessidade de autenticação. Eles fornecem as informações brutas que você precisa para tomar decisões de negociação.

Livro de ofertas (order book) — Retorna os bids e asks atuais para um determinado símbolo. O parâmetro depth controla quantos níveis de preço são retornados (padrão 20, máximo 100).

# Buscar o livro de ofertas de BTC-USD (top 10 níveis)
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}")

Negociações recentes — Retorna as últimas N negociações executadas para um símbolo. Cada negociação inclui o preço, a quantidade, o lado (se o taker estava comprando ou vendendo) e o timestamp.

# Buscar as últimas 50 negociações de 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"Média das últimas 50 negociações: ${avg_price:.2f}")

Ticker — Um resumo do estado atual do mercado: último preço, máxima/mínima de 24h, volume de 24h, melhor bid/ask e variação percentual. Ideal para construir watchlists ou buscar volatilidade.

# Buscar todos os 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 dados em tempo real, use os feeds WebSocket em vez de fazer polling desses endpoints. Os endpoints REST têm limites de taxa e introduzem latência; o WebSocket entrega atualizações no instante em que ocorrem na Hyperliquid L1.

Colocar ordens é a ação central em qualquer sistema de negociação. A GaiaEx suporta três tipos de ordem através do endpoint POST /orders:

Ordem a mercado — Executa imediatamente no melhor preço disponível. Use quando a velocidade de execução importa mais do que a precisão do preço.

# Comprar 0.1 BTC a preço de mercado
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "buy",
    "type": "market",
    "quantity": "0.1",
})
print(f"Executado a {order['avgPrice']}")

Ordem limitada — Executa apenas no seu preço especificado ou melhor. Fica no livro de ofertas até ser executada, cancelada ou expirar.

# Vender 2 ETH a $3.500 ou mais
order = signed_request("POST", "/orders", {
    "symbol": "ETH-USD",
    "side": "sell",
    "type": "limit",
    "price": "3500.00",
    "quantity": "2.0",
    "timeInForce": "GTC",  # Válida até cancelar
})

Ordem stop — Uma ordem condicional que se torna ativa quando o mercado atinge um preço de acionamento. Usada para stop-loss e entradas em rompimento.

# Stop-loss: vender 0.5 BTC se o preço cair para $58,000
order = signed_request("POST", "/orders", {
    "symbol": "BTC-USD",
    "side": "sell",
    "type": "stop_market",
    "stopPrice": "58000.00",
    "quantity": "0.5",
})

Para gerenciar ordens existentes: consulte ordens abertas com GET /orders?status=open, cancele uma ordem específica com DELETE /orders/{orderId}, ou cancele todas as ordens abertas de um símbolo com DELETE /orders?symbol=BTC-USD. Para gestão de posições, GET /positions retorna todas as posições abertas com preço de entrada, quantidade, P&L não realizado e preço de liquidação.

A API WebSocket da GaiaEx usa um modelo de subscribe/unsubscribe. Após conectar, você envia mensagens de subscrição especificando quais canais quer receber. Tanto canais públicos (dados de mercado) quanto privados (eventos de conta) estão disponíveis na mesma conexão.

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:
        # Autenticar para canais privados
        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,
        }))

        # Assinar canais públicos + privados
        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"Atualização de ordem: {data['status']} {data['orderId']}")
            elif ch == "trades.BTC-USD":
                print(f"Negociação: {data['price']} x {data['quantity']}")

asyncio.run(connect_gaiaex())

O canal account.orders envia atualizações sempre que uma de suas ordens é executada, parcialmente executada ou cancelada — eliminando a necessidade de fazer polling do endpoint REST. O canal account.positions transmite atualizações em tempo real de P&L e margem. Combinados com os canais públicos de dados de mercado, uma única conexão WebSocket fornece tudo o que um bot de negociação precisa para operar.

Sempre implemente um mecanismo de heartbeat: a GaiaEx envia frames ping periódicos, e seu cliente deve responder com frames pong. Se nenhum pong for recebido dentro de 30 segundos, o servidor fecha a conexão. Do seu lado, se nenhum dado chegar em 30 segundos, assuma que a conexão está morta e reconecte.

Vamos juntar tudo em um bot de negociação mínimo, mas funcional. O bot monitora o preço de BTC-USD via WebSocket, e quando o preço cai abaixo de um alvo, ele coloca uma ordem de compra limitada. Quando a posição está aberta e o preço sobe acima de um nível de realização de lucro, ele fecha a posição.

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:
        # Autenticação + assinatura (omitidas por brevidade)
        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"Ordem de COMPRA colocada: {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"Ordem de VENDA colocada: {order['orderId']}")
                position_open = False

asyncio.run(trading_bot())

Isso é deliberadamente simples. Um bot de produção adicionaria: tratamento de erros com try/except em torno de toda chamada de API e reconexão automática; lógica de retry com backoff exponencial para falhas transitórias; rastreamento de posição via o canal WebSocket account.positions em vez de uma flag booleana; limites de risco que interrompem a negociação após uma perda diária máxima; e logging que registra cada decisão e resposta de API para análise pós-negociação.

A arquitetura de carteira MPC da GaiaEx significa que seu bot nunca manipula chaves privadas brutas — a assinatura é tratada pela infraestrutura de chaves distribuídas da plataforma. Isso reduz a superfície de segurança em comparação a bots que gerenciam suas próprias chaves de carteira, onde um único comprometimento pode drenar todos os fundos. Combinado com o whitelisting de IP das chaves de API e a camada de autenticação HMAC, você obtém defesa em profundidade para negociação automatizada.

Comece pequeno: implante com o tamanho mínimo de posição, monitore por 48 horas, verifique se as execuções correspondem às expectativas, depois escale gradualmente. Os melhores bots de negociação são construídos incrementalmente, não em um único sprint de codificação.