Formulas & Calculations

Trading formulas, PnL calculations, liquidation price, funding rate math, and utility endpoints for GaiaEx derivatives.

Overview

GaiaEx provides stateless utility endpoints for pre-trade risk calculations. These endpoints perform pure math — they do not read your account state or positions.

UTILITY ENDPOINTS

Most exchanges expect clients to compute PnL, liquidation price, and position sizing locally. GaiaEx provides these as a convenience API for quick prototyping. The formulas are documented below for offline computation — production trading bots should implement them client-side to avoid unnecessary API calls.

All calculator endpoints are public (no authentication required) and have no side effects.

GET20/s IPhttps://openapi.gaiaex.com/v1/trade/calculator/symbol-info/{symbol}

Get Symbol Info

GET https://openapi.gaiaex.com/v1/trade/calculator/symbol-info/{symbol}

Returns trading parameters for a symbol (useful before running calculations).

Path Parameters:

Parameter	Type	Description
`symbol`	string	Trading symbol (e.g., `BTC`, `xyz:GOLD`)

Response:

{
  "symbol": "BTC",
  "maxLeverage": 100,
  "marginMode": "cross",
  "isolatedOnly": false,
  "mmr": "0.005",
  "quoteCurrency": "USDC",
  "timestamp": 1743508800000
}

Parameters

Name	Type	Required	Description
symbol	string	Yes	Symbol

symbol

stringRequired

Symbol

Calculate PnL

POST https://openapi.gaiaex.com/v1/trade/calculator/pnl

Calculate profit/loss and ROI for a hypothetical trade.

Formula

initial_margin = quantity / leverage

# Long position
pnl = quantity * (exit_price - entry_price) / entry_price

# Short position
pnl = quantity * (entry_price - exit_price) / entry_price

roi = (pnl / initial_margin) * 100

Request Body:

Field	Type	Required	Constraints	Description
`side`	string	Yes	`"long"` or `"short"`	Position direction
`leverage`	int	Yes	1–200	Leverage multiplier
`entry_price`	string	Yes	> 0	Entry price
`exit_price`	string	Yes	> 0	Exit price
`quantity`	string	Yes	> 0	Position size in USDC (notional)

Example Request:

{
  "side": "long",
  "leverage": 10,
  "entry_price": "85000",
  "exit_price": "90000",
  "quantity": "1000"
}

Response:

{
  "success": true,
  "calculator_type": "pnl",
  "inputs": {
    "side": "long",
    "leverage": 10,
    "entry_price": "85000",
    "exit_price": "90000",
    "quantity": "1000"
  },
  "results": {
    "initial_margin": "100.00",
    "pnl": "58.82",
    "roi": "58.82"
  },
  "timestamp": 1743508800000
}

Calculate Target Price

POST https://openapi.gaiaex.com/v1/trade/calculator/target-price

Calculate the exit price needed to achieve a target ROI.

Formula

# Long position
target_price = entry_price * (1 + roi / (leverage * 100))

# Short position
target_price = entry_price * (1 - roi / (leverage * 100))

Request Body:

Field	Type	Required	Constraints	Description
`side`	string	Yes	`"long"` or `"short"`	Position direction
`leverage`	int	Yes	1–200	Leverage multiplier
`entry_price`	string	Yes	> 0	Entry price
`roi`	string	Yes	—	Target ROI in percent (can be negative)

Example Request:

{
  "side": "long",
  "leverage": 10,
  "entry_price": "85000",
  "roi": "50"
}

Response:

{
  "success": true,
  "calculator_type": "target_price",
  "inputs": {
    "side": "long",
    "leverage": 10,
    "entry_price": "85000",
    "roi": "50"
  },
  "results": {
    "target_price": "89250.00"
  },
  "timestamp": 1743508800000
}

Calculate Liquidation Price

POST https://openapi.gaiaex.com/v1/trade/calculator/liquidation-price

Estimate the liquidation price for a position.

Formula

mmr = 0.005  # maintenance margin rate (from symbol info)

# Isolated margin
margin = quantity / leverage

# Cross margin
margin = balance

# Long position
liq_price = entry_price * (1 - (margin / quantity) + mmr)

# Short position
liq_price = entry_price * (1 + (margin / quantity) - mmr)

Request Body:

Field	Type	Required	Constraints	Description
`side`	string	Yes	`"long"` or `"short"`	Position direction
`leverage`	int	Yes	1–200	Leverage multiplier
`margin_mode`	string	No	`"cross"` or `"isolated"`	Margin mode (default: `"cross"`)
`entry_price`	string	Yes	> 0	Entry price
`quantity`	string	Yes	> 0	Position size in USDC
`balance`	string	Yes	> 0	Total account balance in USDC

Example Request:

{
  "side": "long",
  "leverage": 10,
  "margin_mode": "isolated",
  "entry_price": "85000",
  "quantity": "1000",
  "balance": "5000"
}

Response:

{
  "success": true,
  "calculator_type": "liquidation_price",
  "results": {
    "liquidation_price": "76925.00"
  },
  "timestamp": 1743508800000
}

Calculate Max Open Position

POST https://openapi.gaiaex.com/v1/trade/calculator/max-open

Calculate the maximum position size given a balance and leverage.

Formula

max_open_usdc = balance * leverage
max_open_coins = max_open_usdc / entry_price

Request Body:

Field	Type	Required	Constraints	Description
`side`	string	Yes	`"long"` or `"short"`	Position direction
`leverage`	int	Yes	1–200	Leverage multiplier
`entry_price`	string	Yes	> 0	Entry price
`balance`	string	Yes	> 0	Available balance in USDC

Example Request:

{
  "side": "long",
  "leverage": 10,
  "entry_price": "85000",
  "balance": "1000"
}

Response:

{
  "success": true,
  "calculator_type": "max_open",
  "results": {
    "max_open_usdc": "10000.00",
    "max_open_coins": "0.1176"
  },
  "timestamp": 1743508800000
}

Calculate Average Open Price

POST https://openapi.gaiaex.com/v1/trade/calculator/open-price

Calculate the average entry price across multiple position entries (DCA).

Formula

total_cost = sum(entry_price_i * quantity_i)
total_quantity = sum(quantity_i)
avg_price = total_cost / total_quantity

Request Body:

Field	Type	Required	Description
`side`	string	Yes	`"long"` or `"short"`
`positions`	array	Yes	List of position entries (min 1)

Each position entry:

Field	Type	Required	Description
`entry_price`	string	Yes	Entry price for this leg
`quantity`	string	Yes	Size for this leg

Example Request:

{
  "side": "long",
  "positions": [
    { "entry_price": "80000", "quantity": "0.05" },
    { "entry_price": "85000", "quantity": "0.03" },
    { "entry_price": "82000", "quantity": "0.02" }
  ]
}

Response:

{
  "success": true,
  "calculator_type": "open_price",
  "results": {
    "avg_price": "81900.00"
  },
  "timestamp": 1743508800000
}