> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rails.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Position Metrics, Margin & Liquidation Price

In our trading system, per-position metrics are derived from position value and quantity. Entry price, unrealized PnL, notional value, margin requirements, and liquidation price all update in real time as the index price changes.

## Key Definitions

| Term              | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| **positionQty**   | Signed position size — positive for long, negative for short |
| **positionValue** | Signed cost basis of the position                            |
| **indexPrice**    | Current market index price                                   |
| **leverage**      | Leverage applied to the position                             |
| **MMR**           | Maintenance margin rate — fixed at `0.05` (5%)               |
| **side**          | `+1` for long positions, `-1` for short positions            |
| **marginMode**    | `C` for cross margin, `I` for isolated margin                |

## Average Entry Price & Notional Value

| Field                     | Formula                       | Description                                  |
| ------------------------- | ----------------------------- | -------------------------------------------- |
| **avgEntryPrice**         | `positionValue / positionQty` | Weighted average fill price for the position |
| **positionNotionalValue** | `indexPrice × positionQty`    | Signed current market value of the position  |

## Unrealized PnL

Unrealized PnL reflects the current profit or loss on an open position, based on the index price relative to the average entry price.

```
unrealizedPnL = (indexPrice - avgEntryPrice) × positionQty
```

Because `positionQty` is signed, this formula naturally handles both directions:

* **Long** (`positionQty > 0`): profit when `indexPrice > avgEntryPrice`
* **Short** (`positionQty < 0`): profit when `indexPrice < avgEntryPrice`

## Position Margin & Maintenance Margin

Position margin is the collateral locked to support an open position. Maintenance margin is the minimum collateral required to keep the position open.

| Field                 | Formula                                    | Description                                                   |
| --------------------- | ------------------------------------------ | ------------------------------------------------------------- |
| **positionMargin**    | `indexPrice × ABS(positionQty) / leverage` | Collateral locked for the position at the current index price |
| **maintenanceMargin** | `indexPrice × ABS(positionQty) × MMR`      | Minimum collateral required to keep the position open         |

The maintenance margin rate (MMR) is fixed at 5% and applied to every position regardless of size. The liquidation trigger depends on the position's `marginMode`:

* **Cross margin (`C`):** at risk when `crossMarginEquity` falls below the sum of maintenance margins across all cross margin positions.
* **Isolated margin (`I`):** at risk when the position's `isolatedPositionEquity` falls below its own maintenance margin.

## Liquidation Price

The liquidation price is the index price at which a position will be forcibly closed due to insufficient margin. The formula has the same shape in both margin modes — only the definition of `marginAvailable` differs.

```
liqPrice = indexPrice - (side × marginAvailable) / (ABS(positionQty) × (1 - side × MMR))
```

| Margin Mode    | `marginAvailable`                                                                      |
| -------------- | -------------------------------------------------------------------------------------- |
| Cross (`C`)    | `crossMarginEquity - totalCrossMaintenanceMargin`  — across all cross margin positions |
| Isolated (`I`) | `isolatedPositionEquity - maintenanceMargin`  — for that position only                 |

`marginAvailable` is the equity cushion remaining after covering maintenance margin. It differs from `availableBalance` (See [Available Balance](/latest/account-balance#available-balance) for the formula), which is based on position margin and open order margin.

For account-wide health metrics derived from these per-position values, see [Cross Margin Ratio](/latest/account-balance#cross-margin-ratio) and [Simulated Cross Margin Ratio](/latest/account-balance#simulated-cross-margin-ratio).

## Usage in API

These calculations are used in the [Get Account Positions](/latest/rest-api/get-account-positions) and [Get Account Balances](/latest/rest-api/get-account-balances) responses. Note that several formula variable names differ from their corresponding response field names:

| Formula variable        | Response field     | Endpoint              |
| ----------------------- | ------------------ | --------------------- |
| `positionValue`         | `value`            | Get Account Positions |
| `positionQty`           | `quantity`         | Get Account Positions |
| `unrealizedPnL`         | `unrealizedPnl`    | Get Account Positions |
| `positionNotionalValue` | `notionalValue`    | Get Account Positions |
| `liqPrice`              | `liquidationPrice` | Get Account Positions |
| `positionMargin`        | `margin`           | Get Account Balances  |

`avgEntryPrice` is not returned directly — derive it from `value / quantity` in the positions response.