Perpetual Futures Trading

Place and manage perpetual futures orders on GaiaEx via API: market, limit, stop-loss, and take-profit order types.

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 order execution endpoints under 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_or_form_string)) as query or form parameters.
Automatic Wallet Resolution: Your wallet account is automatically resolved from X-MBX-APIKEY on the server side — no wallet address parameter is needed.
Content-Type: Parameters may be sent as URL query strings, application/x-www-form-urlencoded, or application/json.

POST10/s key · 5/s IPhttps://openapi.gaiaex.com/fapi/v1/orderHMAC

New Order (TRADE)

Send in a new perpetual futures order.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	YES	Trading symbol (e.g., `BTCUSDC`, `ETHUSDC`, `BTCUSDT`, `ETHUSDT`)
`side`	ENUM	YES	`BUY` or `SELL`
`positionSide`	ENUM	NO	Default `BOTH` for One-way Mode; `LONG` or `SHORT` for Hedge Mode
`type`	ENUM	YES	`LIMIT`, `MARKET`, `STOP_MARKET`, `TAKE_PROFIT_MARKET`, `STOP`, `TAKE_PROFIT`
`timeInForce`	ENUM	NO	`GTC` (Good Till Cancel), `IOC` (Immediate or Cancel), `GTX` (Post-Only)
`quantity`	DECIMAL	YES	Order quantity in base asset contracts
`reduceOnly`	STRING	NO	`"true"` or `"false"` (default `"false"`). Cannot be sent in Hedge Mode or with `closePosition=true`.
`price`	DECIMAL	NO	Order price (required for `LIMIT`, `STOP`, and `TAKE_PROFIT` orders)
`newClientOrderId`	STRING	NO	A unique ID among open orders for idempotency. Automatically generated if not sent.
`stopPrice`	DECIMAL	NO	Used with `STOP`, `STOP_MARKET`, `TAKE_PROFIT`, or `TAKE_PROFIT_MARKET` orders
`closePosition`	STRING	NO	`"true"` or `"false"` — Close-All with `STOP_MARKET` or `TAKE_PROFIT_MARKET`
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Additional Mandatory Parameters by Order Type:

Order Type	Additional Mandatory Parameters
`LIMIT`	`timeInForce`, `quantity`, `price`
`MARKET`	`quantity`
`STOP` / `TAKE_PROFIT`	`quantity`, `price`, `stopPrice`
`STOP_MARKET` / `TAKE_PROFIT_MARKET`	`stopPrice`, plus `quantity` (or `closePosition="true"`)

Example Request (Query / Form):

POST https://openapi.gaiaex.com/fapi/v1/order?symbol=ETHUSDC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=0.1&price=3500.00&timestamp=1743508800000&signature=c3e85abeacfbb9ef64cfb7163b31d622e1a9744c128be6249e8347479c899158
X-MBX-APIKEY: your_api_key_here

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	Yes	Trading symbol (e.g. ETHUSDC, BTCUSDT, GOLDUSDC)
side	string	Yes	BUY or SELL
type	string	Yes	LIMIT, MARKET, STOP_MARKET, TAKE_PROFIT_MARKET
quantity	string	Yes	Order quantity
price	string	No	Limit price (required for LIMIT orders)
stopPrice	string	No	Trigger price (for STOP_MARKET / TAKE_PROFIT_MARKET)
timeInForce	string	No	GTC, IOC, or GTX (Post-Only)
reduceOnly	boolean	No	true or false (default false)
newClientOrderId	string	No	Unique client order ID
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringRequired

Trading symbol (e.g. ETHUSDC, BTCUSDT, GOLDUSDC)

side

stringRequired

BUY or SELL

type

stringRequired

LIMIT, MARKET, STOP_MARKET, TAKE_PROFIT_MARKET

quantity

stringRequired

Order quantity

price

stringOptional

Limit price (required for LIMIT orders)

stopPrice

stringOptional

Trigger price (for STOP_MARKET / TAKE_PROFIT_MARKET)

timeInForce

stringOptional

GTC, IOC, or GTX (Post-Only)

reduceOnly

booleanOptional

true or false (default false)

newClientOrderId

stringOptional

Unique client order ID

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

DELETE10/s key · 5/s IPhttps://openapi.gaiaex.com/fapi/v1/orderHMAC

Cancel Order (TRADE)

Cancel an active order. Either orderId or origClientOrderId must be sent.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	YES	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`orderId`	LONG	NO	System order ID to cancel
`origClientOrderId`	STRING	NO	Client order ID to cancel
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Example Request:

DELETE https://openapi.gaiaex.com/fapi/v1/order?symbol=ETHUSDC&orderId=987654321&timestamp=1743508800000&signature=8bb72b649cea0ef7e170cf82d7e7e902279cf8b4fbf73b7248c1eb00a62ddc42
X-MBX-APIKEY: your_api_key_here

Response:

{
  "orderId": 987654321,
  "symbol": "ETHUSDC",
  "status": "CANCELED",
  "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": 1743508805000
}

Parameters

Name	Type	Required	Description
symbol	string	Yes	Trading symbol (e.g. ETHUSDC)
orderId	int	No	Order ID to cancel
origClientOrderId	string	No	Client order ID to cancel
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringRequired

Trading symbol (e.g. ETHUSDC)

orderId

intOptional

Order ID to cancel

origClientOrderId

stringOptional

Client order ID to cancel

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

PUT10/s key · 5/s IPhttps://openapi.gaiaex.com/fapi/v1/orderHMAC

Modify Order (TRADE)

Order modify function — modifies an existing open limit order's price and quantity in place.

Parameters:

Name	Type	Mandatory	Description
`orderId`	LONG	NO	System order ID (either `orderId` or `origClientOrderId` must be sent)
`origClientOrderId`	STRING	NO	Client order ID
`symbol`	STRING	YES	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`side`	ENUM	YES	`BUY` or `SELL`
`quantity`	DECIMAL	YES	New order quantity
`price`	DECIMAL	YES	New limit price
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Example Request:

PUT https://openapi.gaiaex.com/fapi/v1/order?symbol=ETHUSDC&orderId=987654321&side=BUY&quantity=0.2&price=3480.00&timestamp=1743508800000&signature=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
X-MBX-APIKEY: your_api_key_here

Response:

{
  "orderId": 987654322,
  "symbol": "ETHUSDC",
  "status": "NEW",
  "clientOrderId": "987654322",
  "price": "3480.00",
  "avgPrice": "0.00000",
  "origQty": "0.2",
  "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": 1743508805000,
  "updateTime": 1743508805000
}

Parameters

Name	Type	Required	Description
symbol	string	Yes	Trading symbol (e.g. ETHUSDC)
orderId	int	Yes	Order ID to modify
side	string	Yes	BUY or SELL
quantity	string	Yes	New order quantity
price	string	Yes	New limit price
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringRequired

Trading symbol (e.g. ETHUSDC)

orderId

intRequired

Order ID to modify

side

stringRequired

BUY or SELL

quantity

stringRequired

New order quantity

price

stringRequired

New limit price

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

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

Query Order (USER_DATA)

Check an order's status. Either orderId or origClientOrderId must be sent.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	YES	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`orderId`	LONG	NO	System order ID
`origClientOrderId`	STRING	NO	Client order ID
`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	Yes	Trading symbol (e.g. ETHUSDC)
orderId	int	No	Order ID
origClientOrderId	string	No	Client order ID
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringRequired

Trading symbol (e.g. ETHUSDC)

orderId

intOptional

Order ID

origClientOrderId

stringOptional

Client order ID

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

DELETE10/s key · 5/s IPhttps://openapi.gaiaex.com/fapi/v1/allOpenOrdersHMAC

Cancel All Open Orders (TRADE)

Cancel all open orders for a specified 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:

{
  "code": 200,
  "msg": "The operation of cancel all open order is done."
}

Parameters

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

symbol

stringRequired

Trading symbol (e.g. ETHUSDC)

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

POST10/s key · 5/s IPhttps://openapi.gaiaex.com/fapi/v1/batchOrdersHMAC

Place Multiple Orders (TRADE)

Place up to 5 orders in a single batch request.

Parameters:

Name	Type	Mandatory	Description
`batchOrders`	LIST<JSON>	YES	JSON-encoded list of up to 5 order objects (each containing `symbol`, `side`, `type`, `quantity`, `price`, `timeInForce`, etc.)
`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": "batch_order_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
batchOrders	string	Yes	JSON array of up to 5 order objects
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

batchOrders

stringRequired

JSON array of up to 5 order objects

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

DELETE10/s key · 5/s IPhttps://openapi.gaiaex.com/fapi/v1/batchOrdersHMAC

Cancel Multiple Orders (TRADE)

Cancel up to 10 orders in a single batch request. Either orderIdList or origClientOrderIdList must be provided.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	YES	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`orderIdList`	LIST<LONG>	NO	JSON array of up to 10 order IDs (e.g., `[987654321,987654322]`)
`origClientOrderIdList`	LIST<STRING>	NO	JSON array of up to 10 client order IDs (e.g., `["order_1","order_2"]`)
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

[
  {
    "orderId": 987654321,
    "symbol": "ETHUSDC",
    "status": "CANCELED",
    "clientOrderId": "batch_order_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": 1743508805000
  }
]

Parameters

Name	Type	Required	Description
symbol	string	Yes	Trading symbol (e.g. ETHUSDC)
orderIdList	string	No	JSON array of up to 10 order IDs
origClientOrderIdList	string	No	JSON array of up to 10 client order IDs
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringRequired

Trading symbol (e.g. ETHUSDC)

orderIdList

stringOptional

JSON array of up to 10 order IDs

origClientOrderIdList

stringOptional

JSON array of up to 10 client order IDs

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature

POST10/s key · 5/s IPhttps://openapi.gaiaex.com/fapi/v1/countdownCancelAllHMAC

Auto-Cancel All Open Orders (TRADE)

Cancel all open orders of the specified symbol at the end of the specified countdown timer (Dead Man's Switch). Call repeatedly before the timer expires to reset the countdown, or pass countdownTime=0 to disarm the timer.

Parameters:

Name	Type	Mandatory	Description
`symbol`	STRING	YES	Trading symbol (e.g., `ETHUSDC`, `BTCUSDT`)
`countdownTime`	LONG	YES	Countdown duration in milliseconds (e.g. `60000` for 60s; `0` to cancel the timer)
`recvWindow`	LONG	NO	Timestamp validity window in ms (default `5000`)
`timestamp`	LONG	YES	Current Unix timestamp in milliseconds

Response:

{
  "symbol": "ETHUSDC",
  "countdownTime": "60000"
}

Parameters

Name	Type	Required	Description
symbol	string	Yes	Trading symbol (e.g. ETHUSDC)
countdownTime	int	Yes	Countdown time in ms (0 to cancel timer)
timestamp	int	Yes	Request timestamp in ms
signature	string	Yes	HMAC-SHA256 signature

symbol

stringRequired

Trading symbol (e.g. ETHUSDC)

countdownTime

intRequired

Countdown time in ms (0 to cancel timer)

timestamp

intRequired

Request timestamp in ms

signature

stringRequired

HMAC-SHA256 signature