Documentation Index
Fetch the complete documentation index at: https://docs.phoenix.trade/llms.txt
Use this file to discover all available pages before exploring further.
Phoenix evaluates each trader account as a single margin account. Positions, funding, unrealized PnL, and risk-increasing resting orders all feed into the same account health calculation.
Margin is the mechanism that lets traders take positions larger than their posted collateral while keeping the exchange solvent. A perp venue always has a long and a short side for the same open interest. When one side has unrealized profit, the other side has the matching liability. The risk system is designed to keep those liabilities collateralized and to make sure risky positions can be reduced before they create bad debt.
At a high level:
account_health = effective_collateral - margin_requirement
Risk invariants
Phoenix margin is built around three practical invariants:
- long and short open interest must balance
- unrealized profits must be matched by liabilities elsewhere in the system
- those liabilities must remain collateralized
If a losing account can no longer cover the unrealized profit owed to the other side, the system has bad debt. Margin requirements, mark prices, funding, liquidation thresholds, and open interest controls all exist to reduce the probability of that outcome.
Effective collateral
Effective collateral is the collateral value Phoenix uses for risk checks. It is similar to account equity, but Phoenix can discount positive unrealized PnL before treating it as usable collateral.
effective_collateral = deposited_collateral
+ discounted_positive_unrealized_pnl
+ negative_unrealized_pnl
+ unsettled_funding
- deposited collateral is the USDC collateral balance on the trader account
- positive unrealized PnL can be discounted by the market’s
uPnL risk factor
- negative unrealized PnL counts in full
- unsettled funding is included because it changes account risk before final settlement
Phoenix discounts positive uPnL to reduce the risk that manipulated or unstable mark prices create too much usable collateral. This matters more for volatile or lower-liquidity assets, where mark prices can be easier to move temporarily.
See Market Parameters for market-specific uPnL risk factor values.
Mark price and PnL
Position value is based on mark price, not the last trade price.
unrealized_pnl = position_size * (mark_price - entry_price)
Position margin
For each market, Phoenix calculates margin from the absolute position size and the market’s leverage tier.
position_notional = abs(position_size) * mark_price
position_margin = position_notional / max_leverage_for_size
Limit-order margin
Risk-increasing resting limit orders can require margin before they fill.
Phoenix evaluates resting bids and resting asks separately for each market:
market_initial_margin = position_margin
+ max(bid_side_margin_increase, ask_side_margin_increase)
side_margin_increase =
(margin_after_side_fills - current_position_margin)
* limit_order_risk_factor
- reduce-only orders do not add margin
- orders that only reduce or close the current position do not add margin
- limit-order margin uses the market’s mark price and size, not the order’s limit price
limit_order_risk_factor is market- and tier-specific- limit-order margin is part of initial margin and can move an account toward the cancellation threshold before the order fills
See Leverage Tiers and Market Parameters.
Example portfolio
Assume a cross account has 12,000 USDC deposited collateral and the following open positions:
| Market | Position | Entry | Mark | Unrealized PnL |
|---|
| BTC-PERP | Long 0.10 BTC | 60,000 | 62,000 | +200 USDC |
| SOL-PERP | Short 100 SOL | 150 | 140 | +1,000 USDC |
100% collateral credit for trading risk checks. Assume unsettled funding is -50 USDC.
discounted_positive_unrealized_pnl = (200 + 1,000) * 1.00 = 1,200.000000
effective_collateral = 12,000 + 1,200 - 50 = 13,150.000000 USDC
phoenix/market-parameters-fallback.json. Values below include the quote-lot rounding used by the Rise margin calculator.
| Market | Position notional | Max leverage | Position margin |
|---|
| BTC-PERP | 0.10 * 62,000 = 6,200 | 20x | 310.000000 |
| SOL-PERP | 100 * 140 = 14,000 | 15x | 933.333334 |
| Market | Resting orders | Effect if filled |
|---|
| ETH-PERP | Bid 2 ETH, ask 1 ETH | No current ETH position, so either side opens exposure |
| SOL-PERP | Bid 50 SOL, ask 25 SOL | The bid reduces the short; the ask increases the short |
3,000 and SOL mark price is 140. In the fallback parameters, ETH uses 20x first-tier max leverage, SOL uses 15x, and both markets use a 100% first-tier limit_order_risk_factor.
For ETH:
bid side: 2 ETH * 3,000 / 20x = 300.000000 initial margin
bid limit-order margin = 300.000000 * 100% = 300.000000
ask side: 1 ETH * 3,000 / 20x = 150.000000 initial margin
ask limit-order margin = 150.000000 * 100% = 150.000000
ETH market initial margin = 0 + max(300.000000, 150.000000) = 300.000000
current short position margin = 100 SOL * 140 / 15x = 933.333334
bid side: buying 50 SOL reduces the short from 100 SOL to 50 SOL
bid limit-order margin = 0
ask side: selling 25 SOL increases the short from 100 SOL to 125 SOL
margin after ask fills = 125 SOL * 140 / 15x = 1,166.666667
incremental margin = 1,166.666667 - 933.333334 = 233.333333
ask limit-order margin = 233.333333 * 100% = 233.333333
SOL market initial margin = 933.333334 + max(0, 233.333333) = 1,166.666667
BTC margin = 310.000000
SOL margin = 1,166.666667
ETH margin = 300.000000
total_initial_margin = 1,776.666667 USDC
13,150.000000 effective collateral > 1,776.666667 initial margin
| Threshold | Calculation | Result |
|---|
| Cancel margin | BTC 310.000000 * 70% + SOL 1,166.666667 * 75% + ETH 300.000000 * 70% | 1,302.000000 |
| Maintenance margin | total_initial_margin * 50% | 888.333333 |
| Backstop requirement | total_initial_margin * 20% | 355.333333 |
| High-risk margin | total_initial_margin * 10% | 177.666666 |
Maintenance margin and other thresholds
Phoenix derives lower risk thresholds from initial margin using market-specific risk factors. These thresholds are the escalation ladder the protocol uses as an account becomes more dangerous to the system.
cancel_margin = initial_margin * cancel_order_risk_factor
maintenance_margin = initial_margin * maintenance_risk_factor
backstop_requirement = initial_margin * backstop_risk_factor
high_risk_margin = initial_margin * high_risk_factor
- below cancel margin: risk-increasing limit orders can be cancelled
- below maintenance margin: market liquidation can begin
- below backstop requirement: distressed positions can be transferred to a backstop account
- below high-risk margin: ADL can become available
See Liquidations for the liquidation sequence.
Liquidation estimates
Liquidation price is an estimate, not a fixed promise.
For a single position, Phoenix solves for the mark price where effective collateral would fall to the relevant maintenance requirement:
collateral + other_upnl + q * (P - entry)
= other_maintenance_margin + maintenance_factor * abs(q) * P / L
q is signed position sizeP is the estimated liquidation priceL is the active leverage tierother_upnl is the contribution from other markets in the same cross accountother_maintenance_margin is the maintenance margin from other markets in the same cross account
This is why cross-margin liquidation prices can move when funding, mark prices, other positions, or resting orders change.
In a cross account, profitable positions in one market can support risk in another market. That is capital efficient, but it also means liquidation estimates are portfolio-aware. A BTC liquidation price can move because SOL PnL changed, funding settled, or a risk-increasing ETH order was placed.
See Liquidations for the expanded formula and limit-order example.