This is the trader’s walkthrough. If you want the code-level view, see
trade a perpetual.
1. Connect your wallet
Open the Kimia app, click Connect Wallet, and pick
your wallet. Approve the connection. The cluster dropdown should read devnet.
2. Deposit collateral
Your perp positions draw from a UserAccount, a PDA that holds your USDC
collateral. The first time you trade, the app creates this account for you and
prompts a deposit in the same transaction.
- Minimum deposit: $10 USDC (prevents rent-rounding issues)
- Max leverage: 10× (initial margin ratio 10%)
- Maintenance margin: 5% (liquidation trigger)
Deposits are instant and non-custodial. Your USDC sits in a market-scoped vault
authored by the kimia-perp program; only your wallet (or your chosen
delegate) can withdraw it.
3. Pick a direction and size
The trade panel exposes four fields:
| Field | What it means |
|---|
| Side | Long (profits if SOL rises) or Short (profits if SOL falls) |
| Size | Notional SOL to trade, in 9-decimal precision |
| Order type | Market (fills immediately) or Limit (rests on the book) |
| Max slippage | Taker-only; reverts the tx if fills exceed your tolerance |
size × price × initialMarginRatio. Free
collateral shrinks as resting orders reserve margin upfront.
4. Submit the order
Market orders consume up to four resting counterparties per tx. If not all of
your order fills, the remainder is either:
- Cancelled (if you set Post-Only = false and Market = true), or
- Rested on the book at your limit price (otherwise)
5. Monitor the position
The Positions table shows:
- Entry price, weighted average across all your fills
- Mark price, the clamped-to-oracle price used for PnL and margin
- Unrealized PnL, live
- Liquidation price, derived from your collateral + position size
Liquidation price moves when:
- You deposit / withdraw collateral
- Funding settles (moves your collateral silently)
- You increase or decrease the position
6. Close the position
Click Close, or place a market order in the opposite direction of equal
size. Realized PnL flows back into your UserAccount.collateral, then you can
withdraw it to your wallet whenever you want.
Withdrawals must leave enough collateral to satisfy initial margin, not
just maintenance. This prevents opening a position and instantly pulling out
collateral that the margin check was relying on.
Common errors and what they mean
| Toast | Cause | Fix |
|---|
StaleOracle | Oracle update wasn’t posted or is > 60 s old | Refresh, retry; a new oracle update is prepended automatically |
InsufficientFreeCollateral | Resting orders or the new position would exceed your free margin | Cancel open orders or deposit more USDC |
SlippageExceeded | Market order moved too far before filling | Raise max_slippage_bps or reduce size |
OrderbookFull | 32/32 asks or bids, rare | Wait for cancellations or fill takers |
