Unified Margin Overview
Unified Margin (a.k.a. Portfolio Margin) is an opt-in account mode in which all of a user's open positions share a single margin pool. Offsetting positions (e.g. BTC long + ETH short) reduce the total margin requirement, improving capital efficiency.
A user is in exactly one mode at any time. Switching is explicit and has hard preconditions (see Switch Margin Mode).
| Isolated (default) | Unified | |
|---|---|---|
| Collateral | Per-position | Single account-wide pool |
| Risk metric | Per-position margin ratio | Account-level uniMMR |
| Liquidation | Position-by-position | Cross-position waterfall |
| Best for | Simple directional trades | Hedged / multi-leg strategies |
Key Concepts
uniMMR (Unified Maintenance Margin Ratio)
The single number that describes the health of a unified account:
uniMMR = total_equity / total_maintenance_margin
total_equity = wallet_balance + Σ unrealized_pnl − Σ accumulated_feestotal_maintenance_margin = Σ MM_per_position
When an account has no open positions uniMMR is null and the
account is treated as safe.
Status machine
The backend risk worker evaluates every unified account every 2 s and transitions the account through the following ladder:
| Range | Status | Side-effects |
|---|---|---|
uniMMR > 2.00 or no positions | normal | — |
uniMMR ≤ 2.00 | warning_1 | Margin-call WS push |
uniMMR ≤ 1.50 | warning_2 | Second margin-call |
uniMMR ≤ 1.20 | reduce_only | All open orders auto-cancelled; new opening orders rejected |
uniMMR ≤ 1.05 | liquidating | Forced liquidation engine fires — one position per tick, starting from the worst-PnL |
Status can recover automatically when uniMMR rises back above a
threshold (except during an ongoing liquidation tick).
Tiered maintenance margin
Maintenance margin is computed per position using a symbol-specific
tier table. A tier is a notional range with its own maint_margin_rate
and a cumulative deduction that keeps the ladder continuous:
MM_position = notional × maint_margin_rate − cum_amount
The default ladder (applied when a symbol has no explicit tiers):
| Tier | Notional cap (USD) | MMR | Max leverage |
|---|---|---|---|
| 1 | 50,000 | 0.40% | 125× |
| 2 | 250,000 | 0.50% | 100× |
| 3 | 1,000,000 | 1.00% | 50× |
| 4 | 5,000,000 | 2.50% | 20× |
| 5 | 20,000,000 | 5.00% | 10× |
| 6 | 50,000,000 | 10.00% | 5× |
| 7 | 100,000,000 | 12.50% | 4× |
| 8 | 200,000,000 | 15.00% | 2× |
Order gate
When a user in unified mode submits a new opening order, the server
simulates the post-fill uniMMR. The order is rejected if:
- Account status is
reduce_onlyorliquidating, OR available_balance − new_initial_margin < 0, ORsimulated_uniMMR < 1.10
Reducing / closing orders bypass the check.
Endpoint Map
| Method | Path | Purpose |
|---|---|---|
POST | /api/v1/account/margin-mode | Switch mode |
GET | /api/v1/unified/account | Account snapshot |
POST | /api/v1/unified/risk/simulate | Pre-trade simulation |
GET | /api/v1/unified/liquidations | Liquidation history |
WS | channel unified_account | Live push |
All endpoints live under the standard https://api.ztdx.io host and
require the same HMAC-SHA256 / JWT authentication as the rest of the
/api/v1/* namespace.