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

# Margin Framework

> Initial, maintenance, reserved margin, and how health is computed.

<style>
  {`
    .katex-display {
      overflow-x: auto;
      overflow-y: hidden;
      scrollbar-width: none;
      -ms-overflow-style: none;
    }
    .katex-display::-webkit-scrollbar {
      display: none;
      height: 0;
      width: 0;
    }
    `}
</style>

Kimia uses a **cross-margin** model per market: one `UserAccount` holds one
position and the collateral that backs it. Free collateral is shared between
the open position and any resting orders.

## Margin types

| Type                   | When checked                                        | Default                                 |
| ---------------------- | --------------------------------------------------- | --------------------------------------- |
| **Initial margin**     | Opening or increasing a position, and on withdrawal | 1000 bps (10%)                          |
| **Maintenance margin** | Every time a margin sensor runs (liquidation check) | 500 bps (5%)                            |
| **Reserved margin**    | At `place_order` placement (resting orders)         | Locks `notional × initial_margin_ratio` |

## Formulas

$$
\text{notional} = \frac{|\text{base\_amount}| \times \text{price}}{\text{BASE\_PRECISION}}
$$

$$
\text{initial\_req} = \frac{\text{notional} \times \text{initial\_margin\_ratio}}{10{,}000}
$$

$$
\text{maint\_req} = \frac{\text{notional} \times \text{maintenance\_margin\_ratio}}{10{,}000}
$$

$$
\text{free\_collateral} = \text{collateral} - \text{total\_reserved\_margin}
$$

$$
\text{health} = \text{free\_collateral} + \text{unrealized\_pnl} - \text{maint\_req}
$$

Liquidation triggers when $\text{health} \leq 0$.

## Why reserved margin?

Without reservation, an attacker could:

1. Deposit 100 USDC.
2. Place 10 resting limit orders, each of which *individually* passes the
   initial-margin check.
3. Wait for adverse fills, and end up with a position whose required margin
   exceeds their deposit.

Reserving margin at placement ties each order to real, untouched collateral.

## Max leverage

$$
\text{max\_leverage} = \frac{10{,}000}{\text{initial\_margin\_ratio}}
$$

With V1's 1000 bps ratio, that's **10×**.

## Liquidation price

Given an open position, the liquidation price is where `health` hits 0:

**Long:**

$$
\text{liq\_price} = \text{entry} - \frac{\text{collateral} - \text{maint\_req}}{|\text{base}|}
$$

**Short:**

$$
\text{liq\_price} = \text{entry} + \frac{\text{collateral} - \text{maint\_req}}{|\text{base}|}
$$

The app displays this live and recalculates whenever your collateral or
position size changes.

## Worked example

```
Deposit:  1,000 USDC
Open:     5 SOL long @ $130 (notional = $650, 6.5× leverage)

initial_req = 650 × 0.10 = $65      ← check passes (free = $1,000)
maint_req   = 650 × 0.05 = $32.5

liq_price (long) = 130 − (1,000 − 32.5) / 5 = 130 − 193.5 = negative
                → i.e. never liquidated until funding eats collateral
```

## Settling funding changes collateral

Funding payments move silently in and out of `UserAccount.collateral` when
`settle_funding` runs or when you trade. That means:

* Your **liquidation price drifts** over time even if mark hasn't moved.
* Watch both mark and your collateral balance.
* Holding a losing direction through many funding periods can trigger
  liquidation purely from funding, not from adverse price.