Position Metrics, Margin & Liquidation Price - Rails Trading Developer API Documentation

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 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 and Simulated Cross Margin Ratio.

Usage in API

These calculations are used in the Get Account Positions and 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.

​Key Definitions

​Average Entry Price & Notional Value

​Unrealized PnL

​Position Margin & Maintenance Margin

​Liquidation Price

​Usage in API