@somnia-chain/markets-sdk

@somnia-chain/markets-sdk / index / PerpOrderMarginQuote

Interface: PerpOrderMarginQuote

Defined in: packages/sdk/src/perp/margin.ts:1700

The placement gates and the lock they are measured against.

Properties

increasingQuantity

increasingQuantity: bigint

Defined in: packages/sdk/src/perp/margin.ts:1702

The part of the order that increases the position — the only part that locks.

reducingQuantity

reducingQuantity: bigint

Defined in: packages/sdk/src/perp/margin.ts:1704

The part absorbed by existing exposure. Locks nothing.

lockAmount

lockAmount: bigint

Defined in: packages/sdk/src/perp/margin.ts:1706

Total collateral the pool will lock.

initialMarginPortion

initialMarginPortion: bigint

Defined in: packages/sdk/src/perp/margin.ts:1708

The initial-margin component of lockAmount.

adverseGapPortion

adverseGapPortion: bigint

Defined in: packages/sdk/src/perp/margin.ts:1710

The adverse mark-to-entry component, zero on a favourable entry.

leverageSurcharge

leverageSurcharge: bigint

Defined in: packages/sdk/src/perp/margin.ts:1712

Extra margin a leverage cap stricter than the market's IMF demands.

feeHeadroom

feeHeadroom: bigint

Defined in: packages/sdk/src/perp/margin.ts:1730

The pool's worst-case fee reserve for this order (PerpPool._feeHeadroom).

Not part of lockAmount and not charged — perps locks only initial margin and takes fees from the unlocked balance at fill. It exists solely as an auto-pull addend, so that pulling exactly the lock cannot leave a max-leverage open at equity = IM − fees against an IM requirement, i.e. in MarginCall at birth.

The rate is an envelope, not a prediction: an order rests as a maker or crosses as a taker but never both, so it takes the larger of the two — with a negative (rebate) maker rate floored at zero first, since a rebate must not shrink the reserve below the taker case — plus the order's builder fee. Ceil-rounded, on the full order notional rather than the increasing leg, because fees are charged on the whole fill.

Reported whatever topUpRequired does, but it only enters the arithmetic when auto-pull is modelled.

topUpRequired

topUpRequired: bigint

Defined in: packages/sdk/src/perp/margin.ts:1747

What auto-pull would take from the owner's wallet (MarginBank.quoteOrderTopUp) — 0n when PerpOrderMarginQuoteInputs.wallet is omitted, i.e. when auto-pull is not being modelled at all.

lockAmount + feeHeadroom + leverageSurcharge less the unlocked balance, floored at zero. Order-local by design: it excludes the initial margin of the account's positions in other markets, so it is exactly sufficient for a FLAT account and best-effort for one already carrying exposure — a pre-existing cross-market deficit still fails meetsInitialMargin. Auto-pull funds an ORDER, not an ACCOUNT.

A 0n is three different things, which is why it should be read beside the balance rather than alone: no pull needed, or one of the pool's three declines — a purely reducing order (closing never debits a wallet), an account already in debt (a pull would silently cure bad debt), or a voucher-blocked increase.

walletCoversTopUp

walletCoversTopUp: boolean

Defined in: packages/sdk/src/perp/margin.ts:1756

The wallet can fund topUpRequired — both balance and allowance.

Vacuously true when no pull is needed or auto-pull is not modelled. false means the transferFrom inside depositFor reverts, so the placement fails on the TOKEN's error rather than on any margin gate — which is deliberate on the pool's side, because that error names the fix.

hasCollateralForLock

hasCollateralForLock: boolean

Defined in: packages/sdk/src/perp/margin.ts:1764

Gate 1 — the unlocked balance covers the lock, after any auto-pull.

With PerpOrderMarginQuoteInputs.wallet supplied this is the real post-pull gate. Without it, the in-bank balance alone — conservative rather than wrong on the self-send path, since the pool tops up before lockCollateral runs.

meetsInitialMargin

meetsInitialMargin: boolean

Defined in: packages/sdk/src/perp/margin.ts:1778

Gate 2 — post-lock equity still meets the initial-margin requirement, after any auto-pull (the top-up lands in the unlocked balance that seeds equity).

Note this is NOT monotone in quantity once auto-pull is modelled, and the reason is worth knowing: in the pulled regime the surcharge cancels from both sides and the gate reduces to (equity − unlocked) + feeHeadroom ≥ imRequirement, whose only quantity-dependent term GROWS. An account whose existing positions sit below their own initial margin can therefore be rejected at a middling size and accepted at a far larger one, whose headroom over-pulls enough to cover the deficit. client.getMaxPerpOrderSize deliberately does not offer sizes from that disconnected upper region.

voucherBlocked

voucherBlocked: boolean

Defined in: packages/sdk/src/perp/margin.ts:1780

The order would revert on the voucher allowlist / unset-cap guard.

restrictedBlocked

restrictedBlocked: boolean

Defined in: packages/sdk/src/perp/margin.ts:1785

The market is close-only and this order has an increasing leg, so placement reverts MarketRestricted. Never blocks a pure reduce.

isolationBlocked

isolationBlocked: boolean

Defined in: packages/sdk/src/perp/margin.ts:1791

The account is in isolated margin with a footprint in a DIFFERENT market, so placement reverts IsolatedMarketBlocked. Unlike every other gate here this blocks the reducing legs too — it is about which market may be traded, not about margin.

sufficient

sufficient: boolean

Defined in: packages/sdk/src/perp/margin.ts:1793

Every gate passes.