GaiaExGaiaEx
API

User Data WebSocket Stream

Private WebSocket stream for real-time positions, open orders, and account balances on GaiaEx. Requires API key authentication.

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 ↗
POST20/s IPhttps://openapi.gaiaex.com/fapi/v1/listenKeyHMAC

Overview

GaiaEx supports the GaiaEx Unified Futures User Data Stream lifecycle via /fapi/v1/listenKey alongside real-time WebSocket streaming for account balances, positions, and orders.

  • REST ListenKey Base URL: https://openapi.gaiaex.com
  • WebSocket Stream URL: wss://openapi.gaiaex.com/ws/{listenKey}
  • Authentication: Pass your API key in the X-MBX-APIKEY header when calling /fapi/v1/listenKey. No query signature is required for listenKey endpoints.
POST20/s IPhttps://openapi.gaiaex.com/fapi/v1/listenKeyHMAC

Start User Data Stream (USER_STREAM)

Start a new user data stream and obtain a listenKey for WebSocket subscription. Requires the X-MBX-APIKEY header.

Headers:

HeaderRequiredDescription
X-MBX-APIKEYYESYour GaiaEx API key

Parameters: None

Example Request:

curl -X POST "https://openapi.gaiaex.com/fapi/v1/listenKey" \
  -H "X-MBX-APIKEY: your_api_key_here"

Response:

{
  "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}
PUT20/s IPhttps://openapi.gaiaex.com/fapi/v1/listenKeyHMAC

Keepalive User Data Stream (USER_STREAM)

Keepalive a user data stream to prevent a time out. Recommended to send a ping about every 30 minutes.

Headers:

HeaderRequiredDescription
X-MBX-APIKEYYESYour GaiaEx API key

Parameters: None

Example Request:

curl -X PUT "https://openapi.gaiaex.com/fapi/v1/listenKey" \
  -H "X-MBX-APIKEY: your_api_key_here"

Response:

{
  "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}
DELETE20/s IPhttps://openapi.gaiaex.com/fapi/v1/listenKeyHMAC

Close User Data Stream (USER_STREAM)

Close out a user data stream and invalidate the listenKey.

Headers:

HeaderRequiredDescription
X-MBX-APIKEYYESYour GaiaEx API key

Parameters: None

Example Request:

curl -X DELETE "https://openapi.gaiaex.com/fapi/v1/listenKey" \
  -H "X-MBX-APIKEY: your_api_key_here"

Response:

{}
POST20/s IPhttps://openapi.gaiaex.com/fapi/v1/listenKeyHMAC

WebSocket User Stream Subscription

Once you obtain a listenKey from POST /fapi/v1/listenKey, open a WebSocket connection to wss://openapi.gaiaex.com/ws/{listenKey} to receive real-time account, position, and order execution events.

Python Example

import asyncio
import json
import os
import requests
import websockets

API_KEY = os.environ["GAIAEX_API_KEY"]
REST_BASE = "https://openapi.gaiaex.com"
WS_BASE = "wss://openapi.gaiaex.com"

def get_listen_key() -> str:
    resp = requests.post(
        f"{REST_BASE}/fapi/v1/listenKey",
        headers={"X-MBX-APIKEY": API_KEY},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()["listenKey"]

async def stream_user_data():
    listen_key = get_listen_key()
    uri = f"{WS_BASE}/ws/{listen_key}"
    async with websockets.connect(uri) as ws:
        async for raw_msg in ws:
            event = json.loads(raw_msg)
            event_type = event.get("e") or event.get("type")
            print(f"Event [{event_type}]:", event)

asyncio.run(stream_user_data())

Account & Position Update Event (ACCOUNT_UPDATE)

Pushed whenever account balances or positions change.

{
  "e": "ACCOUNT_UPDATE",
  "E": 1743508800000,
  "T": 1743508800000,
  "a": {
    "m": "ORDER",
    "B": [
      {
        "a": "USDC",
        "wb": "1000.00000000",
        "cw": "1000.00000000",
        "bc": "0"
      }
    ],
    "P": [
      {
        "s": "ETHUSDC",
        "pa": "0.1",
        "ep": "3500.00",
        "cr": "0.00",
        "up": "12.50",
        "mt": "cross",
        "iw": "0",
        "ps": "BOTH"
      }
    ]
  }
}

Order Trade Update Event (ORDER_TRADE_UPDATE)

Pushed whenever an order is created, modified, canceled, or filled.

{
  "e": "ORDER_TRADE_UPDATE",
  "E": 1743508800000,
  "T": 1743508800000,
  "o": {
    "s": "ETHUSDC",
    "c": "my_order_id_1",
    "S": "BUY",
    "o": "LIMIT",
    "f": "GTC",
    "q": "0.1",
    "p": "3500.00",
    "ap": "0.00000",
    "sp": "0",
    "x": "NEW",
    "X": "NEW",
    "i": 987654321,
    "l": "0",
    "z": "0",
    "L": "0",
    "T": 1743508800000,
    "t": 0,
    "R": false,
    "ps": "BOTH"
  }
}

Ping / Keepalive

Standard WebSocket ping/pong frames are supported automatically, or you can send text "ping" and receive "pong". Remember to send PUT /fapi/v1/listenKey every 30 minutes to keep the listenKey active.