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

# Margin Math

> How Phoenix calculates effective collateral, position margin, and limit-order margin

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:

$$
\text{account health} = \text{effective collateral} - \text{margin requirement}
$$

If effective collateral falls through the risk thresholds, Phoenix can cancel risk-increasing orders, liquidate through the order book, escalate to backstop liquidation, and finally use ADL.

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

$$
\begin{aligned}
\text{effective collateral} ={}& \text{deposited collateral} \\
&+ \text{discounted positive unrealized PnL} \\
&+ \text{negative unrealized PnL} \\
&+ \text{unsettled funding}
\end{aligned}
$$

Important details:

* 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](/phoenix/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.

$$
\text{unrealized PnL}
= \text{position size} \times \left(\text{mark price} - \text{entry price}\right)
$$

Using mark price for PnL, margin, and liquidation checks helps prevent a single trade or thin order book from pushing accounts into unsafe states. See [Mark Price](/phoenix/margin-and-risk/mark-price) for how Phoenix builds the mark.

## Position margin

For each market, Phoenix calculates margin from the absolute position size and the market's leverage tier.

$$
\text{position notional}
= \left|\text{position size}\right| \times \text{mark price}
$$

$$
\text{position margin}
= \frac{\text{position notional}}{\text{maximum leverage for size}}
$$

The leverage tier is selected from the resulting position size. A fill that moves the total position into a different tier can change margin for the whole resulting position, not only the newest fill.

## 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:

$$
M_{\text{market, initial}}
= M_{\text{position}} + \max\left(\Delta M_{\text{bid}},\ \Delta M_{\text{ask}}\right)
$$

This matters because a trader cannot fill every bid and every ask in the same market into the same final directional exposure. Phoenix therefore reserves margin for the worse side, not the sum of both sides.

The margin increase for each side is based on the hypothetical position if those non-reduce-only orders fill:

$$
\Delta M_{\text{side}}
= \left(M_{\text{post-fill}} - M_{\text{position}}\right) \times f_{\text{limit order}}
$$

Notes:

* 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](/phoenix/margin-and-risk/leverage-tiers) and [Market Parameters](/phoenix/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    | Long `0.10 BTC` | `60,000` | `62,000` | `+200 USDC`    |
| SOL    | Short `100 SOL` | `150`    | `140`    | `+1,000 USDC`  |

Using the fallback market parameters for BTC and SOL, positive uPnL receives `100%` collateral credit for trading risk checks. Assume unsettled funding is `-50 USDC`.

$$
\begin{aligned}
\text{discounted positive unrealized PnL}
&= \left(200 + 1{,}000\right) \times 1.00 \\
&= 1{,}200.000000
\end{aligned}
$$

$$
\begin{aligned}
\text{effective collateral}
&= 12{,}000 + 1{,}200 - 50 \\
&= 13{,}150.000000\ \text{USDC}
\end{aligned}
$$

Now calculate position margin using the first leverage tier from `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    | $0.10 \times 62{,}000 = 6{,}200$ | $20\times$   | $310.000000$    |
| SOL    | $100 \times 140 = 14{,}000$      | $15\times$   | $933.333334$    |

The account also has resting limit orders:

| Market | Resting orders             | Effect if filled                                       |
| ------ | -------------------------- | ------------------------------------------------------ |
| ETH    | Bid `2 ETH`, ask `1 ETH`   | No current ETH position, so either side opens exposure |
| SOL    | Bid `50 SOL`, ask `25 SOL` | The bid reduces the short; the ask increases the short |

Assume ETH mark price is `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`.

In the calculations below, $M$ denotes margin and $\Delta M$ denotes an increase in margin.

For ETH:

$$
M_{\text{bid, initial}}
= \frac{2\ \text{ETH} \times 3{,}000}{20}
= 300.000000
$$

$$
M_{\text{bid, order}}
= 300.000000 \times 100\%
= 300.000000
$$

$$
M_{\text{ask, initial}}
= \frac{1\ \text{ETH} \times 3{,}000}{20}
= 150.000000
$$

$$
M_{\text{ask, order}}
= 150.000000 \times 100\%
= 150.000000
$$

$$
M_{\text{ETH, initial}}
= 0 + \max\left(300.000000, 150.000000\right)
= 300.000000
$$

For SOL:

$$
M_{\text{SOL, position}}
= \frac{100\ \text{SOL} \times 140}{15}
= 933.333334
$$

Buying $50\ \text{SOL}$ reduces the short from $100\ \text{SOL}$ to $50\ \text{SOL}$, so:

$$
M_{\text{bid, order}} = 0
$$

Selling $25\ \text{SOL}$ increases the short from $100\ \text{SOL}$ to $125\ \text{SOL}$, so:

$$
\begin{aligned}
M_{\text{post-ask}} &= \frac{125\ \text{SOL} \times 140}{15} = 1{,}166.666667 \\[0.75em]
\Delta M_{\text{ask}} &= 1{,}166.666667 - 933.333334 = 233.333333 \\[0.75em]
M_{\text{ask, order}} &= 233.333333 \times 100\% = 233.333333
\end{aligned}
$$

$$
M_{\text{SOL, initial}}
= 933.333334 + \max\left(0, 233.333333\right)
= 1{,}166.666667
$$

Total initial margin:

$$
\begin{aligned}
\text{BTC margin} &= 310.000000 \\[0.5em]
\text{SOL margin} &= 1{,}166.666667 \\[0.5em]
\text{ETH margin} &= 300.000000 \\[1em]
\text{total initial margin} &= 1{,}776.666667\ \text{USDC}
\end{aligned}
$$

The account is healthy because effective collateral is above initial margin:

$$
13{,}150.000000\ \text{effective collateral}
> 1{,}776.666667\ \text{initial margin}
$$

Using the fallback threshold factors for these markets, the account's risk thresholds would be:

| Threshold            | Calculation                                                                    | Result           |
| -------------------- | ------------------------------------------------------------------------------ | ---------------- |
| Cancel margin        | $310.000000 \times 70\% + 1{,}166.666667 \times 75\% + 300.000000 \times 70\%$ | $1{,}302.000000$ |
| Maintenance margin   | $\text{total initial margin} \times 50\%$                                      | $888.333333$     |
| Backstop requirement | $\text{total initial margin} \times 20\%$                                      | $355.333333$     |
| High-risk margin     | $\text{total initial margin} \times 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.

$$
\begin{aligned}
M_{\text{cancel}} &= M_{\text{initial}} \times f_{\text{cancel}} \\[0.5em]
M_{\text{maintenance}} &= M_{\text{initial}} \times f_{\text{maintenance}} \\[0.5em]
M_{\text{backstop}} &= M_{\text{initial}} \times f_{\text{backstop}} \\[0.5em]
M_{\text{high risk}} &= M_{\text{initial}} \times f_{\text{high risk}}
\end{aligned}
$$

Here, $M$ is the margin threshold and $f$ is its corresponding market-specific risk factor.

Initial margin is the opening and healthy-account requirement. Maintenance margin is the main liquidation threshold. If effective collateral falls below maintenance margin, the account can be liquidated.

The broader risk sequence is:

* 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](/phoenix/margin-and-risk/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:

$$
C + U_{\text{other}} + q\left(P - P_{\text{entry}}\right) = M_{\text{other}} + \frac{f_{\text{maintenance}}\left|q\right|P}{L}
$$

Where:

* $C$ is collateral
* $U_{\text{other}}$ is the unrealized PnL contribution from other markets in the same cross account
* $q$ is signed position size
* $P$ is the estimated liquidation price
* $L$ is the active leverage tier
* $M_{\text{other}}$ is the maintenance margin from other markets in the same cross account
* $f_{\text{maintenance}}$ is the maintenance risk factor

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](/phoenix/margin-and-risk/liquidations) for the expanded formula and limit-order example.