> ## 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 theme={null}
account_health = effective_collateral - 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.

```text theme={null}
effective_collateral = deposited_collateral
  + discounted_positive_unrealized_pnl
  + negative_unrealized_pnl
  + unsettled_funding
```

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 theme={null}
unrealized_pnl = position_size * (mark_price - entry_price)
```

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 theme={null}
position_notional = abs(position_size) * mark_price

position_margin = position_notional / max_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:

```text theme={null}
market_initial_margin = position_margin
  + max(bid_side_margin_increase, ask_side_margin_increase)
```

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:

```text theme={null}
side_margin_increase =
  (margin_after_side_fills - current_position_margin)
  * limit_order_risk_factor
```

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

```text theme={null}
discounted_positive_unrealized_pnl = (200 + 1,000) * 1.00 = 1,200.000000

effective_collateral = 12,000 + 1,200 - 50 = 13,150.000000 USDC
```

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 * 62,000 = 6,200` | `20x`        | `310.000000`    |
| SOL    | `100 * 140 = 14,000`    | `15x`        | `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`.

For ETH:

```text theme={null}
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
```

For SOL:

```text theme={null}
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
```

Total initial margin:

```text theme={null}
BTC margin = 310.000000
SOL margin = 1,166.666667
ETH margin = 300.000000

total_initial_margin = 1,776.666667 USDC
```

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

```text theme={null}
13,150.000000 effective collateral > 1,776.666667 initial margin
```

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

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

```text theme={null}
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
```

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:

```text theme={null}
collateral + other_upnl + q * (P - entry)
  = other_maintenance_margin + maintenance_factor * abs(q) * P / L
```

Where:

* `q` is signed position size
* `P` is the estimated liquidation price
* `L` is the active leverage tier
* `other_upnl` is the contribution from other markets in the same cross account
* `other_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](/phoenix/margin-and-risk/liquidations) for the expanded formula and limit-order example.