> For the complete documentation index, see [llms.txt](https://docs.reya.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reya.xyz/developers/devnet/risk/margin-system.md).

# Margin System

Reya margins your **whole account as a portfolio**, not position-by-position. Within a market, your long and short exposure nets off, and all positions draw on one shared margin balance — which is what makes cross-margining capital-efficient.

## The two requirements

Both derive from a single portfolio risk number:

* **Initial Margin (IM)** — required to **open or increase** a position.
* **Liquidation Margin Requirement (LMR)** — the base risk number; **fall below it and the account becomes liquidatable** (see [Liquidations & ADL](/developers/devnet/risk/liquidations-and-adl.md)).

## How it's computed

Each market carries its **own risk factor**, and cross-market correlations are **not modelled** — a position in one market neither offsets nor amplifies another market's requirement. So your account requirement is simply the **sum** of the per-market requirements. Within a single market, your **net** exposure is what counts — longs net against shorts. All quantities are in **rUSD** (the wrapped-USDC quote / settlement collateral). The per-market parameters that drive this are published on each market's definition (see below), and the [next section](#computing-your-requirement) shows how to put them together.

## Where to get the per-market parameters

Each market's risk parameters are published on its [`perpMarketDefinitions`](/developers/devnet/api-reference/rest-api-reference.md) entry (see [Markets & Assets](/developers/devnet/reference/markets-and-assets.md)):

* `maxLeverage` — the maximum leverage allowed for the market.
* `liquidationMarginParameter` — drives the market's **liquidation** margin requirement (LMR).
* `initialMarginParameter` — drives the market's **initial** margin requirement (IM).

Read these per market to size positions and set your own buffer above the liquidation requirement.

## What "margin balance" means

The IM and LMR checks compare against your **margin balance**, which is your **equity, not your raw deposited collateral**. It is your collateral balance **plus unrealised PnL, plus accrued funding** (and any ADL / realized-PnL cashflows), all valued at the current mark price. Because unrealised PnL is included, your margin balance **falls as your positions move against you** — even if you never deposit or withdraw.

The V2 `AccountBalance` fields don't give you this figure directly. `realBalance` is *net deposits plus realized PnL from closed positions* — it **excludes unrealised PnL and funding**, so it **overstates** your margin balance while an open position is underwater (`balanceDEPRECATED` is raw collateral only). To size a buffer safely, reconstruct margin balance yourself as **`realBalance` + unrealised PnL on your open positions (marked to the current mark price) + accrued funding**. Treat this as an estimate for sizing your buffer. Actual trading capacity also depends on collateral valuation and pending fills; the pre-trade checks below determine whether a request is accepted.

## Computing your requirement

Work it out **per market, then sum across markets**. For each market, using the parameters above:

* **Notional** — your net position size, in rUSD: `notional = |net base position| × markPrice` (see [Mark Price](/developers/devnet/pricing-and-funding/mark-price.md)).
* **Initial margin** (required to open or increase): `IM = initialMarginParameter × notional`, equivalently `notional / maxLeverage`.
* **Liquidation requirement**: `LMR = liquidationMarginParameter × notional`.

Across your whole account, sum the per-market requirements:

* `IM = Σ (IM per market)`
* `LMR = Σ (LMR per market)`

You become **liquidatable** once your account margin balance falls below `LMR`, and you **can't open or increase** a position if doing so would drop your margin below `IM`.

### Worked example

An ETH-perp market with `liquidationMarginParameter = 0.04`, `initialMarginParameter = 0.05`, and `maxLeverage = 20`. A **10 ETH long** at a mark price of **3,000 rUSD**:

* `notional = 10 × 3,000 = 30,000 rUSD`
* `IM = 0.05 × 30,000 = 1,500 rUSD` (equivalently `30,000 / 20`) — you need at least **1,500 rUSD** of margin to open it.
* `LMR = 0.04 × 30,000 = 1,200 rUSD` — you become liquidatable if your account margin balance falls below **1,200 rUSD**.

## Pre-trade risk checks

**Pre-trade risk is live on devnet1 for spot and perp orders.** Reya checks margin, balances, open-interest limits and reduce-only constraints before matching. Passing these checks does not confirm settlement; use the executions channels for confirmed trades.

* **Incoming creates and crossing modifies:** a failed risk check returns a request error. A rejected modify leaves the existing order unchanged.
* **Pending settlement:** fills awaiting settlement count against available margin, open-interest capacity and spot balances. Later requests can be rejected until those fills are resolved.
* **Reducing risk:** an account between initial and liquidation margin may make a qualifying risk-reducing trade. Normal trading below the liquidation-margin / real-balance floor is rejected; see [Liquidations & ADL](/developers/devnet/risk/liquidations-and-adl.md).

### Handling risk outcomes

| Surface                | Outcome                                                              | Client action                                                                                                                    |
| ---------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| REST / WS Order Entry  | `ACCOUNT_BELOW_INITIAL_MARGIN_ERROR`                                 | Add collateral, reduce size or submit an eligible risk-reducing order                                                            |
| REST / WS Order Entry  | `ACCOUNT_BELOW_LIQUIDATION_MARGIN_ERROR`                             | Restore the account's margin / real-balance floor; ordinary reducing orders do not bypass it                                     |
| REST / WS Order Entry  | `OPEN_INTEREST_CAP_ERROR` / `OPEN_INTEREST_BUDGET_ERROR`             | Account for the market cap and pending-fill budget; do not blindly resubmit                                                      |
| REST / WS Order Entry  | `REDUCE_ONLY_CONDITION_NOT_MET_ERROR` / `INSUFFICIENT_BALANCE_ERROR` | Correct the reducible size or available spot balance                                                                             |
| REST / WS Order Entry  | `CROSSING_ORDERS_TEMPORARILY_UNAVAILABLE_ERROR`                      | Retry the crossing request after a short delay. Existing resting orders remain unchanged and can still be cancelled              |
| WS Info `orderChanges` | `RISK_CANCELLED`                                                     | Remove the cancelled maker from local order state; reassess capacity before replacing it                                         |
| WS Info `orderChanges` | `RISK_REJECTED`                                                      | A protective fire was refused before a child existed; both armed legs are cancelled and protection must be re-armed deliberately |

For cancellation events, `cancelReasonMessage` is a **fixed explanation per reason**, not the individual failed risk check. Do not parse it to choose a recovery path. Interactive request errors may include more specific diagnostic messages; use the error code for classification.

Continue reconciling [executions](/developers/devnet/executions-and-settlement/executions-and-trade-history.md) and [trade busts](/developers/devnet/executions-and-settlement/trade-busts.md). Pre-trade checks reduce settlement failures; they do not make a matching-engine acknowledgement final.

## What this means for integrators

* **Cross-margin within an account, isolated between accounts.** Your account is margined as one portfolio — within a market, long and short exposure nets off; separate accounts never share margin (see [Accounts & Subaccounts](/developers/devnet/getting-started/accounts-and-subaccounts.md)).
* **Keep a buffer above the liquidation requirement (LMR).** Liquidation triggers on margin, and the [liquidation waterfall](/developers/devnet/risk/liquidations-and-adl.md) acts quickly once you cross it — keepers catch accounts shortly after they breach LMR.