Skip to main content

​
Overview

This guide walks through the full lifecycle of using Isolated Margin via the API. For a conceptual overview, see Isolated Margin basics.

​
Step 1: Query Current Margin Modes

Before switching, check the current margin mode for each symbol. API: GET /v1/client/margin_modes Response: 
{
  "success": true,
  "data": {
    "rows": [
      {
        "symbol": "PERP_BTC_USDC",
        "default_margin_mode": "CROSS"
      },
      {
        "symbol": "PERP_ETH_USDC",
        "default_margin_mode": "ISOLATED"
      }
    ]
  }
}
All symbols default to CROSS unless previously changed.

​
Step 2: Switch a Symbol to Isolated Margin

Set the default margin mode for a specific symbol to ISOLATED. API: POST /v1/client/margin_mode Request body: 
{
  "symbol": "PERP_ETH_USDC",
  "default_margin_mode": "ISOLATED"
}
You can only switch a symbol’s margin mode when you have no open positions or pending orders on that symbol in the current mode. Close all positions and cancel all orders on the symbol before switching.

​
Step 3: Set Leverage for Isolated Mode

Each symbol maintains independent leverage settings per margin mode. Set the leverage for the Isolated mode specifically. API: POST /v1/client/leverages Request body (single symbol): 
{
  "symbol": "PERP_ETH_USDC",
  "leverage": 10,
  "margin_mode": "ISOLATED"
}
You can also query the current leverage: API: GET /v1/client/leverage with query params symbol=PERP_ETH_USDC&margin_mode=ISOLATED
The leverage you set in Isolated mode determines how much margin is allocated from your available balance when opening a position. Higher leverage = less margin allocated = tighter liquidation price.

​
Batch Leverage Updates

When using POST /v1/client/leverages without a symbol parameter, the behavior differs by mode:
ModeBehavior
CrossAll cross-margin symbols update atomically — all succeed or none do
IsolatedOnly applies to symbols with no active isolated positions or pending orders; eligible symbols always update

​
Step 4: Place an Order

Place an order specifying the margin_mode parameter. API: POST /v1/order Request body: 
{
  "symbol": "PERP_ETH_USDC",
  "order_type": "LIMIT",
  "side": "BUY",
  "order_price": 2500,
  "order_quantity": 1,
  "margin_mode": "ISOLATED"
}
If margin_mode is omitted, the symbol’s current default margin mode is used. After switching a symbol to ISOLATED in Step 2, new orders on that symbol will default to Isolated.

​
Dual Positions

You can hold both a Cross position and an Isolated position on the same symbol simultaneously. For example, a Cross long and an Isolated short on PERP_ETH_USDC. Each position has its own margin calculation and liquidation price — they are completely independent.

​
Step 5: Adjust Position Margin

After opening an Isolated position, you can add or reduce the margin allocated to it. API: POST /v1/position_margin Add margin (lowers liquidation price, reduces risk): 
{
  "symbol": "PERP_ETH_USDC",
  "amount": "100",
  "type": "ADD"
}
Reduce margin (raises liquidation price, frees up balance): 
{
  "symbol": "PERP_ETH_USDC",
  "amount": "50",
  "type": "REDUCE"
}
TypeEffect
ADDTransfers margin from available balance to the isolated position
REDUCETransfers margin from the isolated position back to available balance

​
Step 6: Monitor Position

Query the position with the margin_mode parameter to get isolated-specific data. API: GET /v1/position/{symbol} with query param margin_mode=ISOLATED Key fields in the response:
FieldDescription
marginAmount of margin allocated to this isolated position
margin_modeISOLATED
leverageCurrent leverage for this position
est_liq_priceEstimated liquidation price
position_qtyPosition size
unsettled_pnlCurrent unsettled PnL
imrInitial margin ratio
mmrMaintenance margin ratio

​
WebSocket Updates

Subscribe to the private position topic to receive real-time updates for position changes including margin, PnL, and liquidation price. See WebSocket API for details.

​
Account Balance

The GET /v1/client/aggregate/holding endpoint includes two isolated-margin-specific fields:
FieldDescription
isolated_marginTotal margin currently allocated to all isolated positions
isolated_order_frozenMargin frozen in pending isolated orders

​
Liquidation Behavior

When an Isolated position is liquidated:
  • Only the margin assigned to that position is lost
  • Other positions (Cross or Isolated) and your account balance are unaffected
  • The position is handled independently by the liquidation engine
For full details, see Liquidations.