Leverage & Margin Mode
Set leverage (1x–100x) and margin mode (cross or isolated) for perpetual futures positions on GaiaEx via API.
Set Leverage
POST https://openapi.gaiaex.com/v1/trade/leverage
Set the leverage and margin mode for a symbol. Must be called before placing orders if you want a specific leverage level.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
user_address | string | Yes | Your wallet address |
symbol | string | Yes | Trading symbol |
leverage | int | Yes | Desired leverage (1 to maxLeverage; up to 200 for USDT-margined perps) |
is_cross | boolean | No | true for cross margin (default), false for isolated |
Example Request:
{
"user_address": "0xYourAddress",
"symbol": "ETH",
"leverage": 10,
"is_cross": true
}Response:
{
"success": true,
"symbol": "ETH",
"leverage": 10,
"marginType": "CROSSED",
"timestamp": 1743508800000
}INFO
Some symbols only support isolated margin. If you send is_cross: true for an isolated-only symbol, the backend will automatically correct it to isolated margin. You do not need to maintain a list of which symbols support which margin mode — the backend handles this transparently.
Maximum Leverage
Maximum leverage varies by symbol and asset class:
Leverage limits are set per symbol and may change. Fetch GET /symbols/list for the authoritative, current values. Representative values:
| Asset Class | Typical Max Leverage | Examples |
|---|---|---|
| Crypto major | 25x–40x | BTC 40x, ETH 25x |
| Crypto mid-cap | 10x–20x | SOL 20x, DOGE 10x, ARB 10x |
| Crypto small-cap | 3x–5x | varies per symbol |
Forex (xyz:) | 50x | xyz:EUR, xyz:JPY |
Commodities (xyz:) | 10x–20x | xyz:GOLD 20x, xyz:NATGAS 10x |
Equities (xyz:) | 10x | xyz:AAPL, xyz:TSLA, xyz:NVDA |
Index (cash:) | 20x–25x | cash:USA500 20x, xyz:XYZ100 25x |
Pre-IPO ventures (vntl: / xyz:) | 3x–5x | vntl:OPENAI, vntl:ANTHROPIC, xyz:SPCX |
| USDT-margined perps | up to 200x | BTC 200x, ETH 200x, BNB 200x |
STRICT ISOLATED MODE
Some deployer symbols (e.g. xyz:COPPER, xyz:NATGAS) enforce strict isolated margin mode. For these symbols the is_cross flag is ignored — the backend always applies isolated margin and the leverage range may be more restricted than the table above. Check maxLeverage via GET /symbols/list.
ALWAYS CHECK /symbols/list
Leverage limits are dynamic. Always call GET /symbols/list to get the current maxLeverage for each symbol before setting leverage.