> ## 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. # kimia-perp > Perpetual futures matching engine, orderbook, funding, liquidation, spot pool. `kimia-perp` is the core derivatives program. It owns the orderbook, tracks all positions and funding, validates Pyth Hermes oracle posts, and runs the spot pool that delta-vault hedges against. ## Accounts ### ExchangeConfig Singleton. `["exchange_config"]`. | Field | Type | Notes | | ----------------- | -------- | ------------------------ | | `admin` | `Pubkey` | Current admin | | `pending_admin` | `Pubkey` | Two-step transfer target | | `exchange_paused` | `bool` | Global pause | | `bump` | `u8` | | ### Market One per market. `["market", market_index_le]`. | Field | Type | Notes | | ------------------------------------------------------- | -------------- | ----------------------------------------------- | | `admin` | `Pubkey` | | | `market_index` | `u16` | 0 = SOL-PERP (V1) | | `status` | `MarketStatus` | `Initialized`, `Active`, `Paused`, `Settlement` | | `oracle` | `Pubkey` | Pyth `PriceUpdateV2` feed account | | `oracle_staleness_threshold` | `i64` | seconds | | `oracle_confidence_max_bps` | `u16` | bps | | `initial_margin_ratio` | `u32` | bps of MARGIN\_PRECISION (10k) | | `maintenance_margin_ratio` | `u32` | bps | | `taker_fee_bps`, `maker_fee_bps`, `liquidation_fee_bps` | `u16` | | | `funding_period` | `i64` | default 3600s | | `last_funding_update` | `i64` | | | `cumulative_funding_rate_long` | `i128` | | | `cumulative_funding_rate_short` | `i128` | | | `mark_twap`, `oracle_twap` | `u64` | 6-decimal | | `total_long_base`, `total_short_base`, `open_interest` | `u64` | 9-decimal | | `collateral_vault`, `insurance_vault`, `fee_vault` | `Pubkey` | SPL token accounts | | `collateral_mint` | `Pubkey` | USDC mint | | `insurance_fund_balance`, `total_fees_collected` | `u64` | | | `tick_size` | `u64` | orderbook price increment | ### UserAccount `["user", authority]`. | Field | Type | Notes | | ---------------------------------------------------------- | -------- | ------------------------------------------- | | `authority` | `Pubkey` | Owner | | `delegate` | `Pubkey` | Optional trading delegate (cannot withdraw) | | `collateral` | `u64` | USDC, 6-decimal | | `market_index` | `u16` | | | `base_amount` | `i64` | signed, 9-decimal | | `quote_entry` | `i64` | 6-decimal | | `last_cumulative_funding_rate` | `i128` | for lazy settlement | | `realized_pnl`, `total_fees_paid`, `total_reserved_margin` | | | ### Orderbook Zero-copy. `["orderbook", market_index_le]`. * Max 32 bids (sorted descending) and 32 asks (sorted ascending). * FIFO within price. * `Order { owner, order_id, price, base_remaining, reserved_margin, direction, is_active }`. ### SpotPool `["spot_pool", base_mint, quote_mint]`. Simple oracle-priced wSOL/USDC pool used by `delta-vault`. Swaps at oracle ± `spread_bps`; no curve. ## Instructions | Instruction | Who | Purpose | | ----------------------------------------- | ------------------ | ------------------------------------------------------------- | | `initialize_exchange` | first admin | One-time setup | | `propose_admin` / `accept_admin` | admin / new\_admin | Two-step transfer | | `initialize_market` | admin | Create market and its vaults | | `update_market_params` | admin | Adjust fees, margin, oracle thresholds (not oracle account) | | `pause_market` / `resume_market` | admin | Lifecycle | | `set_delegate` | user | Allow a vault / keeper to trade on user's behalf | | `initialize_user_account` | user | Create position account | | `deposit_collateral` | user or delegate | Add USDC | | `withdraw_collateral` | user only | Remove USDC, checks margin post-op | | `initialize_orderbook` | admin | Empty book | | `place_order` | user or delegate | Reserve margin → match (up to 4 fills) → insert resting order | | `cancel_order` / `cancel_all_orders` | user or delegate | Remove, refund margin | | `update_funding_rate` | **anyone** | Keeper crank; TWAPs + funding delta | | `settle_funding` | **anyone** | Lazy settlement for a user | | `liquidate` | **anyone** | Close an underwater position, cancel orders, split fee | | `initialize_spot_pool` / `seed_spot_pool` | admin | Set up wSOL/USDC pool | | `spot_swap` | anyone | Oracle-priced swap (± spread) | ## place\_order `PlaceOrderParams { price, base_amount, direction, post_only, is_market, max_slippage_bps }`. 1. Validate oracle and clamp mark price to oracle ± 10%. 2. Reserve `notional × initial_margin_ratio` out of `free_collateral()`. 3. If `is_market`, walk the book up to 4 fills: * skip self-trades * apply taker fee (to `fee_vault`) * adjust both counterparties' `base_amount` and `quote_entry` * emit `OrderFilled` 4. Any remainder becomes a resting order (if not `post_only` and not market). ## liquidate 1. Validate oracle. 2. `health ≤ 0` check (`NotLiquidatable` otherwise). 3. Cancel all resting orders, their reserved margin goes to `insurance_vault`. 4. Close the full position at oracle price. 5. Charge 5% liquidation fee: 2.5% to liquidator, 2.5% to insurance. 6. If collateral insufficient, drain insurance fund. If still insufficient, emit `BadDebtDetected` and pause the market. ## Events `MarketInitialized`, `PositionOpened`, `PositionClosed`, `FundingRateUpdated`, `FundingSettled`, `CollateralDeposited`, `CollateralWithdrawn`, `Liquidated`, `OrderPlaced`, `OrderFilled`, `OrderCancelled`, `MarkPriceUpdated`, `SelfTradeSkipped`, `BadDebtDetected`, `SpotPoolInitialized`, `SpotSwapped`. ## Error codes See [errors reference](/resources/errors). The main buckets: `6000..6002` oracle, `6010..6012` market, `6020..6022` margin, `6030..6033` position, `6040..6041` funding, `6050..6051` liquidation, `6110..6117` orderbook. ## Read next Formula, clamp, and settlement. Walkthrough.