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 permissions —
read-only agents for monitoring and analytics;read + tradeagents 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 can | Agent cannot |
|---|---|
| Place, cancel, and modify perpetual and spot orders | Deposit USDC into the account |
| Close positions; set TP/SL | Withdraw USDC off the platform |
| Change leverage and margin mode | Transfer assets on-chain (sendAsset, dex-transfer) |
| Read balances, positions, fills, order history, funding | Execute wallet swaps |
| Subscribe to public and private WebSocket streams | Register or authenticate passkeys |
| Query market data, orderbooks, candles, technicals | Complete the account handshake |
| Read referral and affiliate data | Create, 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:
- Human creates API key in GaiaEx mobile app → sets permissions to
["read", "trade"], adds IP whitelist for agent server - Store credentials in
config.jsonon the agent's server (see Security Best Practices) - Agent loads credentials and initializes the API client
- 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.