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`	string	Total USDC balance (confirmed)
`hl_confirmed_bal`	string	Balance confirmed on-chain
`pending_deposit`	string	Pending deposit amount
`available`	string	Available balance for new orders
`unrealized_pnl`	string	Unrealized profit/loss across all positions
`margin_used`	string	Total margin committed to open positions

Code Examples

Python

import time, hmac, hashlib, requests

API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
BASE = "https://openapi.gaiaex.com/v1/trade"
ADDRESS = "0xYourAddress"

timestamp = str(int(time.time() * 1000))
path = f"/user/{ADDRESS}/balance"
message = timestamp + "GET" + path + ""
signature = hmac.new(
    API_SECRET.encode(), message.encode(), hashlib.sha256
).hexdigest()

resp = requests.get(f"{BASE}{path}", headers={
    "X-GAIAEX-APIKEY": API_KEY,
    "X-GAIAEX-TIMESTAMP": timestamp,
    "X-GAIAEX-SIGNATURE": signature,
})
print(resp.json())

JavaScript

const crypto = require('crypto');
const ADDRESS = '0xYourAddress';
const path = `/user/${ADDRESS}/balance`;
const timestamp = Date.now().toString();
const signature = crypto
  .createHmac('sha256', API_SECRET)
  .update(timestamp + 'GET' + path + '')
  .digest('hex');

const resp = await fetch(`https://openapi.gaiaex.com/v1/trade${path}`, {
  headers: {
    'X-GAIAEX-APIKEY': API_KEY,
    'X-GAIAEX-TIMESTAMP': timestamp,
    'X-GAIAEX-SIGNATURE': signature,
  },
});
console.log(await resp.json());

curl

ADDRESS="0xYourAddress"
TIMESTAMP=$(date +%s000)
PATH_="/user/${ADDRESS}/balance"
SIGNATURE=$(echo -n "${TIMESTAMP}GET${PATH_}" | \
  openssl dgst -sha256 -hmac "your_api_secret" | awk '{print $2}')

curl -s "https://openapi.gaiaex.com/v1/trade${PATH_}" \
  -H "X-GAIAEX-APIKEY: your_api_key" \
  -H "X-GAIAEX-TIMESTAMP: ${TIMESTAMP}" \
  -H "X-GAIAEX-SIGNATURE: ${SIGNATURE}"

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

Code Examples

The gaiaex_get and gaiaexGet helpers include HMAC signing. See the Quick Start page or the Get Balance section above for their implementation.

Python

path = f"/user/{ADDRESS}/positions"
resp = gaiaex_get(path)
for pos in resp.json()["positions"]:
    print(f"{pos['coin']}: size={pos['szi']} pnl={pos['unrealizedPnl']}")

JavaScript

const resp = await gaiaexGet(`/user/${ADDRESS}/positions`);
const { positions } = await resp.json();
positions.forEach(p =>
  console.log(`${p.coin}: size=${p.szi} pnl=${p.unrealizedPnl}`)
);

curl

curl -s "https://openapi.gaiaex.com/v1/trade/user/0xYourAddress/positions" \
  -H "X-GAIAEX-APIKEY: your_api_key" \
  -H "X-GAIAEX-TIMESTAMP: ${TIMESTAMP}" \
  -H "X-GAIAEX-SIGNATURE: ${SIGNATURE}"

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",
      "px": "3510.50",
      "sz": "0.1",
      "side": "B",
      "time": 1743508800000,
      "startPosition": "0.0",
      "dir": "Open Long",
      "closedPnl": "0.00",
      "hash": "0xabc...",
      "oid": 987654321,
      "fee": "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",
      "avgPrice": "3499.50",
      "status": "FILLED",
      "time": 1743508800000,
      "updateTime": 1711929601000
    }
  ],
  "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",
      "usdc": "-0.035",
      "szi": "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",
      "exitPx": "3600.00",
      "szi": "0.1",
      "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