Open and close price positions
Use v24 guarded opens, partial closes, settlement, and collateral adjustments.
Before opening
Use the deployment's v24 Router and a fresh quote from the matching Lens Set. Verify direction, collateral, leverage, mode, oracle price band, protocol fee, and the maximum position bounty bond you authorize. Open admission checks the pool's current and stressed risk and the resulting position margin.
For Separate modes an open creates a new position. Full modes explicitly choose a new bucket or require the exact existing merge target and bucket key. A changed merge target must not silently replace the one you approved.
From request to position
An open executes only after all admission checks pass. A failed check reverts the request.
Close all or part
Use closeAllV24 to close an entire position. closePartialV24 accepts requestedBps from 1 through 9,999. Dust rules can promote a partial request to full closure only when allowFullClosePromotion permits it; otherwise it reverts. Inspect effectiveBps and promotedToFull in the result.
A close removes exposure at the valid oracle price and settles the actual signed mass removed from the pool:
- Positive mass: converts to collateral after fees when the risk checks allow immediate settlement.
- Negative mass: creates debt. Settlement uses authorized debtor coverage first, then Safety Reserve; any remainder is uncovered loss.
- Deferred exit: when immediate positive settlement would leave insufficient mass,
allowDeferredExitcan permit conversion into a deferred mass claim instead of cash.minDeferredMassprotects that claim. This does not guarantee when or how much collateral you can later claim.
minOwnerPayout protects the ordinary collateral-payout branch; it does not substitute for minDeferredMass in a deferred exit. If you require cash, do not authorize deferred exit.
What a close delivers
This diagram shows ordinary settlement branches, not guaranteed payouts. Each branch retains its phase, oracle, fee and user guards. Zero-mass settlement is omitted; Recovery uses separate paths.
Deferred claims have no fixed payment date or collateral value. minDeferredMass protects the mass claim; minOwnerPayout protects the ordinary payout. Position bounty bonds are separate from these proceeds.
Direct payment and settlement escrow
For an ordinary direct payout, payoutMode = DIRECT requires a nonzero receiver. For ESCROW, the receiver field must be zero: the contract reserves the owner's settlement balance for a later claimSettlement or claimSettlementAll request. Claim requests have their own amount, receiver, deadline, and state guards.
Margin-account proceeds must follow the account's supported custody route. An escrow amount does not become spendable account collateral until it is claimed into the account. Deferred position claims are a separate mass entitlement, not settlement escrow.
Execution protection
Use fresh accounting and other action-specific digests, a deadline, price bounds, and maxProtocolFee. Set maxDebt, maxDebtorCoverage, maxSafetyUsed, and maxUncoveredDebt deliberately. These upper limits reject an unacceptable result; zero does not mean unlimited. Price bounds are literal comparisons: a zero maxPrice does not disable the upper bound.
maxTerminalFundingDust limits the raw-collateral equivalent of a terminal funding remainder, subject to the stricter protocol profile cap. A stale quote, changed price, or insufficient allowance can still make the transaction revert.
Add collateral or reduce leverage
addPositionCollateralV24 adds collateral to an existing position and accepts minimum added shares and fee/state guards. It does not withdraw money. reduceLeverageV24 reduces a slice of exposure and retains the resulting collateral in the position, with minCollateralKept protection. It is not a wallet payout.
Both actions remain subject to their phase, oracle, authorization, and risk checks. Depositing free collateral to a margin account is different from allocating it to a position.
Market restrictions
Reduce-only blocks new positions. During EmergencyPause, the native ordinary close path permits a full close to escrow, subject to the remaining checks; an ordinary partial close cannot bypass the pause through dust promotion. Recovery uses dedicated repair and settlement paths instead of normal opens and closes.
A position bounty bond is separate custody from trading collateral. A healthy, positive, non-deferred voluntary full close refunds it; terminal negative, zero, or deferred closures do not promise the same refund. See Liquidation.