GaiaExGaiaEx
API

Institutional SDK & Bot Integration Guide

Map Institutional Futures authentication, symbols, orders, positions, and WebSocket flows to GaiaEx; funding remains an in-app wallet step.

AI AGENT READYEquip Claude Code, OpenAI Codex & Antigravity (`agy`) with Official GaiaEx Skills
CLAUDE CODESKILL.md
Claude SKILL.md

Drop-in Claude Code skill with HMAC-SHA256 signing, /fapi/v1 & /fapi/v2 schemas, and secret-redaction guardrails.

Raw ↗
OPENAI CODEXAGENTS.md
Codex AGENTS.md

Drop-in repository AGENTS.md for OpenAI Codex CLI — tick-size rules, rate-limit budgets, and self-custody boundaries.

Raw ↗
ANTIGRAVITYAGY.md
Antigravity AGY.md

Google Antigravity (agy) & Gemini agent spec with verified async Python WebSocket + REST execution templates.

Raw ↗
UNIVERSAL LLMllms.txt
/llms.txt Index

Single-URL machine-readable index of all GaiaEx documentation pages, OpenAPI 3.0 schema, and Postman collection.

Raw ↗

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:

ComponentGaiaEx Unified FuturesGaiaEx (/fapi/v1/* & /fapi/v2/*)
API Key HeaderX-MBX-APIKEYX-MBX-APIKEY (identical)
TimestampQuery/form param: timestamp= (ms)Query/form param: timestamp= (ms, identical)
Recv WindowQuery/form param: recvWindow=5000Query/form param: recvWindow=5000 (identical)
SignatureQuery/form param: signature=Query/form param: signature= (identical)
Signature InputHMAC-SHA256(secret, query_or_form_body)HMAC-SHA256(secret, query_or_form_body) (identical)
Account ResolutionResolved from X-MBX-APIKEYResolved 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&timestamp={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

ProtocolGaiaEx Unified FuturesGaiaEx Drop-In
REST APIhttps://openapi.gaiaex.comhttps://openapi.gaiaex.com
WebSocketwss://openapi.gaiaex.comwss://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.

ContractSymbol on /fapi/v1/* & /fapi/v2/*Margin Asset
Bitcoin Perp (USDC)BTCUSDCUSDC
Bitcoin Perp (USDT)BTCUSDTUSDT
Ethereum Perp (USDC)ETHUSDCUSDC
Ethereum Perp (USDT)ETHUSDTUSDT
Solana Perp (USDC)SOLUSDCUSDC

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:

ActionGaiaEx Unified FuturesGaiaEx
Test connectivityGET /fapi/v1/pingGET /fapi/v1/ping
Server timeGET /fapi/v1/timeGET /fapi/v1/time
Exchange informationGET /fapi/v1/exchangeInfoGET /fapi/v1/exchangeInfo
Order book depthGET /fapi/v1/depthGET /fapi/v1/depth
Recent tradesGET /fapi/v1/tradesGET /fapi/v1/trades
Compressed/Aggregate tradesGET /fapi/v1/aggTradesGET /fapi/v1/aggTrades
Kline/Candlestick dataGET /fapi/v1/klinesGET /fapi/v1/klines
Continuous contract klinesGET /fapi/v1/continuousKlinesGET /fapi/v1/continuousKlines
Mark price klinesGET /fapi/v1/markPriceKlinesGET /fapi/v1/markPriceKlines
Index price klinesGET /fapi/v1/indexPriceKlinesGET /fapi/v1/indexPriceKlines
Mark price & funding rateGET /fapi/v1/premiumIndexGET /fapi/v1/premiumIndex
Funding rate historyGET /fapi/v1/fundingRateGET /fapi/v1/fundingRate
24hr ticker price changeGET /fapi/v1/ticker/24hrGET /fapi/v1/ticker/24hr
Symbol price tickerGET /fapi/v1/ticker/priceGET /fapi/v1/ticker/price
Symbol order book tickerGET /fapi/v1/ticker/bookTickerGET /fapi/v1/ticker/bookTicker
Open interestGET /fapi/v1/openInterestGET /fapi/v1/openInterest
Notional & leverage bracketsGET /fapi/v1/leverageBracketGET /fapi/v1/leverageBracket
Multi-TF technical signalsN/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:

ActionGaiaEx Unified FuturesGaiaEx
New orderPOST /fapi/v1/orderPOST /fapi/v1/order
Test new order (dry-run)POST /fapi/v1/order/testPOST /fapi/v1/order/test
Cancel orderDELETE /fapi/v1/orderDELETE /fapi/v1/order
Modify orderPUT /fapi/v1/orderPUT /fapi/v1/order
Query orderGET /fapi/v1/orderGET /fapi/v1/order
Place multiple ordersPOST /fapi/v1/batchOrdersPOST /fapi/v1/batchOrders
Cancel multiple ordersDELETE /fapi/v1/batchOrdersDELETE /fapi/v1/batchOrders
Cancel all open ordersDELETE /fapi/v1/allOpenOrdersDELETE /fapi/v1/allOpenOrders
Auto-cancel all open ordersPOST /fapi/v1/countdownCancelAllPOST /fapi/v1/countdownCancelAll
Current open ordersGET /fapi/v1/openOrdersGET /fapi/v1/openOrders
All ordersGET /fapi/v1/allOrdersGET /fapi/v1/allOrders
Futures account balance V2GET /fapi/v2/balanceGET /fapi/v2/balance
Account information V2GET /fapi/v2/accountGET /fapi/v2/account
Position information V2GET /fapi/v2/positionRiskGET /fapi/v2/positionRisk
Change initial leveragePOST /fapi/v1/leveragePOST /fapi/v1/leverage
Change margin typePOST /fapi/v1/marginTypePOST /fapi/v1/marginType
Position mode (One-Way / Hedge)GET/POST /fapi/v1/positionSide/dualGET/POST /fapi/v1/positionSide/dual
Multi-Assets modeGET/POST /fapi/v1/multiAssetsMarginGET/POST /fapi/v1/multiAssetsMargin
Account trade listGET /fapi/v1/userTradesGET /fapi/v1/userTrades
Income historyGET /fapi/v1/incomeGET /fapi/v1/income
Commission rateGET /fapi/v1/commissionRateGET /fapi/v1/commissionRate
Position ADL quantileGET /fapi/v1/adlQuantileGET /fapi/v1/adlQuantile
User's force ordersGET /fapi/v1/forceOrdersGET /fapi/v1/forceOrders
Start user data streamPOST /fapi/v1/listenKeyPOST /fapi/v1/listenKey
Keepalive user data streamPUT /fapi/v1/listenKeyPUT /fapi/v1/listenKey
Close user data streamDELETE /fapi/v1/listenKeyDELETE /fapi/v1/listenKey

Spot Market Data, Trading & Account (/sapi/v1/* & /api/v3/*)

Spot endpoints are available identically under both /sapi/v1/* and /api/v3/*:

ActionGaiaEx SpotGaiaEx
Spot exchange infoGET /api/v3/exchangeInfoGET /sapi/v1/exchangeInfo & GET /api/v3/exchangeInfo
Spot order bookGET /api/v3/depthGET /sapi/v1/depth & GET /api/v3/depth
Spot recent tradesGET /api/v3/tradesGET /sapi/v1/trades & GET /api/v3/trades
Spot klinesGET /api/v3/klinesGET /sapi/v1/klines & GET /api/v3/klines
Spot 24hr / price tickerGET /api/v3/ticker/24hrGET /sapi/v1/ticker/24hr & GET /api/v3/ticker/24hr
New / cancel / query spot orderPOST/DELETE/GET /api/v3/orderPOST/DELETE/GET /sapi/v1/order & /api/v3/order
Open spot orders / cancel allGET/DELETE /api/v3/openOrdersGET/DELETE /sapi/v1/openOrders & /api/v3/openOrders
Spot account balancesGET /api/v3/accountGET /sapi/v1/account & GET /api/v3/account
Spot trade fillsGET /api/v3/myTradesGET /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-SHA256 for 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 returned orderId from the response.
  • Funding Scope: Because GaiaEx is self-custodial, API keys have strictly read and trade scopes. 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:

ParameterTypeRequiredDescription
symbolSTRINGYESTrading pair, e.g. ETHUSDC, BTCUSDC, ETHUSDT
sideENUMYESBUY or SELL
typeENUMYESLIMIT, MARKET, STOP, TAKE_PROFIT, STOP_MARKET, TAKE_PROFIT_MARKET
quantityDECIMALYESOrder quantity in base asset units
priceDECIMALNOOrder price (required for LIMIT orders)
timeInForceENUMNOGTC, IOC, FOK, or GTX (Post-Only)
reduceOnlySTRINGNO"true" or "false"
newClientOrderIdSTRINGNOUnique client order ID
timestampLONGYESMillisecond epoch timestamp
recvWindowLONGNOValidity window in ms (default 5000)
signatureSTRINGYESHMAC-SHA256 hex digest

Standard GaiaEx Endpoint Configuration

BASE = "https://openapi.gaiaex.com"
# POST /fapi/v1/order with X-MBX-APIKEY

After (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.