Position modes and margin accounts
Choose v24 isolated or Cross risk and authorize account actions.
Position modes
| Mode | Position grouping | Risk holder |
|---|---|---|
| Separate | A new independent position | Individual position |
| Full | Explicitly guarded same-direction merge or new bucket | Individual position |
| CrossSeparate | Independent position in a margin account | Account |
| CrossFull | Explicitly guarded same-direction account bucket | Account |
For Full modes, NEW_ONLY requires an empty bucket. REQUIRE_EXACT_MERGE requires the expected position ID and bucket key. Position-count, collateral, exposure, and leverage limits come from current configuration; do not assume the old v22 fixed bucket range.
Margin accounts
PvpMarginAccountV24 is a user-owned contract for supported pools sharing one collateral token. Use the matching account factory and registry. Pool, account, Router, schema, and deployment identity must be compatible.
Deposit collateral to create a backed free balance. Merely transferring tokens to the address is not the same accounting operation; syncExcessCollateral reconciles eligible excess. Open and close through supported account routes so positions, proceeds, fees, and debt coverage remain correctly attributed.
Risk ownership and account equity
Position grouping and risk ownership are separate choices. The arrows below show relationships and accounting, not automatic transfers between pools.
Cross aggregation requires supported compatible pools with the same collateral token; it does not merge their backing. Complete reads, backed custody and no Recovery pool are prerequisites for ordinary health evaluation.
Equity and margin
Account equity starts with backed free collateral and adds canonical signed contributions from each pool. Requirements group exposure by risk profile, including configured concentration adjustments. Health is not a sum of independently refreshed position display values.
New risk and withdrawals require a complete, custody-backed account meeting initial margin. A normally evaluable account becomes liquidatable strictly below maintenance margin. Liquidation targets the configured target requirement, which is above maintenance and no greater than initial margin.
Incomplete reads, a custody deficit, and a Recovery pool are distinct health states. They do not prove normal liquidation eligibility. The dedicated degraded path can reduce a readable target under its own guards without declaring the rest of the account healthy.
LP lots and deferred claims have separate tracking. Do not add their display values to free collateral or promise they are immediately withdrawable margin. Pool escrow must be claimed into the account through claimPoolEscrowToAccount before becoming account collateral.
Liquidation sessions and rescue
Anyone can invoke the supported liquidateNext, liquidatePositions, or liquidateToTarget paths when their conditions hold. Page guards bind the account state, target set, execution price, and bounty budget. A page stopping or making partial progress does not itself mean the account is healthy.
Liquidation sessions block withdrawals and new risk. Deposits and supported risk-reducing or recovery operations have separate gates. Rescue contributions are tracked to protect them from inappropriate bounty attribution; protection is resolved using the account's current health and rescue state, not by assuming every deposit instantly ends liquidation.
Router approval
Token allowances and account Router trust are separate. proposeAccountRouterV24 accepts the required owner authorization, including a relayed owner signature. activateAccountRouterV24 checks the activation window, Router identity, and authority binding. Owners can cancel a pending proposal. The old setRouterApproval interface is not the v24 flow.
Trading agents
The owner calls setTradingAgentV24 with an allowed-pool list, action permissions, expiry, nonce, and limits on notional, leverage, protocol fees, keeper fees, collateral spending, and daily volume. Revoke through revokeTradingAgentV24 using the current authorization nonce.
Agents can perform only the authorized trading actions. They cannot withdraw custody, change Router trust, or manage agents. Their permitted trades can still lose collateral or incur fees, so use limited balances, short expiries, and narrow pool lists.
For agent-signed orders, a nonzero keeper fee is bounded by maxKeeperFee and is paid from the signing maker's wallet, not by an unrestricted account withdrawal. The matching token allowance is still required.