GaiaExGaiaEx
API

AI Agent Integration Guide

Integrate AI trading agents with GaiaEx: no-KYC API keys, scoped permissions, HMAC authentication, and code examples for autonomous trading.

AI Agent Integration

GaiaEx is designed as a bounded execution layer for AI trading agents. You give the agent a trade-scoped API key, it trades against your pre-deposited balance, and the funds themselves stay under your self-custody at all times. The agent never has the ability to move money on or off the platform — that's the point.

WHY GaiaEx FOR AI AGENTS

  • Bounded risk — the worst an agent can do is trade badly within your deposited balance. It cannot withdraw, deposit, transfer, or swap on-chain.
  • Scoped permissionsread-only agents for monitoring and analytics; read + trade agents for execution
  • 167+ markets in one API — crypto perps (133 USDC-margined + 34 USDT-margined), RWA (stocks, commodities, forex), and venture tokens
  • WebSocket bidirectional — place orders directly over WebSocket for lowest latency
  • No manual identity verification for API access — API keys are issued from the mobile app after the user's in-app account setup

Agent Scope — What It Can and Cannot Do

API-key-authenticated agents operate strictly within a trading and read scope. The table below is the complete, accurate picture — please share it with the agent's system prompt so it understands its own capabilities.

Agent canAgent cannot
Place, cancel, and modify perpetual and spot ordersDeposit USDC into the account
Close positions; set TP/SLWithdraw USDC off the platform
Change leverage and margin modeTransfer assets on-chain (sendAsset, dex-transfer)
Read balances, positions, fills, order history, fundingExecute wallet swaps
Subscribe to public and private WebSocket streamsRegister or authenticate passkeys
Query market data, orderbooks, candles, technicalsComplete the account handshake
Read referral and affiliate dataCreate, modify, or delete API keys

FUNDING IS A MANUAL STEP

The user must fund the account in the GaiaEx mobile app before the agent runs. If the account runs out of USDC mid-strategy, the agent will start receiving insufficient-margin errors on new orders — it cannot top up on its own. When the user is ready to pull funds out, they do so in the mobile app, not through the agent.

Agent Authentication Flow

The recommended flow for AI agent authentication:

  1. Human creates API key in GaiaEx mobile app → sets permissions to ["read", "trade"], adds IP whitelist for agent server
  2. Store credentials in config.json on the agent's server (see Security Best Practices)
  3. Agent loads credentials and initializes the API client
  4. Agent trades autonomously within its permission scope
import hmac, hashlib, time, json, requests

with open("/secure/agent_config.json") as f:
    cfg = json.load(f)

API_KEY, API_SECRET = cfg["api_key"], cfg["api_secret"]
ADDRESS = cfg["user_address"]
BASE = "https://openapi.gaiaex.com/v1/trade"

def sign(method, path, body=""):
    ts = str(int(time.time() * 1000))
    sig = hmac.new(API_SECRET.encode(), (ts + method + path + body).encode(), hashlib.sha256).hexdigest()
    return {"X-GAIAEX-APIKEY": API_KEY, "X-GAIAEX-TIMESTAMP": ts, "X-GAIAEX-SIGNATURE": sig, "Content-Type": "application/json"}

# Verify connectivity
health = requests.get(BASE + "/health").json()
assert health["status"] == "ok"

# Agent can now trade
balance = requests.get(BASE + f"/user/{ADDRESS}/balance", headers=sign("GET", f"/user/{ADDRESS}/balance")).json()
if float(balance.get("available", 0)) > 100:
    body = json.dumps({"user_address": ADDRESS, "symbol": "ETH", "is_buy": True, "size": "0.05", "order_type": "market"})
    requests.post(BASE + "/order", headers=sign("POST", "/order", body), data=body)

SECURITY

Always use IP whitelisting for agent API keys. If the agent server is compromised, IP restrictions prevent the key from being used elsewhere.

Real-Time Data for AI Agents

For low-latency AI agents, use WebSocket streams instead of polling REST endpoints.

import asyncio
import websockets
import json

async def ai_agent():
    uri = "wss://openapi.gaiaex.com/ws/market/ETH"
    async with websockets.connect(uri) as ws:
        count = 0
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("type") == "orderbook":
                levels = msg.get("levels", [])
                best_bid = levels[0]["px"] if levels else "N/A"
                print(f"ETH best bid: {best_bid}")
                count += 1
                if count >= 5:
                    break

asyncio.run(ai_agent())

PRODUCTION TIP

For production AI agents, run the market data stream and the user data stream concurrently using asyncio.gather. This gives your agent real-time market data and instant position/order updates in a single event loop.