Perps leverage

These helpers contain the reusable product math behind a USDC input and leverage control. All amounts are bigint values. They do not format strings, access a wallet, or call RPC.

Import

import {
  getLongLeverageBounds,
  getPerpLeverageBounds,
  getShortLeverageBounds,
  quoteLongByLeverage,
  quotePerpByLeverage,
  quoteShortByLeverage,
} from "@repo/contract-client/math";

Long bounds and quote

const account = await sv3.market.getAccountContext(market, owner);
const contribution = parseUsdc("100");
const bounds = getLongLeverageBounds(account, contribution);

const quote = quoteLongByLeverage(account, {
  userContributionRaw: contribution,
  leverageBps: 20_000n,
});

getLongLeverageBounds searches the complete 1×–3.3× product range against the actual expansion quote. It includes the post-buy collateral capacity, liquid reserve, market/protocol debt headroom, and market/protocol gross-backing headroom.

LongLeverageQuote includes:

Field	Meaning
`userContributionRaw`	USDC supplied by the user
`positionSizeRaw`	User USDC plus net debt used for the curve purchase
`avmAcquired`	Physical AVM minted and pledged
`grossDebtIncreaseRaw`	Debt recorded by FloorMarket
`netDebtProceedsRaw`	Debt contribution after the 3% origination fee
`tradeFees` / `borrowFees`	Separate fee breakdowns
`averageEntryPriceWad`	Fee-inclusive average entry for this increase
`grossBackingIncreaseRaw`	Net increase checked against Directory caps
`floorEquityRaw`	Floor value of the resulting collateral minus resulting debt
`priceImpact` / `provenance`	Curve impact and pinned-state identity

Short bounds and quote

const perp = await sv3.perp.getContext(market);
const margin = parseUsdc("100");
const bounds = getShortLeverageBounds(perp, margin);

const quote = quoteShortByLeverage(perp, {
  marginRaw: margin,
  leverageBps: 20_000n,
});

PerpMarketContext is required because a safe short quote needs more than the FloorMarket curve snapshot. It includes live fee and margin policies, active and surrendered offset, per-position and aggregate caps, market/protocol escrow totals, and Directory backing headroom.

ShortLeverageQuote includes:

Field	Meaning
`marginRaw`	Isolated USDC margin
`positionSizeRaw`	Conservative premium restoration exposure
`sizeAvm`	Exact offset size sent to the contract
`releasedPremiumRaw`	Position escrow released from FloorMarket
`openFeeRaw`	0.125% fee on released premium
`totalWalletDebitRaw`	Margin plus open fee
`entryPremiumWad`	Released premium per AVM
`initialMarginRequiredRaw`	IMR requirement at entry
`maintenanceMarginRequiredRaw`	MMR requirement at entry
`liquidationBufferRaw`	Buffer included in health
`equityRaw` / `flaggable`	Entry health under current policies

Generic helpers

Use getPerpLeverageBounds and quotePerpByLeverage when the side is selected at runtime. Their input and result are discriminated by side.

Constraint codes

bounds.limitingConstraint is one of:

product-cap
floor-capacity
liquid-reserve
debt-cap
gross-backing-cap
position-size-cap
market-offset-cap
market-share-cap
market-escrow-cap
protocol-escrow-cap
minimum-curve-supply

Do not infer a limit from an error string. Display the returned maximum and map this stable code into consumer-specific copy. If a quote requests more than that maximum, the SDK throws LeverageLimitError with the same side, maxLeverageBps, and limitingConstraint fields.

Legacy exact-size helpers

quoteOpenShort and quoteOpenShortByLeverage(snapshot, ...) remain available for low-level calculations and compatibility. A MarketSnapshot alone cannot know aggregate perp escrow or offset headroom. New trading integrations should use quoteShortByLeverage(PerpMarketContext, ...).