Institutional SDK & Bot Integration Guide
Map Institutional Futures authentication, symbols, orders, positions, and WebSocket flows to GaiaEx; funding remains an in-app wallet step.
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.
Institutional SDK & CCXT Integration Guide
GaiaEx provides 100% 1:1 drop-in compatibility with the GaiaEx Unified Futures /fapi/v1/* and /fapi/v2/* REST API. Institutional trading bots, CCXT strategies, and quantitative Python/TypeScript SDKs work without rewriting endpoints, parameter names, or signature logic.
ZERO-CODE-CHANGE MIGRATION
To migrate a working GaiaEx Unified Futures integration in under 2 minutes, simply change your REST base URL from https://openapi.gaiaex.com to https://openapi.gaiaex.com and pass your GaiaEx API key and secret via the standard X-MBX-APIKEY header + query/form HMAC-SHA256 signature. Your wallet address is resolved automatically on the server from your API key.
1:1 Authentication Parity
GaiaEx uses the exact same authentication scheme as GaiaEx Unified Futures on all /fapi/v1/* and /fapi/v2/* routes:
| Component | GaiaEx Unified Futures | GaiaEx (/fapi/v1/* & /fapi/v2/*) |
|---|---|---|
| API Key Header | X-MBX-APIKEY | X-MBX-APIKEY (identical) |
| Timestamp | Query/form param: timestamp= (ms) | Query/form param: timestamp= (ms, identical) |
| Recv Window | Query/form param: recvWindow=5000 | Query/form param: recvWindow=5000 (identical) |
| Signature | Query/form param: signature= | Query/form param: signature= (identical) |
| Signature Input | HMAC-SHA256(secret, query_or_form_body) | HMAC-SHA256(secret, query_or_form_body) (identical) |
| Account Resolution | Resolved from X-MBX-APIKEY | Resolved automatically from X-MBX-APIKEY |
Signing Example (1:1 Drop-In)
import hmac, hashlib, time
query = f"symbol=BTCUSDC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=0.1&price=65000.00×tamp={int(time.time() * 1000)}"
signature = hmac.new(secret.encode(), query.encode(), hashlib.sha256).hexdigest()
url = f"https://openapi.gaiaex.com/fapi/v1/order?{query}&signature={signature}"
headers = {"X-MBX-APIKEY": api_key}Base URL
| Protocol | GaiaEx Unified Futures | GaiaEx Drop-In |
|---|---|---|
| REST API | https://openapi.gaiaex.com | https://openapi.gaiaex.com |
| WebSocket | wss://openapi.gaiaex.com | wss://openapi.gaiaex.com |
Symbol Format
On /fapi/v1/* and /fapi/v2/*, GaiaEx accepts standard concatenated GaiaEx symbols (BTCUSDC, ETHUSDC, BTCUSDT, ETHUSDT, SOLUSDC) and routes them directly to the corresponding USDC-margined or USDT-margined perpetual contract.
| Contract | Symbol on /fapi/v1/* & /fapi/v2/* | Margin Asset |
|---|---|---|
| Bitcoin Perp (USDC) | BTCUSDC | USDC |
| Bitcoin Perp (USDT) | BTCUSDT | USDT |
| Ethereum Perp (USDC) | ETHUSDC | USDC |
| Ethereum Perp (USDT) | ETHUSDT | USDT |
| Solana Perp (USDC) | SOLUSDC | USDC |
Query GET /fapi/v1/exchangeInfo at any time to inspect the full list of 167+ active symbols, precision filters (PRICE_FILTER, LOT_SIZE, MIN_NOTIONAL), and margin assets.
1:1 Endpoint Parity
Public Market Data (/fapi/v1/*)
All standard GaiaEx Unified Futures public market data routes are supported 1:1 at https://openapi.gaiaex.com:
| Action | GaiaEx Unified Futures | GaiaEx |
|---|---|---|
| Test connectivity | GET /fapi/v1/ping | GET /fapi/v1/ping |
| Server time | GET /fapi/v1/time | GET /fapi/v1/time |
| Exchange information | GET /fapi/v1/exchangeInfo | GET /fapi/v1/exchangeInfo |
| Order book depth | GET /fapi/v1/depth | GET /fapi/v1/depth |
| Recent trades | GET /fapi/v1/trades | GET /fapi/v1/trades |
| Compressed/Aggregate trades | GET /fapi/v1/aggTrades | GET /fapi/v1/aggTrades |
| Kline/Candlestick data | GET /fapi/v1/klines | GET /fapi/v1/klines |
| Continuous contract klines | GET /fapi/v1/continuousKlines | GET /fapi/v1/continuousKlines |
| Mark price klines | GET /fapi/v1/markPriceKlines | GET /fapi/v1/markPriceKlines |
| Index price klines | GET /fapi/v1/indexPriceKlines | GET /fapi/v1/indexPriceKlines |
| Mark price & funding rate | GET /fapi/v1/premiumIndex | GET /fapi/v1/premiumIndex |
| Funding rate history | GET /fapi/v1/fundingRate | GET /fapi/v1/fundingRate |
| 24hr ticker price change | GET /fapi/v1/ticker/24hr | GET /fapi/v1/ticker/24hr |
| Symbol price ticker | GET /fapi/v1/ticker/price | GET /fapi/v1/ticker/price |
| Symbol order book ticker | GET /fapi/v1/ticker/bookTicker | GET /fapi/v1/ticker/bookTicker |
| Open interest | GET /fapi/v1/openInterest | GET /fapi/v1/openInterest |
| Notional & leverage brackets | GET /fapi/v1/leverageBracket | GET /fapi/v1/leverageBracket |
| Multi-TF technical signals | N/A (GaiaEx extension) | GET /fapi/v1/technicals |
Authenticated Trading & Account (/fapi/v1/* & /fapi/v2/*)
All authenticated routes accept standard X-MBX-APIKEY + query/form HMAC-SHA256 signatures:
| Action | GaiaEx Unified Futures | GaiaEx |
|---|---|---|
| New order | POST /fapi/v1/order | POST /fapi/v1/order |
| Test new order (dry-run) | POST /fapi/v1/order/test | POST /fapi/v1/order/test |
| Cancel order | DELETE /fapi/v1/order | DELETE /fapi/v1/order |
| Modify order | PUT /fapi/v1/order | PUT /fapi/v1/order |
| Query order | GET /fapi/v1/order | GET /fapi/v1/order |
| Place multiple orders | POST /fapi/v1/batchOrders | POST /fapi/v1/batchOrders |
| Cancel multiple orders | DELETE /fapi/v1/batchOrders | DELETE /fapi/v1/batchOrders |
| Cancel all open orders | DELETE /fapi/v1/allOpenOrders | DELETE /fapi/v1/allOpenOrders |
| Auto-cancel all open orders | POST /fapi/v1/countdownCancelAll | POST /fapi/v1/countdownCancelAll |
| Current open orders | GET /fapi/v1/openOrders | GET /fapi/v1/openOrders |
| All orders | GET /fapi/v1/allOrders | GET /fapi/v1/allOrders |
| Futures account balance V2 | GET /fapi/v2/balance | GET /fapi/v2/balance |
| Account information V2 | GET /fapi/v2/account | GET /fapi/v2/account |
| Position information V2 | GET /fapi/v2/positionRisk | GET /fapi/v2/positionRisk |
| Change initial leverage | POST /fapi/v1/leverage | POST /fapi/v1/leverage |
| Change margin type | POST /fapi/v1/marginType | POST /fapi/v1/marginType |
| Position mode (One-Way / Hedge) | GET/POST /fapi/v1/positionSide/dual | GET/POST /fapi/v1/positionSide/dual |
| Multi-Assets mode | GET/POST /fapi/v1/multiAssetsMargin | GET/POST /fapi/v1/multiAssetsMargin |
| Account trade list | GET /fapi/v1/userTrades | GET /fapi/v1/userTrades |
| Income history | GET /fapi/v1/income | GET /fapi/v1/income |
| Commission rate | GET /fapi/v1/commissionRate | GET /fapi/v1/commissionRate |
| Position ADL quantile | GET /fapi/v1/adlQuantile | GET /fapi/v1/adlQuantile |
| User's force orders | GET /fapi/v1/forceOrders | GET /fapi/v1/forceOrders |
| Start user data stream | POST /fapi/v1/listenKey | POST /fapi/v1/listenKey |
| Keepalive user data stream | PUT /fapi/v1/listenKey | PUT /fapi/v1/listenKey |
| Close user data stream | DELETE /fapi/v1/listenKey | DELETE /fapi/v1/listenKey |
Spot Market Data, Trading & Account (/sapi/v1/* & /api/v3/*)
Spot endpoints are available identically under both /sapi/v1/* and /api/v3/*:
| Action | GaiaEx Spot | GaiaEx |
|---|---|---|
| Spot exchange info | GET /api/v3/exchangeInfo | GET /sapi/v1/exchangeInfo & GET /api/v3/exchangeInfo |
| Spot order book | GET /api/v3/depth | GET /sapi/v1/depth & GET /api/v3/depth |
| Spot recent trades | GET /api/v3/trades | GET /sapi/v1/trades & GET /api/v3/trades |
| Spot klines | GET /api/v3/klines | GET /sapi/v1/klines & GET /api/v3/klines |
| Spot 24hr / price ticker | GET /api/v3/ticker/24hr | GET /sapi/v1/ticker/24hr & GET /api/v3/ticker/24hr |
| New / cancel / query spot order | POST/DELETE/GET /api/v3/order | POST/DELETE/GET /sapi/v1/order & /api/v3/order |
| Open spot orders / cancel all | GET/DELETE /api/v3/openOrders | GET/DELETE /sapi/v1/openOrders & /api/v3/openOrders |
| Spot account balances | GET /api/v3/account | GET /sapi/v1/account & GET /api/v3/account |
| Spot trade fills | GET /api/v3/myTrades | GET /sapi/v1/myTrades & GET /api/v3/myTrades |
Self-Custody & Architectural Notes
- Rate Limit Headers: Every response emits
X-MBX-USED-WEIGHT-1M,X-MBX-USED-WEIGHT, and (on trading routes)X-MBX-ORDER-COUNT-1M. - Signing Algorithm: GaiaEx uses
HMAC-SHA256for API keys (RSA and Ed25519 asymmetric key types are not used). - Order Modify (
PUT /fapi/v1/order): Modifying an open USDC perpetual limit order atomically cancels and replaces the order on-chain; always read the returnedorderIdfrom the response. - Funding Scope: Because GaiaEx is self-custodial, API keys have strictly
readandtradescopes. Deposits and withdrawals require an in-app wallet signature and passkey step-up.
Order Parameters (1:1 Compatible)
POST /fapi/v1/order accepts the exact same parameters on GaiaEx as on GaiaEx Unified Futures:
| Parameter | Type | Required | Description |
|---|---|---|---|
symbol | STRING | YES | Trading pair, e.g. ETHUSDC, BTCUSDC, ETHUSDT |
side | ENUM | YES | BUY or SELL |
type | ENUM | YES | LIMIT, MARKET, STOP, TAKE_PROFIT, STOP_MARKET, TAKE_PROFIT_MARKET |
quantity | DECIMAL | YES | Order quantity in base asset units |
price | DECIMAL | NO | Order price (required for LIMIT orders) |
timeInForce | ENUM | NO | GTC, IOC, FOK, or GTX (Post-Only) |
reduceOnly | STRING | NO | "true" or "false" |
newClientOrderId | STRING | NO | Unique client order ID |
timestamp | LONG | YES | Millisecond epoch timestamp |
recvWindow | LONG | NO | Validity window in ms (default 5000) |
signature | STRING | YES | HMAC-SHA256 hex digest |
Standard GaiaEx Endpoint Configuration
BASE = "https://openapi.gaiaex.com"
# POST /fapi/v1/order with X-MBX-APIKEYAfter (GaiaEx Base URL — Zero Logic Changes)
import hmac, hashlib, time, os, urllib.parse, requests
API_KEY, API_SECRET = os.environ["GAIAEX_API_KEY"], os.environ["GAIAEX_API_SECRET"]
BASE = "https://openapi.gaiaex.com"
params = {
"symbol": "ETHUSDC",
"side": "BUY",
"type": "LIMIT",
"timeInForce": "GTC",
"quantity": "0.1",
"price": "3500.00",
"timestamp": int(time.time() * 1000),
}
query = urllib.parse.urlencode(params)
sig = hmac.new(API_SECRET.encode(), query.encode(), hashlib.sha256).hexdigest()
order = requests.post(
f"{BASE}/fapi/v1/order?{query}&signature={sig}",
headers={"X-MBX-APIKEY": API_KEY},
).json()Complete Migration Example
A complete end-to-end trading bot using /fapi/v1/* and /fapi/v2/* against https://openapi.gaiaex.com:
import hmac, hashlib, time, os, urllib.parse, requests
API_KEY, API_SECRET = os.environ["GAIAEX_API_KEY"], os.environ["GAIAEX_API_SECRET"]
BASE = "https://openapi.gaiaex.com"
def fapi_request(method: str, path: str, params: dict | None = None):
p = dict(params or {})
p["timestamp"] = int(time.time() * 1000)
query = urllib.parse.urlencode(p)
sig = hmac.new(API_SECRET.encode(), query.encode(), hashlib.sha256).hexdigest()
url = f"{BASE}{path}?{query}&signature={sig}"
return requests.request(method, url, headers={"X-MBX-APIKEY": API_KEY}).json()
# 1. Get account balances (/fapi/v2/balance)
balance = fapi_request("GET", "/fapi/v2/balance")
print("Balances:", balance)
# 2. Check open positions (/fapi/v2/positionRisk)
positions = fapi_request("GET", "/fapi/v2/positionRisk", {"symbol": "ETHUSDC"})
print("Positions:", positions)
# 3. Set leverage (/fapi/v1/leverage)
fapi_request("POST", "/fapi/v1/leverage", {"symbol": "ETHUSDC", "leverage": 10})
# 4. Place limit order (/fapi/v1/order)
order = fapi_request("POST", "/fapi/v1/order", {
"symbol": "ETHUSDC",
"side": "BUY",
"type": "LIMIT",
"timeInForce": "GTC",
"quantity": "0.1",
"price": "3500.00",
})
print("Order placed:", order)
# 5. Cancel all open orders (/fapi/v1/allOpenOrders)
fapi_request("DELETE", "/fapi/v1/allOpenOrders", {"symbol": "ETHUSDC"})GaiaEx ADVANTAGE
GaiaEx is fully non-custodial — your funds stay on-chain while giving you GaiaEx Unified Futures API ergonomics, no manual KYC gate for API key generation, and verifiable on-chain settlement.