Math helpers

liquidationPrice(), pnl() and rolloverFee() are standalone functions over plain numbers — no client, no network. For bots, backtesters and risk dashboards. All three run @ostium/formulae, the same math the contracts use.

import {
  liquidationPrice, pnl, rolloverFee, maxWithdrawable, maxAddCollateral,
} from '@ostium/builder-sdk';

liquidationPrice

liquidationPrice({
  entryPx: 100_000,
  isLong: true,
  collateral: 1000,
  leverage: 10,
  maxLeverage: 100,
});  // → 90_250

Parameter	Type	Default	Description
`entryPx`	`number`	—	Price the position opened at.
`isLong`	`boolean`	—	Direction.
`collateral`	`number`	—	Collateral backing the position, in USDC.
`leverage`	`number`	—	Position leverage.
`maxLeverage`	`number`	—	Max leverage allowed for the pair — this sets the maintenance margin.
`rollover`	`number`	`0`	Rollover accrued so far, in USDC.
`funding`	`number`	`0`	Funding accrued so far, in USDC.

Accrued fees push the liquidation price toward the entry price, so a long-held position liquidates sooner than it did at open. Pass rollover for the current figure.

pnl

pnl({ entryPx: 100_000, markPx: 105_000, isLong: true, collateral: 1000, leverage: 10 });
// → { netPnl: 500, netPnlPercent: 50, netValue: 1500 }

Parameter	Type	Default	Description
`entryPx`	`number`	—	Price the position opened at.
`markPx`	`number`	—	Current mark price.
`isLong`	`boolean`	—	Direction.
`collateral`	`number`	—	Collateral backing the position, in USDC.
`leverage`	`number`	—	Position leverage.
`highestLeverage`	`number`	`leverage`	Highest leverage the position has ever run at. Only differs after collateral has been added or removed.
`rollover`	`number`	`0`	Rollover accrued, in USDC.
`funding`	`number`	`0`	Funding accrued, in USDC.

Returns netPnl (USDC, after rollover and funding), netPnlPercent (as a percentage of collateral) and netValue (collateral + netPnl — what the position is worth if closed now).

rolloverFee

const { pairs } = await client.getPairs();
const { pairPositions } = await client.getOpenPositions({ user });
const { position } = pairPositions[0];
const pair = pairs.find(p => p.pairId === position.pairId)!;

const accrued = rolloverFee({
  rollover: pair.rollover,
  isLong: position.side === 'B',
  snapshot: position.rolloverSnapshot,
  collateral: Number(position.collateralUsed),
  leverage: Number(position.leverage),
  blockNumber: await publicClient.getBlockNumber(),   // your own viem client
});

const liq = liquidationPrice({
  entryPx: Number(position.entryPx),
  isLong: position.side === 'B',
  collateral: Number(position.collateralUsed),
  leverage: Number(position.leverage),
  maxLeverage: Number(position.maxLeverage),
  rollover: accrued,
});

Parameter	Type	Description
`rollover`	`PairRollover`	The pair’s raw accumulators, from `Pair.rollover`.
`isLong`	`boolean`	`true` for a long position.
`snapshot`	`string`	The position’s `rolloverSnapshot` — the accumulator when it opened.
`collateral`	`number`	Collateral backing the position, in USDC.
`leverage`	`number`	Position leverage.
`blockNumber`	`bigint \| number \| string`	Current chain block. Rollover accrues per block, so this sets the clock.

Positive means the trader pays. Rollover accumulators are global per pair, not per position, so one getPairs() poll plus a block number lets you keep liquidation price and PnL current for any number of positions locally — no per-position read, and no re-fetching positions. createStore() does this for you.

maxWithdrawable / maxAddCollateral

The two collateral-edit limits, for a ticket that has to bound its own input.

maxWithdrawable({
  collateral: 1000, leverage: 10, maxLeverage: 100, notional: 10_000,
  entryPx: 100_000, exitPx: 100_000, isLong: true, pnl: -300,
});  // → 675

maxAddCollateral({ collateral: 1000, leverage: 10, minLeverage: 2 });  // → 4000

Removing collateral raises leverage, so it is bounded by three limits at once and maxWithdrawable returns the smallest: the leverage cap, liquidation safety (accrued fees and unrealised loss), and profit protection. The leverage cap alone overstates the answer on a losing position — 900 in the example above. Adding collateral lowers leverage, so that direction is bounded by the pair group’s minimum, Pair.minLeverage. Position.maxWithdrawable is this number, already computed for an open position.

SDK

Client Modes

Helpers

Previews & Limits

Read Methods

Live State

Write Methods

Builder API

Builder

Trader

Legacy

liquidationPrice

pnl

rolloverFee

maxWithdrawable / maxAddCollateral

​liquidationPrice

​pnl

​rolloverFee

​maxWithdrawable / maxAddCollateral

​Related

liquidationPrice

pnl

rolloverFee

maxWithdrawable / maxAddCollateral

Related