General Info & Authentication

• The base endpoint is: https://openapi.gaiaex.com
• GaiaEx implements the GaiaEx Unified Futures standard under /fapi/v1/* and /fapi/v2/*.
• All endpoints return either a JSON object or array.
• All time and timestamp related fields are in milliseconds (Unix epoch).
• Data is returned in ascending order unless otherwise specified.
• For GET and DELETE endpoints, parameters are sent as query strings. For POST and PUT endpoints, parameters can be sent as query strings or application/x-www-form-urlencoded request bodies.
• Your trading account is automatically resolved server-side from your X-MBX-APIKEY header — standard quantitative SDKs (ccxt, Python, TypeScript, Rust) and bots work as a 1:1 drop-in.

Each endpoint has a security type that determines how you interact with it.

• All trading and account endpoints under /fapi/v1/* and /fapi/v2/* accept SIGNED (X-MBX-APIKEY + HMAC-SHA256) authentication.
• Market data endpoints (/fapi/v1/ping, /fapi/v1/time, /fapi/v1/exchangeInfo, /fapi/v1/depth, /fapi/v1/klines, /fapi/v1/ticker/24hr) are public (NONE).

GaiaEx supports two authentication methods:

Method 1: 1:1 GaiaEx API Key + HMAC-SHA256 (Recommended for programmatic trading)

What HMAC-SHA256 is, in one paragraph. Your API secret never leaves your machine. For each request, you build a query string (or form body) that includes timestamp=<ms> (and optional recvWindow=<ms>, default 5000), compute HMAC-SHA256(api_secret, query_string_or_form_body), and append the resulting lowercase hex digest as signature=<hex>. You send your public key in the X-MBX-APIKEY HTTP header. The server resolves your wallet address automatically from the API key, recomputes the HMAC digest, and verifies they match.

What EIP-712 is, and why you don't need it for API trading. EIP-712 is a structured-data wallet signature used for on-chain actions (deposits, withdrawals, swaps, handshake). It requires a wallet private key and, in GaiaEx, is only produced by the mobile app's embedded wallet. API-key integrations never produce EIP-712 signatures — HMAC-SHA256 is the only signing you need. If a doc page mentions EIP-712, it's describing an in-app flow, not something you'll implement in your bot.

API keys are created in the GaiaEx mobile app (Settings > API Keys). Existing keys can be listed programmatically via the GET /api-keys endpoint, but creating, updating, and revoking keys all require a passkey step-up and are app-only — they cannot be performed headlessly via API key alone (see the API Keys page). Each signed request requires:

Signature construction:

payload = query_string_or_form_body   # includes timestamp=<ms> and optional recvWindow=<ms>, WITHOUT &signature=...
signature = HMAC-SHA256(api_secret, payload)

• query_string_or_form_body — all request parameters formatted as key=value&key2=value2...&timestamp=1712345678000 in the exact order sent on the wire.
• Append &signature=<hex> as the final parameter.

Example (Python):

import hmac
import hashlib
import time
import os
import requests

api_key = os.environ["GAIAEX_API_KEY"]
api_secret = os.environ["GAIAEX_API_SECRET"]

timestamp = int(time.time() * 1000)
query_string = f"timestamp={timestamp}&recvWindow=5000"

signature = hmac.new(
    api_secret.encode("utf-8"),
    query_string.encode("utf-8"),
    hashlib.sha256,
).hexdigest()

headers = {
    "X-MBX-APIKEY": api_key,
}

resp = requests.get(
    f"https://openapi.gaiaex.com/fapi/v2/balance?{query_string}&signature={signature}",
    headers=headers,
)
print(resp.json())

Example (curl):

TIMESTAMP=$(date +%s000)
QUERY="timestamp=${TIMESTAMP}&recvWindow=5000"
SIGNATURE=$(echo -n "$QUERY" | openssl dgst -sha256 -hmac "$GAIAEX_API_SECRET" | awk '{print $2}')

curl -s -H "X-MBX-APIKEY: $GAIAEX_API_KEY" \
     "https://openapi.gaiaex.com/fapi/v2/balance?${QUERY}&signature=${SIGNATURE}"

Method 2: Bearer Session Token (Web app / mobile only)

Session tokens are issued by the GaiaEx mobile app after the user completes an in-app wallet handshake. They are not obtainable from the public REST API and are not intended for programmatic integrations — use API keys instead.

Scope of the Public API

API keys can be used to trade, read account data (balances, positions, fills, order history, funding), manage orders and leverage, and query read-only wallet data (portfolio, swap quotes). They cannot:

• Deposit or withdraw funds
• Execute on-chain transfers or swaps
• Register or authenticate passkeys
• Complete the account handshake
• Create, modify, or delete API keys

These actions require the user's embedded-wallet signature and, in several cases, a passkey step-up — both performed in the GaiaEx mobile app. Users fund and defund accounts from the app; API integrations operate within the deposited balance.

This section uses concrete values at every step. If you plug the same secret and query string into your own code, you must get the exact same signature shown here. If you don't, your implementation has a bug — most likely in parameter ordering or URL encoding.

Example 1: GET Futures Balance (GET /fapi/v2/balance)

Goal: query your USDⓈ-M Futures account balances (wallet address is resolved automatically from X-MBX-APIKEY).

Example response (HTTP 200):

[
  {
    "accountAlias": "gaiaex-usdc",
    "asset": "USDC",
    "balance": "1523.47",
    "crossWalletBalance": "1523.47",
    "crossUnPnl": "18.92",
    "availableBalance": "892.10",
    "updateTime": 1712345679123
  },
  {
    "accountAlias": "gaiaex-usdt",
    "asset": "USDT",
    "balance": "500.00",
    "crossWalletBalance": "500.00",
    "crossUnPnl": "0.00",
    "availableBalance": "500.00",
    "updateTime": 1712345679123
  }
]

import hmac, hashlib, time, os, requests

# Load from environment variables (recommended)
api_key    = os.environ["GAIAEX_API_KEY"]
api_secret = os.environ["GAIAEX_API_SECRET"]

# Step 1-4: Build query string with timestamp
timestamp    = int(time.time() * 1000)
query_string = f"timestamp={timestamp}&recvWindow=5000"
print(f"Query to sign: {query_string}")

# Step 5-6: Compute HMAC-SHA256
signature = hmac.new(
    api_secret.encode("utf-8"),
    query_string.encode("utf-8"),
    hashlib.sha256,
).hexdigest()
print(f"Signature: {signature}")

# Step 7: Send request with X-MBX-APIKEY
resp = requests.get(
    f"https://openapi.gaiaex.com/fapi/v2/balance?{query_string}&signature={signature}",
    headers={"X-MBX-APIKEY": api_key},
)
print(f"Status: {resp.status_code}")
print(f"Response: {resp.json()}")

Example 2: POST Place Order (POST /fapi/v1/order)

Goal: place a limit buy order for 0.1 ETHUSDC at $3,500.00.

Example response (HTTP 200):

{
  "orderId": 41298374,
  "symbol": "ETHUSDC",
  "status": "NEW",
  "clientOrderId": "bot-a1b2c3",
  "price": "3500.00",
  "avgPrice": "0.00",
  "origQty": "0.1",
  "executedQty": "0.0",
  "cumQuote": "0.00",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "reduceOnly": false,
  "side": "BUY",
  "PositionSide": "BOTH",
  "updateTime": 1712345679456
}

Common rejection (HTTP 401, signature mismatch):

{"code": -1022, "msg": "Signature for this request is not valid."}

If you see this, the server computed a different digest than yours. Check, in order: (1) the parameter string you signed matches the exact parameter order sent on the wire; (2) &signature=... was not included in the signed input; (3) timestamp is in milliseconds (not seconds) and within recvWindow of the server clock.

import hmac, hashlib, time, os, urllib.parse, requests

api_key    = os.environ["GAIAEX_API_KEY"]
api_secret = os.environ["GAIAEX_API_SECRET"]

params = {
    "symbol": "ETHUSDC",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.1",
    "price": "3500.00",
    "timestamp": int(time.time() * 1000),
    "recvWindow": 5000,
}
query_string = urllib.parse.urlencode(params)
signature = hmac.new(
    api_secret.encode("utf-8"),
    query_string.encode("utf-8"),
    hashlib.sha256,
).hexdigest()

resp = requests.post(
    f"https://openapi.gaiaex.com/fapi/v1/order?{query_string}&signature={signature}",
    headers={"X-MBX-APIKEY": api_key},
)
print(resp.json())

Follow these rules to keep a production bot safe from the most common duplicate-order failure mode.

Recommended HTTP timeout

Set your client timeout to 20 seconds for POST /fapi/v1/order, PUT /fapi/v1/order, and DELETE /fapi/v1/order. Typical responses are under 2 seconds, but allow headroom for network spikes.

Never blind-retry a timeout

Idempotency via newClientOrderId

Pass a unique ASCII string (max 64 chars) as newClientOrderId in POST /fapi/v1/order. The server treats duplicate client order IDs from the same account within a 10-minute window as idempotent — it returns the existing order instead of creating a second one. Use this as belt-and-suspenders on every order:

import uuid
order = fapi_request("POST", "/fapi/v1/order", {
    "symbol":           "BTCUSDC",
    "side":             "BUY",
    "type":             "LIMIT",
    "timeInForce":      "GTC",
    "quantity":         "0.001",
    "price":            "79000",
    "newClientOrderId": f"bot-{uuid.uuid4().hex[:24]}",   # safe to retry
})

Modify order (PUT /fapi/v1/order)

A successful PUT /fapi/v1/order modifies the existing order on the book and returns the active orderId in the response. Always read orderId from the modify response for any subsequent cancel or modify calls.

Exponential backoff for transient errors

HTTP 429 (rate limited) and 502 (upstream unavailable) are transient — retry with jittered exponential backoff (e.g., 1s, 2s, 4s, up to 30s). HTTP 400 and 401 are not retryable without fixing the request.

• All SIGNED requests must include a timestamp parameter (Unix epoch in milliseconds).
• An optional recvWindow parameter (default 5000 ms, maximum 60000 ms) specifies how many milliseconds after timestamp the request remains valid.
• The server rejects requests where the timestamp is outside the recvWindow tolerance.
• Use GET /fapi/v1/time to synchronize clocks if needed.

API Key Rate Limits (Trading Actions)

Endpoints that place, cancel, or modify orders are subject to per-API-key rate limits:

Rate-limited endpoints include: POST /fapi/v1/order, DELETE /fapi/v1/order, PUT /fapi/v1/order, DELETE /fapi/v1/allOpenOrders, POST /fapi/v1/leverage, POST /fapi/v1/marginType.

IP-Level Rate Limits

The API gateway enforces IP-based rate limits in addition to per-API-key limits:

Session / Handshake

HTTP 429 Response

When a rate limit is exceeded, the server returns HTTP 429. The response includes a Retry-After header indicating the number of seconds to wait before retrying.

{
  "detail": "Rate limit exceeded. Try again in 5s.",
  "retry_after": 5
}

Ban Escalation

Clients that repeatedly violate rate limits or fail to back off after receiving 429 responses may be temporarily IP-banned. Ban durations escalate for repeat offenders.

Handling 502 / 503 on Order Endpoints

For non-order endpoints (market data, account queries), a 502 or 503 is always safe to retry immediately with backoff.

On /fapi/v1/* and /fapi/v2/* endpoints, errors return a GaiaEx-compatible JSON object with code and msg (or detail):

{
  "code": -1121,
  "msg": "Invalid symbol."
}

For schema validation errors (422):

{
  "detail": [
    {
      "loc": ["query", "symbol"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Each API key has a set of permissions that control which endpoints it can access:

By default, newly created API keys have read permission only. Add trade permission to enable order placement.

API keys can optionally be restricted to specific IP addresses. When an IP whitelist is configured, requests from non-whitelisted IPs will be rejected with HTTP 403.

The API supports Cross-Origin Resource Sharing (CORS) with the following allowed headers:

• X-MBX-APIKEY
• Authorization
• Content-Type
• X-Requested-With