Margin & Liquidation
GoDark supports isolated and cross margin, selected per symbol on one collateral wallet. The sequencer evaluates four risk bands and, at the liquidation boundary, performs one full-leg vault takeover. There is no 10% / 30% / 60% partial-liquidation ladder.
This page describes how margin requirements, health tiers, and liquidation work. For fee tiers (Core → Apex), see VIP Tiers — those are unrelated to margin health.
Margin Modes
| Concept | Description |
|---|---|
| Initial margin (IM) | Collateral locked when a position opens: ⌈size × price / leverage⌉ |
| Extra margin | Optional additional collateral added to a position |
| Equity | IM + extra margin + unrealized PnL |
| Maintenance margin | Minimum equity required to keep the position open: size × mark × maintenance_rate |
| Margin ratio | equity / maintenance_margin — values at or below 100% trigger liquidation |
In isolated mode, loss is contained to the symbol's margin silo. In cross mode, positions share cross equity while isolated locks remain protected. Mode is per symbol and defaults to isolated. Switching requires that symbol to be flat with no resting orders; adjusting margin is isolated-only.
Default platform rates (overridable per instrument via GET /instruments):
| Rate | Default | Meaning |
|---|---|---|
| Maintenance margin | 500 bps (5%) | Minimum equity as a fraction of notional at mark |
| Warning margin | 1,000 bps (10%) | Early warning band (internal classification) |
Per-instrument fields initial_margin_ratio and maintenance_margin_ratio on GET /instruments are authoritative for each market.
Pre-Trade Risk Checks
Every order is risk-checked before it enters the book. A successful POST /orders response means all checks passed — not that the order has filled.
Checks include margin, position limits, liquidation lockout, and max leverage. Resting orders also reserve margin so free_collateral reflects working liquidity. Rejects use the trade ACK catalog — see Error Codes and Place Order — Pre-Trade Risk Validation.
Pre-trade checks fail closed on stale or missing oracle prices — orders are rejected rather than accepted without a valid mark.
Margin Health Bands
The monitor classifies risk using margin ratio (equity ÷ maintenance requirement, where 10,000 bps = 100%).
| Tier | Margin ratio | User-visible action |
|---|---|---|
| Healthy | > 150% | No action |
| Warning | > 120% to 150% | Margin warning |
| Critical | > 100% to 120% | Critical alert; same-side orders may be cancelled |
| Liquidation | ≤ 100% | Cancel resting orders, then full remaining leg takeover |
The web trading UI mirrors these bands in the margin health bar and tier banners. Tier names here are margin health tiers, not VIP fee tiers.
The takeover transfers the full remaining leg to the liquidation vault at bankruptcy pricing. It is deferred while resting-order cancellation is incomplete. Unrecoverable takeover failures can escalate to ADL.
Liquidation Process
End-to-end flow:
- Monitor tick — sequencer evaluates margin ratios for all open positions
- Band classification — healthy, warning, critical, or liquidation
- Alerts — margin alerts pushed to connected clients (web UI and programmatic subscribers)
- Order cancellation — resting orders are cancelled before takeover
- Full takeover — the remaining position leg transfers to the GoDark Liquidation Vault (GLV)
- Unwind — GLV inventory is unwound through internal market-making strategies
- On-chain settlement — collateral split settled on Solana (see Settlement and Collateral Vault)
On-chain liquidation settles collateral (ZK split from user remainder to GLV credit). Position sizing, tier logic, and tranche scheduling run off-chain in the sequencer.
Oracle mark prices (Pyth primary, Switchboard failover) drive PnL and liquidation math. Stale oracle data can delay or block pre-trade checks; the monitor uses the same mark feed for ongoing evaluation.
Liquidation Price
Each open position may expose liquidation_price: the mark where equity equals maintenance margin plus the taker fee charged to close.
Returned by encrypted POST /api/v1/positions snapshots and position subscriptions.
Approximate isolated formulas use maintenance rate MMR, liquidation taker fee F, and BPS = 10_000:
Long: liq = (size × entry − collateral) × BPS / (size × (BPS − MMR − F))
Short: liq = (collateral + size × entry) × BPS / (size × (BPS + MMR + F))
Higher leverage means less initial collateral for the same size, so liquidation price sits closer to entry.
Cross liquidation is account-level: cross_equity = collateral − isolated locks − isolated order holds + cross uPnL, compared with total cross maintenance requirement. The engine selects cross positions worst-margin-ratio first. Cross liquidation cannot consume isolated silos, and isolated liquidation cannot consume the cross pool.
ADL is an escalation path. No live insurance-fund or socialized-loss claim is made here because those product surfaces are not currently verified.
Programmatic Integration
Use an official SDK. Subscribe to position updates on GodarkClient and read the position object — do not scrape REST or raw WebSocket frames for this.
PositionUpdate (name varies slightly by language) is the shape you watch:
| Field | Why it matters |
|---|---|
symbol, side, size | What is open |
margin, leverage, mgn_mode | Allocated margin, leverage, and isolated/cross mode |
unrealized_pnl | Mark-to-market |
liquidation_price | Where this position would liquidate |
update_reason | Why the row changed (fill, mark_price, liquidation) |
Instrument limits you need for pre-trade checks live on the instrument object: initial_margin_ratio, maintenance_margin_ratio, max_leverage.
Order rejects: Error Codes.
Related
- Trade Flow — order lifecycle
- Positions — position snapshot API
- Settlement — batch settlement and oracle role
- VIP Tiers — fee tiers (distinct from margin health tiers)