Perps engine

Units

Immediate markets

isImmediate(feedId) is true when the feed's policy prices every round. On such a market, open(OpenArgs) fills in the same transaction at the latest round plus spreadBps, if the round is at most 2 seconds old. The margin is pulled from accountOf(msg.sender); the open fee (FEE_BPS, 0.05% of margin x leverage) is taken from it; 70% of the fee goes to the vault. A non-zero tp or sl is set on the orders book in the same call. close(id) closes in full, by the trader or any live key of theirs. Calling open on a two-step market reverts "two-step".

Two-step markets

requestOpen(OpenRequest) escrows the margin and records roundAtRequest. A keeper calls execute(id) once a newer round exists and fills at that round with no spread, or cancels with a reason: past acceptablePrice (long fills at or below it, short at or above; 0 is no bound), market closed, rejected by the engine. requestClose(positionId, acceptablePrice) works the same way. The trader can cancel after TRADER_CANCEL_AFTER (30 seconds), or at once while the market is not open; after EXPIRE_AFTER (120 seconds) the request can no longer fill and anyone may cancel it. Every refund goes to the trader's bank balance. Request ids share the engine's idBase.

Triggers

setTriggers(positionId, tp, sl, limitPrice) sets take profit, stop loss and a limit close on your position, on any market; zero clears a field. Long: TP and limit fire at or above, SL at or below; short mirrored. The keeper's executeTrigger fills only at a round newer than the one the triggers were set at, and refuses a liquidatable position. On a closed market, triggers wait for the reopening.

Liquidation

liquidate(id) is permissionless. It needs a fresh price and equity below maintenance, where equity is margin + PnL - funding - the full close fee, and maintenance is ceil(value / (2 x maxLeverage)) of the position's current value. It closes at the oracle price with no spread; the penalty is LIQ_PENALTY_BPS (1%) of the value, capped by what is left, half to the caller in pUSD and half to the protocol; the rest goes to the trader's bank balance. Below zero is bad debt, which the vault absorbs. Read isLiquidatable(id) or positionState(id); /api/perp/open pages through every open position with the market state you need to check it off chain.

Closed markets

When the oracle feed's status is closed (2), the publisher keeps the session's last price standing. Opens are refused ("market closed"). A close, or a requestClose (which the keeper fills at once), goes through at that last price less closedSpreadBps(feedId), plus the market's own spread on an immediate market. The closed spread is set per market by the owner, DEFAULT_CLOSED_SPREAD_BPS (10) at listing, at most MAX_CLOSED_SPREAD_BPS (100). The last price must be at most CLOSED_HEARTBEAT + 30 seconds old (or the feed's own heartbeat if longer), and a position below maintenance at that price does not close ("liquidatable"). Funding is paused; TP, SL, limits and liquidations wait for the first round after the reopening. Status 0 (unknown) and 3 (halted) freeze the market both ways.

idBase and the previous engine

idBase() is fixed at construction: 10,000,000 on the current engine, so its first position is 10,000,001. The previous engine, listed in the manifest's perpsPrevious with version: 1, numbers from 1, takes margin from the wallet's own pUSD and pays the wallet; it predates the bank, so a key cannot act on it. Its positions are closed with its own close(id), signed by the wallet that opened them.

PepperPerps

PepperPerpOrders

PepperPerpVault