Introduction
In this trading mode, you can seamlessly trade five different products—spot, margin, futures, perpetual swaps, and options—by simply transferring assets into a cross-margin account. The cross-margin feature allows shared margin usage across derivatives with the same settlement currency, enabling profit/loss offsetting during risk calculations. However, this also means all positions under the same settlement currency are evaluated collectively for risk. Insufficient equity in the currency may trigger full liquidation, potentially resulting in total loss of that currency’s equity. Alternatively, users may opt for isolated margin mode to compartmentalize risks.
Asset Fields Explained
| Term | Definition | API Field (details[]) |
|---|---|---|
| Currency Equity | Total equity of a currency across cross-margin and isolated positions. Formula: Account Balance + Cross-Margin PnL + Isolated Margin Balance + Isolated PnL + Options Market Value. | eq |
| Available Margin | Funds available for opening cross-margin positions (leveraged trades, perpetual/futures contracts, options selling). Formula: Max(0, Cross-Margin Balance + PnL - Frozen Balance). | availEq |
| Available Balance | Funds available for isolated trades, options buying, or spot sell orders (not displayed in asset fields). | availBal |
| Frozen Balance | Assets locked for open orders/positions (cross-margin and isolated). | frozenBal |
| Unrealized PnL | Sum of profits/losses for all leveraged/contract positions settled in the currency (cross-margin + isolated). | upl |
| Currency Leverage | Overall leverage at currency level. Formula: Position Coin Count / (Cross-Margin Balance + PnL). | notionalLever |
| Maintenance Margin Rate | Risk metric per currency. Formula: (Cross-Margin Balance + PnL - Sell Orders - Options Buy Costs - Isolated Margin Needs - Fees) / (Maintenance Margin + Liquidation Fees). | mgnRatio |
| Account Equity | Total net value of all currencies converted to fiat. Uses OKX’s USD index or USDT-based pricing. | eqUsd |
Trading Rules Overview
Users may trade in cross-margin (shared equity) or isolated margin (compartmentalized risk) modes. Cross-margin enables offsetting profits/losses across products sharing the same settlement currency.
Cross-Margin Order Validation
- Derivatives/Options Selling/Leverage: Available margin must cover the order’s required amount.
- Spot Trading/Options Buying: Available balance must suffice.
Example Scenario:
A user holds BTC cross-margin positions:
- Leverage (5X): 100 BTC margin, 200 BTC open orders, +10 BTC PnL.
- Futures (1X): 10 BTC margin, 20 BTC open orders, +5 BTC PnL.
Order Validation:
- New Leverage Order (40 BTC needed): Available margin = 185 BTC → Success.
- New Futures Order (200 BTC needed): Available margin = 185 BTC → Failure.
Cross-Margin Leverage
Position Fields
| Term | Definition | API Field |
|---|---|---|
| Position Assets | Net positive assets (excluding margin). | pos |
| Available to Close | Assets available for closing, adjusted by account equity vs. initial/maintenance margin. | availPos |
| Liquidation Price | Estimated price triggering liquidation (not calculable with multi-currency positions). | liqPx |
| Initial Margin | Calculated based on leverage, trade direction, and collateral type (coin vs. quote currency). | imr |
Closing Mechanisms
Same-Currency Collateral:
- Full Close: Sells position assets to repay debt; excess returns to balance.
- Partial Close: Repays debt incrementally; residual assets returned.
Different-Currency Collateral:
- Sells all position assets first; any remaining debt is auto-repaid from account balance.
Example:
- BTC-USDT Long (BTC collateral): Selling 2 BTC at 10,000 USDT repays 10,000 USDT debt; excess BTC refunded.
- BTC-USDT Short (USDT collateral): Buying 1.5 BTC reduces debt; surplus BTC refunded.
Cross-Margin Futures/Perpetuals
Supports one-way (single-direction) and hedging (multi-direction) modes.
Position Fields
| Term | Definition | API Field |
|---|---|---|
| Unrealized PnL | For USDⓈ-M contracts: Face Value × Contracts × (Mark Price - Entry Price). | upl |
| Maintenance Margin | Adjusted by position tier and mark price. | mmr |
Cross-Margin Options
Position Fields
| Term | Definition | API Field |
|---|---|---|
| Market Value | Position Size × Mark Price × Contract Multiplier (for contract-based pricing). | optVal |
| Seller Margin | Initial/maintenance margins apply only to option sellers. | imr/mmr |
Risk Management
Two-tiered checks prevent abrupt liquidations:
Risk Control Cancellation:
- Cancels orders if
Available Equity < Maintenance Margin + Open Order Costs.
- Cancels orders if
Pre-Liquidation:
- At 300% maintenance rate: Warning issued.
- At ≤100%: All open orders canceled; forced liquidation in stages:
a) Offset hedged positions.
b) Delta-neutral reductions.
c) Non-hedged positions (highest risk impact first).
Liquidation Example:
A BTC-USD futures + options portfolio triggers liquidation. System offsets delta-neutral pairs first, then prioritizes futures over options to minimize risk.
FAQs
1. What happens if my cross-margin equity turns negative?
The platform’s insurance fund covers negative balances, generating a clawback report.
2. Can I use both cross-margin and isolated margin simultaneously?
Yes, but isolated positions remain risk-segregated.
3. How is maintenance margin calculated for multi-product portfolios?
It aggregates maintenance needs across all positions under the same settlement currency.
4. Why might my liquidation price be unavailable?
Multi-currency portfolios or non-USDT pairs with mixed derivatives disable this estimate.
5. Are option buyers subject to forced liquidation?
No, only sellers face liquidation risks.
👉 Learn more about advanced trading strategies
This document is for informational purposes only and does not constitute financial advice. Trading digital assets involves significant risk.
© 2024 OKX. All rights reserved.