General Info & Authentication

• The base endpoint is: https://openapi.gaiaex.com/v1/trade
• 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 endpoints, parameters are sent as query strings. For POST, PATCH, and DELETE endpoints, parameters are sent as a JSON request body with Content-Type: application/json.

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

• Most trading and account endpoints accept both SIGNED (API key) and SESSION (Bearer token) authentication.
• Market data endpoints are public (NONE).

GaiaEx supports two authentication methods:

Method 1: 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 concatenate four pieces of text into one message, run HMAC-SHA256 over it with your secret as the key, and attach the resulting hex digest as a header. The server does the exact same computation and compares digests. If they match, the request is yours; if any byte differs (wrong timestamp, wrong path, tampered body), the digests don't match and the server rejects. You never send the secret over the network.

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) and can be managed programmatically via the /api-keys endpoints. Each request must include three custom headers:

Signature construction:

message = timestamp + method + path + body
signature = HMAC-SHA256(api_secret, message)

• timestamp — the value of X-GAIAEX-TIMESTAMP (string)
• method — HTTP method in uppercase (GET, POST, DELETE, PATCH)
• path — request path without the /v1/trade prefix and without query string (e.g., /user/0xABC.../balance, not /v1/trade/user/0xABC.../balance)
• body — JSON request body as string (empty string "" for GET/DELETE)

Example (Python):

import hmac
import hashlib
import time
import requests
import json

api_key = "your_api_key_here"
api_secret = "your_api_secret_here"

timestamp = str(int(time.time() * 1000))
method = "GET"
path = "/user/0xYourAddress/balance"
body = ""

message = timestamp + method + path + body
signature = hmac.new(
    api_secret.encode(), message.encode(), hashlib.sha256
).hexdigest()

headers = {
    "X-GAIAEX-APIKEY": api_key,
    "X-GAIAEX-TIMESTAMP": timestamp,
    "X-GAIAEX-SIGNATURE": signature,
    "Content-Type": "application/json",
}

resp = requests.get(f"https://openapi.gaiaex.com/v1/trade{path}", headers=headers)
print(resp.json())

Example (curl):

TIMESTAMP=$(date +%s000)
METHOD="GET"
PATH="/user/0xYourAddress/balance"
BODY=""
MESSAGE="${TIMESTAMP}${METHOD}${PATH}${BODY}"

SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')

curl -H "X-GAIAEX-APIKEY: $API_KEY" \
     -H "X-GAIAEX-TIMESTAMP: $TIMESTAMP" \
     -H "X-GAIAEX-SIGNATURE: $SIGNATURE" \
     -H "Content-Type: application/json" \
     "https://openapi.gaiaex.com/v1/trade${PATH}"

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, timestamp, method, path, and body into your own code, you must get the same signature shown here. If you don't, your implementation has a bug — most likely in how you serialize the body or strip the path prefix.

Example 1: GET Balance (no body)

Goal: query perpetual account balance for address 0xA6E3c04eF78427b5B53F43CDBA881d7E15B0bccD.

Example response (HTTP 200):

{
  "address": "0xA6E3c04eF78427b5B53F43CDBA881d7E15B0bccD",
  "account_value": "1523.47",
  "available_margin": "892.10",
  "margin_used": "631.37",
  "leverage_used": "2.4",
  "unrealized_pnl": "18.92",
  "timestamp": 1712345679123
}

import hmac, hashlib, time, json, requests

# Load from config.json (recommended)
with open("config.json") as f:
    cfg = json.load(f)

api_key    = cfg["api_key"]
api_secret = cfg["api_secret"]
address    = cfg["user_address"]

# Step 1: Generate timestamp
timestamp = str(int(time.time() * 1000))

# Step 2-4: Build message components
method = "GET"
path   = f"/user/{address}/balance"
body   = ""  # Empty for GET

# Step 5: Concatenate message
message = timestamp + method + path + body
print(f"Message: {message}")

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

# Step 8: Send request
headers = {
    "X-GAIAEX-APIKEY": api_key,
    "X-GAIAEX-TIMESTAMP": timestamp,
    "X-GAIAEX-SIGNATURE": signature,
    "Content-Type": "application/json",
}

resp = requests.get(
    f"https://openapi.gaiaex.com/v1/trade{path}",
    headers=headers,
)
print(f"Status: {resp.status_code}")
print(f"Response: {resp.json()}")

Example 2: POST Place Order (with body)

Goal: place a limit buy order for 0.1 ETH at $3,500.

Example response (HTTP 200):

{
  "status": "ok",
  "order_id": 41298374,
  "client_order_id": "bot-a1b2c3",
  "symbol": "ETH",
  "is_buy": true,
  "size": "0.1",
  "price": "3500.00",
  "order_type": "limit",
  "state": "resting",
  "filled": "0",
  "avg_fill_price": null,
  "timestamp": 1712345679456
}

Common rejection (HTTP 401, signature mismatch):

{"detail": "Invalid signature"}

If you see this, the server computed a different digest than yours. Check, in order: (1) the body you signed equals the body you sent; (2) path has no /v1/trade prefix; (3) timestamp is in milliseconds (not seconds) and within 5s of the server clock.

import hmac, hashlib, time, json, requests

with open("config.json") as f:
    cfg = json.load(f)

api_key    = cfg["api_key"]
api_secret = cfg["api_secret"]
address    = cfg["user_address"]

timestamp = str(int(time.time() * 1000))
method    = "POST"
path      = "/order"

# Build JSON body — NOTE: order of keys matters for reproducibility
body_dict = {
    "user_address": address,
    "symbol": "ETH",
    "is_buy": True,
    "size": "0.1",
    "price": "3500.00",
    "order_type": "limit",
}
body = json.dumps(body_dict)

# Sign: timestamp + method + path + body
message = timestamp + method + path + body
signature = hmac.new(
    api_secret.encode(), message.encode(), hashlib.sha256
).hexdigest()

headers = {
    "X-GAIAEX-APIKEY": api_key,
    "X-GAIAEX-TIMESTAMP": timestamp,
    "X-GAIAEX-SIGNATURE": signature,
    "Content-Type": "application/json",
}

resp = requests.post(
    f"https://openapi.gaiaex.com/v1/trade{path}",
    headers=headers,
    data=body,
)
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 /order, /order/modify, and /order/cancel. Typical responses are under 2 seconds, but allow headroom for network spikes.

Never blind-retry a timeout

Idempotency via client_order_id

Pass a unique ASCII string (max 64 chars) as client_order_id on POST /order. The server treats duplicate client_order_id values from the same address 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 = gaiaex_post("/order", {
    "user_address":    ADDRESS,
    "symbol":          "BTC",
    "is_buy":          True,
    "size":            "0.001",
    "price":           "79000",
    "order_type":      "limit",
    "client_order_id": f"bot-{uuid.uuid4()}",   # safe to retry
})

Modify replaces the order

A successful POST /order/modify cancels the old order and creates a new one. The response returns a NEW orderId; the old id is no longer valid. Always use orderId from the modify response for subsequent cancel or modify calls. oldOrderId is echoed back for convenience.

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 X-GAIAEX-TIMESTAMP header.
• The server rejects requests where the timestamp is more than 5 seconds away from the server time.
• Use GET /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: /order, /order/cancel, /order/cancel-all, /order/modify, /order/tpsl, /position/close, /leverage, /spot/order, /spot/order/cancel, /spot/order/cancel-all.

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.

All error responses follow a consistent structure:

{
  "detail": "Human-readable error message"
}

For validation errors (422):

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "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:

• Authorization
• Content-Type
• X-Requested-With
• X-GAIAEX-APIKEY
• X-GAIAEX-TIMESTAMP
• X-GAIAEX-SIGNATURE