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 + Σ position_collateral + Σ unrealized_pnl − Σ accumulated_fees
• total_maintenance_margin = Σ MM_per_position

When a position is opened its margin is debited from the wallet balance into the position's collateral, so Σ position_collateral is added back to make equity reflect the user's total funds on the platform — not just the uncommitted cash.

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).

Independently of uniMMR: if any open position's symbol is missing a mark price, the account is forced to reduce_only (risk-conservative gate — trading stays restricted until prices recover). An account already in liquidating is not downgraded by this rule.

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_only or liquidating, OR
• available_balance − new_initial_margin < 0, OR
• simulated_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
GET	/api/v1/admin/margin-tiers	List all margin-tier rows
POST	/api/v1/admin/margin-tiers	Upsert a tier row by (symbol, tier)
DELETE	/api/v1/admin/margin-tiers	Delete a tier row by (symbol, tier)
POST	/api/v1/admin/margin-tiers/reload	Hot-reload the in-memory tier store from DB

All user-facing 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.

The /admin/margin-tiers endpoints are operator-only and protected by X-API-Key (like the other /api/v1/admin/* routes). They manage the per-symbol maintenance-margin tier table; after editing tiers, call POST /admin/margin-tiers/reload — the new ladder takes effect immediately for all subsequent risk computations, no restart required.