> ## 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.

# Perpetuals

> How Kimia's perpetual futures engine works.

<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's perpetual futures engine (`kimia-perp`) is an on-chain orderbook-based derivatives
exchange. It supports long and short positions on SOL-PERP (V1) with USDC as the single
collateral type.

## What makes it distinct

* **On-chain FIFO orderbook**, up to 32 bids and 32 asks per market, matched in
  price-then-time priority. Up to 4 fills per transaction to stay inside compute limits.
* **Single-position-per-market** (V1), one user account holds one directional position
  per market; switching direction requires closing first.
* **Reserved margin for resting orders**, margin locks at placement, not fill,
  preventing order-book spam from over-leveraging the account.
* **Permissionless funding + liquidation**, any keeper can crank.
* **Pyth Hermes Pull Oracles**, prices are posted and consumed in the same tx.

## Precision

| Quantity                  | Decimals | Precision       |
| ------------------------- | -------- | --------------- |
| Base (SOL)                | 9        | `1_000_000_000` |
| Quote / collateral (USDC) | 6        | `1_000_000`     |
| Price                     | 6        | `1_000_000`     |
| Funding rate              | 9        | `1_000_000_000` |
| Margin ratio / BPS        | 4        | `10_000`        |

## Position math

A position has a signed `base_amount` (positive = long, negative = short) and a
`quote_entry` accumulator.

$$
\text{unrealizedPnL} = \frac{\text{base} \times \text{mark}}{10^9} + \text{quoteEntry}
$$

For a long at entry $E$ with mark $M$:
`pnl = base·M - base·E = base·(M-E)` ✓

For a short at entry $E$ with mark $M$:
`pnl = -base·M + base·E = base·(E-M)` ✓

## Margin model

| Check               | Formula                                      | When                            |
| ------------------- | -------------------------------------------- | ------------------------------- |
| Initial margin      | `notional × initialMarginRatio / 10_000`     | Opening / increasing a position |
| Maintenance margin  | `notional × maintenanceMarginRatio / 10_000` | Every mark / oracle update      |
| Health              | `freeCollateral + unrealizedPnL - maintReq`  | On liquidation check            |
| Liquidation trigger | `health ≤ 0`                                 |                                 |

With a 10% initial and 5% maintenance ratio, a 1 SOL long at $130 needs $13 to open
and stays safe until health reaches 0 (roughly $116.5 with $20 collateral).

## Mark price

Mark price is derived from the last trade, clamped to the oracle within ±10%. This
prevents a single manipulated fill from cascading through liquidations.

```rust theme={null}
// Pseudocode
mark = clamp(last_trade_price, oracle * 0.9, oracle * 1.1)
```

## What a trade touches

<Steps>
  <Step title="Oracle post (prepended instruction)">
    Off-chain you fetch a signed update from Hermes and post it via
    `@pythnetwork/pyth-solana-receiver`. This creates a `PriceUpdateV2` account
    usable for one tx.
  </Step>

  <Step title="Reserve margin + match">
    `place_order` locks `notional × initialMargin` out of free collateral and then
    walks the book up to 4 fills, emitting `OrderFilled` events and adjusting both
    sides' positions.
  </Step>

  <Step title="Settle funding (lazy)">
    The taker's funding is settled in-line with the trade. Resting makers settle
    on their next interaction, or when a keeper calls `settle_funding`.
  </Step>
</Steps>

## Fees

| Fee         | Default                    | Sink                                         |
| ----------- | -------------------------- | -------------------------------------------- |
| Taker       | 10 bps                     | `fee_vault`                                  |
| Maker       | 5 bps                      | `fee_vault`                                  |
| Liquidation | 500 bps of notional closed | split 50/50 between liquidator and insurance |

## Read next

<CardGroup cols={2}>
  <Card title="Funding rate" icon="arrows-rotate" href="/concepts/funding-rate">
    The Drift-style dynamic funding formula Kimia uses.
  </Card>

  <Card title="Oracles" icon="satellite-dish" href="/concepts/oracles">
    How Pyth Hermes Pull Oracles are validated.
  </Card>

  <Card title="kimia-perp reference" icon="book" href="/programs/kimia-perp">
    Full list of instructions, accounts, and error codes.
  </Card>

  <Card title="Trade a perpetual" icon="chart-candlestick" href="/guides/trade-perpetual">
    End-to-end walkthrough.
  </Card>
</CardGroup>