API & WebSocket Servers
REST and WebSocket base URLs, connection endpoints, keep-alive requirements, and rate limits for GaiaEx API access.
SKILL.mdDrop-in Claude Code skill with HMAC-SHA256 signing, /fapi/v1 & /fapi/v2 schemas, and secret-redaction guardrails.
AGENTS.mdDrop-in repository AGENTS.md for OpenAI Codex CLI — tick-size rules, rate-limit budgets, and self-custody boundaries.
AGY.mdGoogle Antigravity (agy) & Gemini agent spec with verified async Python WebSocket + REST execution templates.
llms.txtSingle-URL machine-readable index of all GaiaEx documentation pages, OpenAPI 3.0 schema, and Postman collection.
REST Base URL
All REST API requests are sent to:
https://openapi.gaiaex.com| API Surface | Base URL / Prefix | Status |
|---|---|---|
| USDⓈ-M Perpetual Futures | https://openapi.gaiaex.com/fapi/v1 & /fapi/v2 | Live (1:1 GaiaEx compatible) |
| Spot Market & Trading | https://openapi.gaiaex.com/sapi/v1 & /api/v3 | Live (1:1 GaiaEx compatible) |
All endpoints return application/json and include X-MBX-USED-WEIGHT-1M rate-limit headers. Standard X-MBX-APIKEY + query/form HMAC-SHA256 authentication is used for all private trading and account endpoints.
WebSocket Servers
GaiaEx provides two WebSocket domains. Both connect to the same backend — choose whichever is convenient.
| Domain | Protocol | Purpose |
|---|---|---|
wss://openapi.gaiaex.com | WSS | Primary — REST + WS on the same domain |
wss://ws.gaiaex.com | WSS | Dedicated WS domain (shorter paths) |
INFO
Both domains use TLS (wss://). Unencrypted ws:// connections are not accepted in production.
Public Streams (No Auth)
Public streams do not require authentication. Connect directly with the symbol in the URL path.
| Stream | openapi.gaiaex.com | ws.gaiaex.com |
|---|---|---|
| Perp Order Book | wss://openapi.gaiaex.com/ws/market/{symbol} | wss://ws.gaiaex.com/market/{symbol} |
| Spot Order Book | wss://openapi.gaiaex.com/ws/market/spot/{symbol} | wss://ws.gaiaex.com/market/spot/{symbol} |
| Kline / Candlestick | wss://openapi.gaiaex.com/ws/candles/{symbol} | wss://ws.gaiaex.com/candles/{symbol} |
Replace {symbol} with the trading symbol, e.g. BTCUSDC, ETHUSDC, BTC, xyz:GOLD.
Private Streams (Auth Required)
Private user data streams support 1:1 GaiaEx listenKey authentication (obtained via POST /fapi/v1/listenKey with your X-MBX-APIKEY header). See the User Data Stream page for details.
| Stream | openapi.gaiaex.com | ws.gaiaex.com |
|---|---|---|
User Data Stream (1:1 GaiaEx listenKey) | wss://openapi.gaiaex.com/ws/{listenKey} | wss://ws.gaiaex.com/ws/{listenKey} |
Connection Notes
- Ping/Pong: Send a text message
"ping"to keep the connection alive. The server responds with"pong". Standard WebSocket ping/pong frames are also handled automatically. - ListenKey Keepalive: Call
PUT /fapi/v1/listenKeyevery 30 minutes to keep your user data stream active. - Reconnection: If the connection drops, reconnect with exponential backoff (1s, 2s, 4s, ..., max 30s).
- Full L2 Snapshots: Order book streams deliver full 20-level L2 snapshots on every update (no diff-depth sequence stitching required).
- Idle timeout: The nginx proxy is configured with a
proxy_read_timeoutof 86,400 seconds (24 hours).
| Feature | GaiaEx Futures | GaiaEx |
|---|---|---|
| User stream auth | POST /fapi/v1/listenKey → /ws/{listenKey} | POST /fapi/v1/listenKey → /ws/{listenKey} (1:1 identical) |
| User stream events | ACCOUNT_UPDATE, ORDER_TRADE_UPDATE | ACCOUNT_UPDATE, ORDER_TRADE_UPDATE (1:1 compatible) |
| Keepalive | PUT /fapi/v1/listenKey every 30m | PUT /fapi/v1/listenKey every 30m + WS ping/pong |
| Public order book | Diff depth or partial book | Full L2 snapshot at /ws/market/{symbol} |
Terminal Walkthrough
Step 1: Install wscat
npm install -g wscatStep 2: Connect to Public Orderbook
$ wscat -c wss://openapi.gaiaex.com/ws/market/BTC
Connected (press CTRL+C to quit)
< {"type":"orderbook","symbol":"BTC","bids":[["84250.00","1.234"],["84249.50","0.500"]],"asks":[["84251.50","0.800"]],"priceDecimals":2,"timestamp":1712345678000,"stale":false,"displayName":"BTC","feed_connected":true}
> ping
< pongStep 3: Connect to Private User Data Stream via listenKey
# 1. Obtain a listenKey using your API key
LISTEN_KEY=$(curl -s -X POST "https://openapi.gaiaex.com/fapi/v1/listenKey" \
-H "X-MBX-APIKEY: $GAIAEX_API_KEY" | jq -r .listenKey)
# 2. Connect to the WebSocket stream
$ wscat -c "wss://openapi.gaiaex.com/ws/${LISTEN_KEY}"
Connected (press CTRL+C to quit)
< {"e":"ACCOUNT_UPDATE","E":1743508800000,"T":1743508800000,"a":{"m":"ORDER","B":[{"a":"USDC","wb":"1000.00000000","cw":"850.00000000","bc":"0"}],"P":[]}}Step 4: Python — Multi-Symbol Monitoring
import asyncio
import json
import websockets
SYMBOLS = ["BTC", "ETH", "SOL"]
async def monitor_symbol(symbol: str):
uri = f"wss://openapi.gaiaex.com/ws/market/{symbol}"
async with websockets.connect(uri) as ws:
async for raw in ws:
msg = json.loads(raw)
if msg["type"] == "orderbook" and msg.get("bids"):
top_bid = msg["bids"][0]
print(f"{symbol}: {top_bid[0]} x {top_bid[1]}")
async def main():
await asyncio.gather(*(monitor_symbol(s) for s in SYMBOLS))
asyncio.run(main())Step 5: Python — Reconnection with Exponential Backoff
import asyncio
import json
import websockets
async def stream_with_reconnect(symbol: str):
delay = 1
while True:
try:
uri = f"wss://openapi.gaiaex.com/ws/market/{symbol}"
async with websockets.connect(uri) as ws:
delay = 1 # Reset on successful connect
async for raw in ws:
msg = json.loads(raw)
if msg["type"] == "orderbook":
print(f"{symbol}: {len(msg.get('bids', []))} bids, {len(msg.get('asks', []))} asks")
except (websockets.ConnectionClosed, OSError) as e:
print(f"Disconnected: {e}. Reconnecting in {delay}s...")
await asyncio.sleep(delay)
delay = min(delay * 2, 30) # Max 30s backoff
asyncio.run(stream_with_reconnect("ETH"))