Perpetual Futures Account

API reference for managing GaiaEx perpetual futures accounts: balances, margin, positions, and leverage settings.

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 ↗

Overview

GaiaEx provides GaiaEx Unified Futures account, position, order, trade, and income endpoints under https://openapi.gaiaex.com/fapi/v2/* and https://openapi.gaiaex.com/fapi/v1/*.

Authentication: Send your API key in the X-MBX-APIKEY header and attach timestamp + signature (HMAC-SHA256(api_secret, query_string)) as query parameters.
No Address Parameter: Your account is automatically resolved server-side from X-MBX-APIKEY.
Independent Margin Balances: Both USDC and USDT margin assets are returned in balance and account queries.

GET20/s IPhttps://openapi.gaiaex.com/fapi/v2/balanceHMAC

Futures Account Balance V2 (USER_DATA)

Query futures account balance across all margin assets (USDC and USDT).

Parameters:

Name	Type	Mandatory	Description
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

[
  {
    "accountAlias": "0xA6E3c04e",
    "asset": "USDC",
    "balance": "1000.00000000",
    "crossWalletBalance": "1000.00000000",
    "crossUnPnl": "12.50000000",
    "availableBalance": "850.00000000",
    "marginAvailable": true,
    "updateTime": 1743508800000
  },
  {
    "accountAlias": "0xA6E3c04e",
    "asset": "USDT",
    "balance": "500.00000000",
    "crossWalletBalance": "500.00000000",
    "crossUnPnl": "0.00000000",
    "availableBalance": "500.00000000",
    "marginAvailable": true,
    "updateTime": 1743508800000
  }
]

Field	Type	Description
`accountAlias`	string	Unique account alias prefix
`asset`	string	Margin asset code (`USDC` or `USDT`)
`balance`	string	Total wallet balance
`crossWalletBalance`	string	Crossed wallet balance
`crossUnPnl`	string	Unrealized profit/loss of crossed positions
`availableBalance`	string	Available balance for new orders
`marginAvailable`	boolean	Whether the asset can be used as margin
`updateTime`	long	Last update timestamp in ms

Parameters

Name	Type	Required	Description
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

GET20/s IPhttps://openapi.gaiaex.com/fapi/v2/accountHMAC

Account Information V2 (USER_DATA)

Get current account information including total margin summary, per-asset balances, and open positions.

Parameters:

Name	Type	Mandatory	Description
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

{
  "feeTier": 0,
  "canTrade": true,
  "updateTime": 1743508800000,
  "multiAssetsMargin": true,
  "totalInitialMargin": "150.00000000",
  "totalMaintMargin": "75.00000000",
  "totalWalletBalance": "1500.00000000",
  "totalUnrealizedProfit": "12.50000000",
  "totalMarginBalance": "1512.50000000",
  "totalPositionInitialMargin": "150.00000000",
  "totalOpenOrderInitialMargin": "0.00000000",
  "totalCrossWalletBalance": "1500.00000000",
  "totalCrossUnPnl": "12.50000000",
  "availableBalance": "1350.00000000",
  "assets": [
    {
      "asset": "USDC",
      "walletBalance": "1000.00000000",
      "unrealizedProfit": "12.50000000",
      "marginBalance": "1012.50000000",
      "maintMargin": "75.00000000",
      "initialMargin": "150.00000000",
      "positionInitialMargin": "150.00000000",
      "openOrderInitialMargin": "0.00000000",
      "crossWalletBalance": "1000.00000000",
      "crossUnPnl": "12.50000000",
      "availableBalance": "850.00000000",
      "marginAvailable": true,
      "updateTime": 1743508800000
    }
  ],
  "positions": [
    {
      "symbol": "ETHUSDC",
      "initialMargin": "0.00000000",
      "maintMargin": "0",
      "unrealizedProfit": "12.50",
      "positionInitialMargin": "0.00000000",
      "openOrderInitialMargin": "0",
      "leverage": "10",
      "isolated": false,
      "entryPrice": "3500.00",
      "maxNotional": "INF",
      "positionSide": "BOTH",
      "positionAmt": "0.1",
      "notional": "350.00",
      "isolatedWallet": "0",
      "updateTime": 1743508800000
    }
  ]
}

Parameters

Name	Type	Required	Description
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

GET20/s IPhttps://openapi.gaiaex.com/fapi/v2/positionRiskHMAC

Position Information V2 (USER_DATA)

Get current position information. Optionally filter by symbol.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	NO	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`). Omit to return all positions.
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

[
  {
    "symbol": "ETHUSDC",
    "positionAmt": "0.1",
    "entryPrice": "3500.00",
    "breakEvenPrice": "3500.00",
    "markPrice": "3625.00",
    "unRealizedProfit": "12.50",
    "liquidationPrice": "3150.00",
    "leverage": "10",
    "maxNotionalValue": "INF",
    "marginType": "cross",
    "isolatedMargin": "0.00000000",
    "isAutoAddMargin": "false",
    "positionSide": "BOTH",
    "notional": "362.50",
    "isolatedWallet": "0",
    "updateTime": 1743508800000
  }
]

Field	Type	Description
`symbol`	string	Trading symbol
`positionAmt`	string	Signed position size (positive = long, negative = short)
`entryPrice`	string	Average entry price
`breakEvenPrice`	string	Break-even price
`markPrice`	string	Current mark price
`unRealizedProfit`	string	Unrealized PnL
`liquidationPrice`	string	Estimated liquidation price
`leverage`	string	Current leverage multiplier
`marginType`	string	`cross` or `isolated`
`positionSide`	string	`BOTH`, `LONG`, or `SHORT`
`notional`	string	Position notional value

Parameters

Name	Type	Required	Description
symbol	string	No	Trading symbol (omit for all positions)
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringOptional

Trading symbol (omit for all positions)

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

GET20/s IPhttps://openapi.gaiaex.com/fapi/v1/openOrdersHMAC

Current All Open Orders (USER_DATA)

Get all open orders on a symbol, or across all symbols if symbol is omitted.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	NO	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`). Omit to query all open orders.
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

[
  {
    "orderId": 987654321,
    "symbol": "ETHUSDC",
    "status": "NEW",
    "clientOrderId": "my_order_id_1",
    "price": "3500.00",
    "avgPrice": "0.00000",
    "origQty": "0.1",
    "executedQty": "0",
    "cumQty": "0",
    "cumQuote": "0",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "reduceOnly": false,
    "closePosition": false,
    "side": "BUY",
    "positionSide": "BOTH",
    "stopPrice": "0",
    "workingType": "CONTRACT_PRICE",
    "priceProtect": false,
    "origType": "LIMIT",
    "time": 1743508800000,
    "updateTime": 1743508800000
  }
]

Parameters

Name	Type	Required	Description
symbol	string	No	Trading symbol (omit for all symbols)
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringOptional

Trading symbol (omit for all symbols)

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

GET20/s IPhttps://openapi.gaiaex.com/fapi/v1/allOrdersHMAC

All Orders (USER_DATA)

Get all account orders: active, canceled, or filled.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	YES	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`orderId`	LONG	NO	If set, returns orders with `orderId >=` that value
`startTime`	LONG	NO	Start timestamp in ms
`endTime`	LONG	NO	End timestamp in ms
`limit`	INT	NO	Default `500`; max `1000`
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

[
  {
    "orderId": 987654321,
    "symbol": "ETHUSDC",
    "status": "FILLED",
    "clientOrderId": "my_order_id_1",
    "price": "3500.00",
    "avgPrice": "3500.00",
    "origQty": "0.1",
    "executedQty": "0.1",
    "cumQty": "0.1",
    "cumQuote": "350.00",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "reduceOnly": false,
    "closePosition": false,
    "side": "BUY",
    "positionSide": "BOTH",
    "stopPrice": "0",
    "workingType": "CONTRACT_PRICE",
    "priceProtect": false,
    "origType": "LIMIT",
    "time": 1743508800000,
    "updateTime": 1743508860000
  }
]

Parameters

Name	Type	Required	Description
symbol	string	Yes	Trading symbol (e.g. ETHUSDC)
limit	int	No	Default 500; max 1000
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringRequired

Trading symbol (e.g. ETHUSDC)

limit

intOptional

Default 500; max 1000

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

GET20/s IPhttps://openapi.gaiaex.com/fapi/v1/userTradesHMAC

Account Trade List (USER_DATA)

Get trades for a specific account and symbol.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	YES	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`orderId`	LONG	NO	Filter trades by orderId
`startTime`	LONG	NO	Start timestamp in ms
`endTime`	LONG	NO	End timestamp in ms
`fromId`	LONG	NO	Trade ID to fetch from
`limit`	INT	NO	Default `500`; max `1000`
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

[
  {
    "symbol": "ETHUSDC",
    "id": 698759,
    "orderId": 987654321,
    "side": "BUY",
    "price": "3500.00",
    "qty": "0.1",
    "realizedPnl": "0",
    "marginAsset": "USDC",
    "quoteQty": "350.0000",
    "commission": "0.1225",
    "commissionAsset": "USDC",
    "time": 1743508860000,
    "positionSide": "BOTH",
    "buyer": true,
    "maker": false
  }
]

Parameters

Name	Type	Required	Description
symbol	string	Yes	Trading symbol (e.g. ETHUSDC)
limit	int	No	Default 500; max 1000
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringRequired

Trading symbol (e.g. ETHUSDC)

limit

intOptional

Default 500; max 1000

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

GET20/s IPhttps://openapi.gaiaex.com/fapi/v1/incomeHMAC

Get Income History (USER_DATA)

Query account income history including realized PnL, funding fees, and trading commissions.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	NO	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`incomeType`	STRING	NO	`REALIZED_PNL`, `FUNDING_FEE`, or `COMMISSION`. If omitted, all income types are returned.
`startTime`	LONG	NO	Timestamp in ms to get income from INCLUSIVE
`endTime`	LONG	NO	Timestamp in ms to get income until INCLUSIVE
`limit`	INT	NO	Default `100`; max `1000`
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

[
  {
    "symbol": "ETHUSDC",
    "incomeType": "FUNDING_FEE",
    "income": "-0.03500000",
    "asset": "USDC",
    "info": "FUNDING_FEE",
    "time": 1743508800000,
    "tranId": 9689322392,
    "tradeId": ""
  },
  {
    "symbol": "ETHUSDC",
    "incomeType": "REALIZED_PNL",
    "income": "12.50000000",
    "asset": "USDC",
    "info": "REALIZED_PNL",
    "time": 1743508860000,
    "tranId": 9689322393,
    "tradeId": "698759"
  },
  {
    "symbol": "ETHUSDC",
    "incomeType": "COMMISSION",
    "income": "-0.12250000",
    "asset": "USDC",
    "info": "COMMISSION",
    "time": 1743508860000,
    "tranId": 9689322394,
    "tradeId": "698759"
  }
]

Parameters

Name	Type	Required	Description
symbol	string	No	Trading symbol
incomeType	string	No	REALIZED_PNL, FUNDING_FEE, COMMISSION
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringOptional

Trading symbol

incomeType

stringOptional

REALIZED_PNL, FUNDING_FEE, COMMISSION

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

GET20/s IPhttps://openapi.gaiaex.com/fapi/v1/commissionRateHMAC

User Commission Rate (USER_DATA)

Get user's maker and taker commission rates for a symbol.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	YES	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

{
  "symbol": "ETHUSDC",
  "makerCommissionRate": "0.000150",
  "takerCommissionRate": "0.000450"
}

Parameters

Name	Type	Required	Description
symbol	string	Yes	Trading symbol (e.g. BTCUSDC)
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringRequired

Trading symbol (e.g. BTCUSDC)

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

GET20/s IPhttps://openapi.gaiaex.com/fapi/v1/adlQuantileHMAC

Position ADL Quantile Estimation (USER_DATA)

Query position auto-deleveraging (ADL) quantile estimation.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	NO	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

[
  {
    "symbol": "ETHUSDC",
    "adlQuantile": {
      "LONG": 1,
      "SHORT": 1,
      "BOTH": 1
    }
  }
]

Parameters

Name	Type	Required	Description
symbol	string	No	Trading symbol (optional)
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringOptional

Trading symbol (optional)

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

GET20/s IPhttps://openapi.gaiaex.com/fapi/v1/forceOrdersHMAC

User's Force Orders (USER_DATA)

Query user's force liquidation or auto-deleveraging orders.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	NO	Trading symbol
`startTime`	LONG	NO	Start timestamp in ms
`endTime`	LONG	NO	End timestamp in ms
`limit`	INT	NO	Default 50; max 100
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

[]

Parameters

Name	Type	Required	Description
symbol	string	No	Trading symbol (optional)
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringOptional

Trading symbol (optional)

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

GET20/s IPhttps://openapi.gaiaex.com/fapi/v1/apiTradingStatusHMAC

User API Trading Quantitative Rules Indicators (USER_DATA)

Query user API trading quantitative rules indicators (UFR, IFER, GCR) and account trading status.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	NO	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds
`signature`	STRING	YES	`HMAC-SHA256` signature

Response:

{
  "indicators": {},
  "updateTime": 1743508800000
}

Parameters

Name	Type	Required	Description
symbol	string	No	Trading symbol (optional)
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringOptional

Trading symbol (optional)

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature