Perpetual Futures Account

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

Overview

All account endpoints require authentication. The {address} path parameter must match the authenticated user's address.

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/user/{address}/balanceHMAC

Get Balance

GET https://openapi.gaiaex.com/v1/trade/user/{address}/balance

Returns the user's perpetual account balance and margin summary.

Path Parameters:

Parameter	Type	Description
`address`	string	User's wallet address

Response:

{
  "address": "0xYourAddress",
  "usdc_balance": "1000.00",
  "hl_confirmed_bal": "1000.00",
  "pending_deposit": "0.00",
  "available": "850.00",
  "unrealized_pnl": "12.50",
  "margin_used": "150.00",
  "timestamp": 1743508800000
}

Field	Type	Description
`usdc_balance`	float	Total USDC balance (confirmed)
`hl_confirmed_bal`	float	Balance confirmed on-chain
`pending_deposit`	float	Pending deposit amount
`available`	float	Available balance for new orders
`unrealized_pnl`	float	Unrealized profit/loss across all positions
`margin_used`	float	Total margin committed to open positions

Parameters

Name	Type	Required	Description
address	string	Yes	Wallet address

address

stringRequired

Wallet address

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/user/{address}/positionsHMAC

Get Positions

GET https://openapi.gaiaex.com/v1/trade/user/{address}/positions

Returns all open perpetual positions.

Response:

{
  "address": "0xYourAddress",
  "positions": [
    {
      "coin": "ETH",
      "szi": "0.1",
      "entryPx": "3500.00",
      "positionValue": "350.00",
      "unrealizedPnl": "12.50",
      "leverage": {
        "type": "cross",
        "value": 10
      },
      "liquidationPx": "3150.00",
      "marginUsed": "35.00"
    }
  ],
  "count": 1,
  "timestamp": 1743508800000
}

Field	Type	Description
`coin`	string	Symbol name
`szi`	string	Signed size (positive = long, negative = short)
`entryPx`	string	Average entry price
`positionValue`	string	Current notional value
`unrealizedPnl`	string	Unrealized PnL
`leverage`	object	`{ type: "cross"/"isolated", value: int }`
`liquidationPx`	string	Estimated liquidation price
`marginUsed`	string	Margin allocated to this position

Parameters

Name	Type	Required	Description
address	string	Yes	Wallet address

address

stringRequired

Wallet address

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/user/{address}/openOrdersHMAC

Get Open Orders

GET https://openapi.gaiaex.com/v1/trade/user/{address}/openOrders

Returns all open perpetual orders.

Response:

{
  "address": "0xYourAddress",
  "orders": [
    {
      "orderId": 987654321,
      "symbol": "ETH",
      "side": "BUY",
      "type": "LIMIT",
      "origQty": "0.1",
      "price": "3500.00",
      "status": "NEW",
      "time": 1743508800000
    }
  ],
  "count": 1,
  "timestamp": 1743508800000
}

Parameters

Name	Type	Required	Description
address	string	Yes	Wallet address

address

stringRequired

Wallet address

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/user/{address}/fillsHMAC

Get Fills

GET https://openapi.gaiaex.com/v1/trade/user/{address}/fills

Returns recent trade fills (executions).

Query Parameters:

Parameter	Type	Default	Max	Description
`limit`	int	100	500	Number of fills to return

Response:

{
  "address": "0xYourAddress",
  "fills": [
    {
      "coin": "ETH",
      "price": "3510.50",
      "qty": "0.1",
      "side": "B",
      "time": 1743508800000,
      "startPosition": "0.0",
      "dir": "Open Long",
      "realizedPnl": "0.00",
      "hash": "0xabc...",
      "orderId": 987654321,
      "commission": "0.12285"
    }
  ],
  "count": 1,
  "timestamp": 1743508800000
}

Parameters

Name	Type	Required	Description
address	string	Yes	Wallet address
limit	int	No	Max results (default 50)

address

stringRequired

Wallet address

limit

intOptional

Max results (default 50)

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/user/{address}/historicalOrdersHMAC

Get Historical Orders

GET https://openapi.gaiaex.com/v1/trade/user/{address}/historicalOrders

Returns historical orders (filled, cancelled, etc.).

Query Parameters:

Parameter	Type	Default	Max	Description
`limit`	int	200	2000	Number of orders to return

Response:

{
  "address": "0xYourAddress",
  "orders": [
    {
      "orderId": 987654321,
      "symbol": "ETH",
      "side": "BUY",
      "type": "LIMIT",
      "origQty": "0.1",
      "executedQty": "0.1",
      "price": "3500.00",
      "status": "FILLED",
      "time": 1743508800000
    }
  ],
  "count": 1,
  "timestamp": 1743508800000
}

Parameters

Name	Type	Required	Description
address	string	Yes	Wallet address

address

stringRequired

Wallet address

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/user/{address}/fundingHistoryHMAC

Get Funding History

GET https://openapi.gaiaex.com/v1/trade/user/{address}/fundingHistory

Returns funding rate payments received or paid.

Query Parameters:

Parameter	Type	Description
`start_time`	int	Start timestamp in ms
`end_time`	int	End timestamp in ms
`limit`	int	Max results (default 200, max 2000)

Response:

{
  "address": "0xYourAddress",
  "funding": [
    {
      "coin": "ETH",
      "income": "-0.035",
      "positionSize": "0.1",
      "fundingRate": "0.0001",
      "time": 1743508800000
    }
  ],
  "count": 1,
  "timestamp": 1743508800000
}

Parameters

Name	Type	Required	Description
address	string	Yes	Wallet address

address

stringRequired

Wallet address

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/user/{address}/positionHistoryHMAC

Get Position History

GET https://openapi.gaiaex.com/v1/trade/user/{address}/positionHistory

Returns closed position history.

Query Parameters:

Parameter	Type	Description
`start_time`	int	Start timestamp in ms
`limit`	int	Max results (default 200, max 1000)

Response:

{
  "address": "0xYourAddress",
  "positions": [
    {
      "coin": "ETH",
      "side": "Long",
      "entryPx": "3500.00",
      "avgClosePrice": "3600.00",
      "closedPnl": "10.00",
      "openTime": 1743508800000,
      "closeTime": 1711932600000
    }
  ],
  "count": 1,
  "total": 15,
  "timestamp": 1743508800000
}

Parameters

Name	Type	Required	Description
address	string	Yes	Wallet address

address

stringRequired

Wallet address