Overview
This guide walks through the full lifecycle of using Isolated Margin via the API. Both Cross and Isolated margin modes are supported simultaneously — you can hold a Cross position and an Isolated position on the same symbol at the same time. Simply specify margin_mode when placing an order. For a conceptual overview, see Isolated Margin basics.
Step 1: 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"
}
/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:
| Mode | Behavior |
|---|
| Cross | All cross-margin symbols update atomically — all succeed or none do |
| Isolated | Only applies to symbols with no active isolated positions or pending orders; eligible symbols always update |
Step 2: 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"
}
margin_mode is omitted, the symbol’s default margin mode is used. You can change the default via POST /v1/client/margin_mode.
Step 3: 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"
}
{
"symbol": "PERP_ETH_USDC",
"amount": "50",
"type": "REDUCE"
}
| Type | Effect |
|---|
ADD | Transfers margin from available balance to the isolated position |
REDUCE | Transfers margin from the isolated position back to available balance |
Step 4: 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:
| Field | Description |
|---|
margin | Amount of margin allocated to this isolated position |
margin_mode | ISOLATED |
leverage | Current leverage for this position |
est_liq_price | Estimated liquidation price |
position_qty | Position size |
unsettled_pnl | Current unsettled PnL |
imr | Initial margin ratio |
mmr | Maintenance 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:
| Field | Description |
|---|
isolated_margin | Total margin currently allocated to all isolated positions |
isolated_order_frozen | Margin 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.
Related Pages
