Skip to main content
This page is a reference for all the key formulas used on Orderly. Each section explains what a value means in plain language, then gives the exact formula. If you are building a trading bot or just want to double-check the numbers you see in the UI, this is the page to bookmark.

Margin and Balance Formulas

Futures Margin Ratio

Your margin ratio tells you how healthy your account is. It compares how much collateral you have against how large your open positions are. A higher ratio means your account is in better shape. Current margin ratio = total_collateral_value / sum(abs(position_notional_i))

Total Collateral

This is the total value of everything backing your positions. It includes your USDC balance plus any unrealized profit or loss you have not yet settled. It does not factor in pending orders. Total collateral of the user (doesn’t account for any pending orders, includes unsettled PnL) = total_balance + upnl + pending_short_USDC

Free Collateral

Free collateral is the portion of your collateral that is still available for opening new trades. Unlike total collateral, it does account for margin already reserved by your pending orders. Available collateral/balance to trade (accounts for any pending orders, includes unsettled PnL) = collateral + upnl - total_initial_margin_with_orders - pending_short_USDC

Portfolio Value

This is the total dollar value of everything in your account, including the notional value of your positions. Total portfolio value including position notionals = USDC Balance + (non USDC assets) * mid_price + unsettled pnl

Withdrawable Balance

This is how much you can actually withdraw from your account right now. It is more conservative than free collateral because it excludes any unrealized profits (you can only withdraw profits after settling PnL). Collateral available to withdraw (excludes unsettled PnL) = total_balance - total_initial_margin_with_orders - positive_upnl Here are two examples to show the difference between free collateral and withdrawable balance: Example 1 (unrealized loss): Your total_balance = 100 USDC, unsettled PnL = -40 USDC, so total_collateral is 60 USDC. You have a position using 20 USDC of maintenance margin. In this case, free_collateral or withdrawable_balance = 60 - 20 = 40 USDC. Example 2 (unrealized profit): Your total_balance = 100 USDC, unsettled PnL = +40 USDC, so total_collateral is 140 USDC. But for withdrawal purposes, only 100 USDC counts. With 20 USDC of maintenance margin, free_collateral = 140 - 20 = 120 USDC, but withdrawable_balance = 100 - 20 = 80 USDC.
Withdrawable balance/collateral does not equal to total or free collateral.

Initial Margin Ratio

The Initial Margin Ratio (IMR) determines how much margin you need to open or maintain a position. It scales up for larger positions, meaning you need proportionally more margin as your position grows. This prevents traders from taking on dangerously large positions with minimal collateral.

Maintenance Margin Ratio

The Maintenance Margin Ratio (MMR) is the minimum margin ratio your account must hold to avoid liquidation. It is always lower than the IMR, giving you a buffer between “you can’t open new positions” and “your positions get liquidated.”

Positions PnL

These formulas let you calculate how much you are making or losing on your open positions, and at what price your position would get liquidated. Unrealized PnL tells you the current profit or loss on an open position, based on the current mark price compared to your entry price. Unrealized PnL = position_qty * (mark_price - avg_open) Liquidation Price is the price at which your account would fall below the maintenance margin and get liquidated. Knowing this number helps you manage risk.
Notional is the total USDC value of a single position. It is simply the mark price multiplied by the number of contracts you hold. Notional = position_notional_i = abs(mark_price_i * position_qty_i) Fut Notional or Total Notional is the sum of the notional values across all your positions. Fut Notional or Total Notional = sum (abs (position_notional_i))

API Data Mapping

To implement these formulas, you can retrieve the base values from the following API endpoints:

Risk Management Pseudocode

The following pseudocode demonstrates how to integrate the formulas into a cohesive risk management logic for a trading bot.

Max Order Quantity

This formula calculates the largest order you can place for a given market, based on your available collateral and the margin requirements. The system also checks whether you already have enough margin or whether iterative calculation is needed for very large orders.
The full logic, including edge cases when your collateral is already fully used, works as follows:

Liquidation Price

This estimates your liquidation price after a new order would be filled. It is useful for previewing the risk of a trade before you submit it.