Utilities

Calculation helpers, order classification, formatting, and validation utilities

The SDK exports utility functions for position math, TP/SL calculations, fee estimation, order classification, formatting, and validation. Most helpers are pure functions that do not call the API. The Numbers page describes the DecimalString contract and the naming of these helpers. Every formula takes and gives DecimalString values, throws PerpsError with ValidationError on a malformed or zero-divisor input, and has a safe* pair (for example safeCalculateRoe) that logs a warning and gives undefined in place of the throw. getGasRecommendation, the signing helpers, and the storage adapters perform network, crypto, or storage I/O.

​

Position Calculations

import {
  calculateSize,
  calculateNotionalValue,
  calculateUnrealizedPnl,
  calculateRoe,
  calculateRequiredMargin,
  calculateRealizedPnlPercent,
  calculateEffectiveLeverage,
  calculateLiquidationDistance,
} from '@lifi/perps-sdk';

​

calculateSize

Calculate position size from margin, leverage, and price.

import { calculateSize } from '@lifi/perps-sdk';

const size = calculateSize('1000', '10', '95000');
// '0.10526315789…' (asset units, e.g. BTC, for a $10k notional)

Parameter	Type	Description
marginUsd	DecimalString	Margin amount in USD
leverage	DecimalString	Leverage multiplier
price	DecimalString	Entry price. Throws when it is zero.

Returns: DecimalString, divided to 40 decimal places.

​

calculateNotionalValue

Notional value in USD: |size| * price.

import { calculateNotionalValue } from '@lifi/perps-sdk';

const notional = calculateNotionalValue('0.5', '96000'); // '48000'

​

calculateUnrealizedPnl

(currentPrice - entryPrice) * size. size is signed: positive for long, negative for short.

import { calculateUnrealizedPnl } from '@lifi/perps-sdk';

const pnl = calculateUnrealizedPnl('95000', '96000', '0.5'); // '500'

​

calculateRoe

Return on equity as a percentage ('10' means 10%): pnl / margin * 100. Throws when margin is zero.

import { calculateRoe } from '@lifi/perps-sdk';

const roe = calculateRoe('500', '1000'); // '50'

​

calculateRequiredMargin

notionalValue / leverage. Throws when leverage is zero.

import { calculateRequiredMargin } from '@lifi/perps-sdk';

const margin = calculateRequiredMargin('10000', '10'); // '1000'

​

calculateRealizedPnlPercent

Realised PnL as a percentage of the position value at close: realizedPnl / (|size| * price) * 100. Throws when size * price is zero.

import { calculateRealizedPnlPercent } from '@lifi/perps-sdk';

const pnlPercent = calculateRealizedPnlPercent('500', '0.5', '96000'); // '1.0416…'

​

calculateEffectiveLeverage

Effective leverage of an open position (positionValueUsd / marginUsd). Throws when marginUsd is zero. Takes a single params object.

import { calculateEffectiveLeverage } from '@lifi/perps-sdk';

calculateEffectiveLeverage({ positionValueUsd: '10000', marginUsd: '1000' }); // '10'

Parameter	Type	Description
positionValueUsd	DecimalString	Position notional value in USD
marginUsd	DecimalString	Margin backing the position in USD

​

calculateLiquidationDistance

Absolute distance from the current price to the liquidation price, as a percentage of the current price. Throws when the current price is zero.

import { calculateLiquidationDistance } from '@lifi/perps-sdk';

calculateLiquidationDistance({ liquidationPrice: '90000', currentPrice: '95000' }); // '5.2631…'

Parameter	Type	Description
liquidationPrice	DecimalString	The position’s liquidation price
currentPrice	DecimalString	Current market price

​

Margin adjustment capability

isPositionMarginAdjustable(position) is true when the position is isolated and its market’s positionMarginAdjustment is not NONE. isPositionMarginRemovable(position) is true when that field is ADD_AND_REMOVE; an ADD_ONLY market takes adds but no withdrawal.

To read how much margin can be withdrawn, call perps.getPositionRemovableMargin(position). It delegates to the position’s provider.

import { isPositionMarginAdjustable } from '@lifi/perps-sdk';
import type { Position } from '@lifi/perps-sdk';

function removableMargin(position: Position) {
  if (!isPositionMarginAdjustable(position)) return '0';
  return perps.getPositionRemovableMargin(position) ?? '0';
}

Returns: DecimalString | undefined. undefined for cross positions and markets without individual margin adjustment. '0' when the market is add-only or nothing is removable. Otherwise a decimal string rounded down to 6 decimal places. Throws PerpsError with ValidationError when a Position decimal the venue formula reads is malformed.

Each provider package also exports the same calculation as positionRemovableMargin(position):

Provider	Removable margin
Hyperliquid	marginUsed - max(initialMarginRequirement, 0.1 * size * markPrice). Hyperliquid isolated marginUsed already includes unrealized PnL.
Lighter	marginUsed + unrealizedPnl - initialMarginRequirement. Lighter marginUsed excludes unrealized PnL.
Ondo	Always undefined (cross margin only).

import { positionRemovableMargin } from '@lifi/perps-sdk-provider-hyperliquid';

---

​

Position Math (Estimates)

Pure-function helpers for estimating how a perp position changes after a fill. Add-to-position and partial-close preview blocks use them. These take SDK shapes as they are: pass Position.size, entryPrice, and the other decimal strings without conversion. Sizes passed in are non-negative magnitudes; direction is carried by isLong. Results are for display. Do not send them to a venue.

import {
  estimateLiquidationPrice,
  estimateAverageEntryPrice,
  estimateNewLeverage,
  estimateUnrealizedPnl,
  calculateRealizedPnl,
} from '@lifi/perps-sdk';

​

estimateLiquidationPrice

Estimated liquidation price for a new isolated-margin position, parameterised by the venue’s maintenance margin rate. Throws PerpsError with ValidationError when the inputs cannot produce one (zero leverage, zero denominator). safeEstimateLiquidationPrice gives undefined instead. For existing positions, prefer Position.liquidationPrice from the venue.

import { estimateLiquidationPrice } from '@lifi/perps-sdk';

estimateLiquidationPrice({
  entryPrice: '95000',
  leverage: '10',
  isLong: true,
  maintenanceMarginRate: '0.01',
});
// '86363.6363…'

Parameter	Type	Description
entryPrice	DecimalString	Position entry price
leverage	DecimalString	Position leverage
isLong	boolean	True for long, false for short
maintenanceMarginRate	DecimalString	Venue maintenance margin rate as a fraction (e.g. '0.01' = 1%)

Returns: DecimalString

estimateLiquidationPriceAtMarketRate(market, params) reads the rate from market.maintenanceMarginRate and gives undefined when the market has none.

wouldImmediatelyLiquidate({ liquidationPrice, currentPrice, isLong }) is true when a long’s liquidation price is at or above the current price, or a short’s is at or below it. It gives false when either price is not positive.

​

estimateAverageEntryPrice

Estimated average entry price after adding to an existing position. Weighted average of current entry and the new fill price, weighted by leg size in asset units. Both legs must be in the same direction (this helper is for adding to, not flipping, a position).

import { estimateAverageEntryPrice } from '@lifi/perps-sdk';

const newEntry = estimateAverageEntryPrice({
  currentSize: '1',
  currentEntry: '95000',
  addSize: '0.5',
  fillPrice: '96500',
});
// '95500'

Parameter	Type	Description
currentSize	DecimalString	Existing position size in asset units (>= 0)
currentEntry	DecimalString	Existing position’s average entry price
addSize	DecimalString	Size being added in asset units (>= 0)
fillPrice	DecimalString	Price the new size is expected to fill at (mid for market, limit price for limit orders)

Returns: DecimalString — the new weighted-average entry price. Throws PerpsError with ValidationError when the combined size is not positive or a value is malformed.

​

estimateNewLeverage

Estimated effective leverage (totalNotional / totalMargin) after adding margin and notional. The caller computes notional from size and price (e.g. with calculateNotionalValue) and supplies the additional margin the user is about to put up.

import { estimateNewLeverage } from '@lifi/perps-sdk';

const newLeverage = estimateNewLeverage({
  currentNotional: '10000',
  currentMargin: '1000',
  addNotional: '5000',
  addMargin: '500',
});
// '10'

Parameter	Type	Description
currentNotional	DecimalString	Current position notional
currentMargin	DecimalString	Current position margin
addNotional	DecimalString	Notional being added
addMargin	DecimalString	Margin being added

Returns: DecimalString — the new effective leverage. Throws PerpsError with ValidationError when the total margin is not positive.

​

estimateUnrealizedPnl

Estimated unrealised PnL at the current mark price: (markPrice - entryPrice) * size * (isLong ? 1 : -1).

import { estimateUnrealizedPnl } from '@lifi/perps-sdk';

const uPnl = estimateUnrealizedPnl({
  entryPrice: '95000',
  markPrice: '96000',
  size: '1',
  isLong: true,
});
// '1000'

Parameter	Type	Description
entryPrice	DecimalString	Position entry price
markPrice	DecimalString	Current mark price
size	DecimalString	Position size as a non-negative magnitude
isLong	boolean	Direction of the position

Returns: DecimalString

​

calculateRealizedPnl

Realised PnL on the portion of a position being closed: (closePrice - entryPrice) * closeSize * (isLong ? 1 : -1).

import { calculateRealizedPnl } from '@lifi/perps-sdk';

const rPnl = calculateRealizedPnl({
  entryPrice: '95000',
  closePrice: '96000',
  closeSize: '0.5',
  isLong: true,
});
// '500'

Parameter	Type	Description
entryPrice	DecimalString	Position entry price
closePrice	DecimalString	Price the close fills at
closeSize	DecimalString	Size being closed as a non-negative magnitude
isLong	boolean	Direction of the position being closed

Returns: DecimalString

---

​

Order Math (Expected rPnL Previews)

Helpers for previewing the realised PnL the user would lock in if an active order filled against a matching position. estimateRealizedPnl composes calculateRealizedPnl from Position Math, so the two stay in lockstep.

Orders that open or add to a position have no defined rPnL and return undefined.

import {
  estimateRealizedPnl,
  resolveMatchingPosition,
  resolveCloseSize,
} from '@lifi/perps-sdk';
import type { Order, Position } from '@lifi/perps-sdk';

​

resolveMatchingPosition

Pick the matching open position for an order’s asset, if any.

import { resolveMatchingPosition } from '@lifi/perps-sdk';
import type { Position, RegularOrder } from '@lifi/perps-sdk';

function matchFor(order: RegularOrder, positions: readonly Position[]) {
  return resolveMatchingPosition(order.market.id, positions);
}

Parameter	Type	Description
marketId	string	The order’s market.id
positions	readonly Position[]	Open positions list (any symbol)

Returns: Position | undefined

​

resolveCloseSize

Resolve the close-size against a position, applying the spec’s cap rules:

• orderSize === 0 is the Hyperliquid convention for “close entire position” used by trigger orders → close the full position size.
• Otherwise cap at the absolute position size; an order larger than the position can only close what’s open.

Inputs are non-negative magnitudes.

import { resolveCloseSize } from '@lifi/perps-sdk';

resolveCloseSize('0', '1.5');   // '1.5'  (zero == close-all)
resolveCloseSize('0.5', '1.5'); // '0.5'  (partial close)
resolveCloseSize('2', '1.5');   // '1.5'  (capped at position)

Parameter	Type	Description
orderSize	DecimalString	Order size, non-negative magnitude
positionSize	DecimalString	Open position size, non-negative magnitude

Returns: DecimalString

​

estimateRealizedPnl

Expected rPnL for an unfilled order against a matching position. estimateRealizedPnl(order, position) takes any Order. A resting limit order prices off its limit price and an armed trigger order prices off its trigger price. A TWAP parent carries no single execution price, so the result is undefined. A malformed decimal on the order or the position throws PerpsError with ValidationError; safeEstimateRealizedPnl gives undefined instead.

import { estimateRealizedPnl, resolveMatchingPosition } from '@lifi/perps-sdk';
import type { Order, Position } from '@lifi/perps-sdk';

function previewOrderRPnl(order: Order, positions: readonly Position[]) {
  const position = resolveMatchingPosition(order.market.id, positions);
  return estimateRealizedPnl(order, position);
  // DecimalString when the order would reduce the position; undefined otherwise
}

Parameter	Type	Description
order	Order	The market, limit, or TP/SL trigger order
position	Position | undefined	Matching open position, if any

Returns: DecimalString | undefined

For a market or limit order (RegularOrder), reducing requires opposite sides (long position + SELL, short position + BUY). The projected quantity is order.remainingSize, capped at the position size, at order.price. The result is undefined when:

• there is no matching position;
• order.status is not in ACTIVE_ORDER_STATUSES;
• the order is same-side (it adds to the position);
• order.price is null, or the position size is not positive;
• remainingSize is 0.

For a TP/SL trigger order (TriggerOrder), the order is a closing leg, so its side must be opposite to the position’s. The trigger price is the rPnL price. TriggerOrder.triggerPrice is optional, and the result is undefined when it is absent. The optional limitPrice for STOP_LIMIT / TAKE_PROFIT_LIMIT is the post-trigger limit, not the rPnL price. The projected quantity is remainingSize, capped at the position size. The result is undefined when:

• there is no matching position;
• order.status is not in ACTIVE_ORDER_STATUSES, or is PENDING;
• the order side is not opposite to the position;
• the position size is not positive;
• remainingSize is 0, unless originalSize is 0 and the order is reduceOnly (the close-entire-position convention, which projects the full position size).

---

​

TP/SL Calculations

import {
  calculateExpectedPnl,
  calculateTriggerPrice,
  calculateTriggerPercent,
} from '@lifi/perps-sdk';

​

calculateExpectedPnl

Calculate expected PnL if a trigger price is hit.

import { calculateExpectedPnl } from '@lifi/perps-sdk';

const expected = calculateExpectedPnl(
  '96000', // triggerPrice
  '95000', // entryPrice
  '10',    // leverage
  true,    // isLong
  '1000'   // margin
);
// { amount: '105.2631…', percent: '10.5263…' }

Parameter	Type	Description
triggerPrice	DecimalString	TP/SL trigger price
entryPrice	DecimalString	Position entry price
leverage	DecimalString	Leverage
isLong	boolean	Whether position is long
margin	DecimalString	Position margin

Returns: ExpectedPnl — { amount: DecimalString; percent: DecimalString } (signed; positive = profit). Throws PerpsError with ValidationError when triggerPrice, entryPrice, or margin is zero.

​

calculateTriggerPrice

Convert a target PnL percentage (leveraged ROE, so 50 is +50% on margin) to a trigger price: entryPrice ± entryPrice * percent / 100 / leverage, plus for a long and minus for a short. Throws when entryPrice or leverage is zero.

import { calculateTriggerPrice } from '@lifi/perps-sdk';

const price = calculateTriggerPrice('50', '95000', '10', true);
// '99750' (+50% ROE on a 10x long)

​

calculateTriggerPercent

Convert a trigger price to a leveraged PnL percentage: (price - entryPrice) / entryPrice * leverage * 100, sign-flipped for a short. Throws when entryPrice or leverage is zero.

import { calculateTriggerPercent } from '@lifi/perps-sdk';

const percent = calculateTriggerPercent('99750', '95000', '10', true); // '50'

---

​

Decimal Arithmetic

Exact arithmetic on DecimalString values. Each helper throws PerpsError with ValidationError for a malformed input, and has a safe* pair.

Helper	Result
addDecimalString(a, b)	a + b
addDecimalStrings(values)	Sum of a list. '0' for an empty list.
subtractDecimalString(a, b)	a - b
multiplyDecimalString(a, b)	a * b
divideDecimalString(a, b)	a / b to 40 decimal places, rounded half up. Throws when b is zero.
divideDecimalStringRoundDown(a, b)	a / b to 40 decimal places, rounded toward zero. Throws when b is zero.
absDecimalString(value)	|value|
compareDecimalStrings(a, b)	-1, 0, or 1
isDecimalStringGreaterThan(a, b)	true when a > b
isDecimalStringZero(value)	true when value equals zero

import { addDecimalString, compareDecimalStrings } from '@lifi/perps-sdk';

addDecimalString('0.1', '0.2');       // '0.3'
compareDecimalStrings('1.50', '1.5'); // 0

---

​

Order Entry Amounts

calculateOrderAmounts({ sdk, market, held, amount, leverage, price }) derives the three order-entry amounts from the one the user typed. held is 'margin', 'size', or 'notional', and amount is that figure as a DecimalString. leverage is a number. It returns { margin, size, notional } as DecimalString values.

• Only size snaps, onto the market’s lot grid through the market’s own provider. An order sends size alone.
• notional is the snapped size * price.
• margin is the held amount unchanged when held is 'margin'. Otherwise it is notional / leverage and is for display only.

It throws PerpsError with ValidationError when amount or price is not a positive decimal, leverage is not a finite number above zero, or the snapped size is zero. It throws SDKError when market.providerId names no registered provider. safeCalculateOrderAmounts gives undefined instead.

---

​

Balance Helpers

import {
  calculateTransferable,
  calculateWithdrawMax,
  calculateRefuelAmount,
  REFUEL_FEE_MARGIN_PERCENT,
} from '@lifi/perps-sdk';

• calculateTransferable(venueFigure, units) clamps the venue’s free figure to the range from '0' to units. It is the rule behind Balance.transferable.
• calculateWithdrawMax(row) gives the largest amount a WithdrawableBalance row can fund. It is available, or available - withdrawalFee floored at '0' when isFeeDeducted is false.
• calculateRefuelAmount({ recommendedAmount, recommendedUsd, nativeBalance, priceUsd, decimals }) gives the source-token amount that buys the native gas the wallet lacks. It adds REFUEL_FEE_MARGIN_PERCENT (20) percent, rounds up to decimals places, and gives undefined when the wallet already holds the recommendation. recommendedAmount and nativeBalance are integer base-unit strings.

---

​

Fee & Slippage

import { estimateFees, calculateSlippagePrice } from '@lifi/perps-sdk';

​

estimateFees

sizeUsd * feeRate. Both are DecimalString values. feeRate is a decimal fraction ('0.0005' is 0.05%).

import { estimateFees } from '@lifi/perps-sdk';

const fees = estimateFees('10000', '0.0005'); // '5'

​

calculateSlippagePrice

Adjust a price by a slippage tolerance. calculateSlippagePrice(price, slippagePercent, isBuy) takes DecimalString values. slippagePercent is a percentage ('0.5' is 0.5%; '1' is 1%). A buy multiplies the price by 1 + p / 100; a sell divides it by 1 + p / 100. The result is not rounded to a tick grid: pass it to snapOrderPrice. It throws when slippagePercent is -100 or less.

import { calculateSlippagePrice } from '@lifi/perps-sdk';

calculateSlippagePrice('100', '1', true);  // '101'
calculateSlippagePrice('100', '1', false); // '99.0099…'

---

​

Quote Building

Pure helpers behind getQuote / subscribeQuote — walk a book to a VWAP fill and assemble a Quote. Most consumers call the client methods; reach for these to compute a quote from a book snapshot you already hold.

import { calculateOrderbookWalk, buildQuote } from '@lifi/perps-sdk';

​

calculateOrderbookWalk

Walk one side of an orderbook to fill sizeUsd notional, accumulating base size and notional level-by-level to derive the VWAP fill. Levels are consumed in array order — pass asks for a buy and bids for a sell, each ordered best-price-first. Throws PerpsError (ValidationError) on a malformed level.

import { calculateOrderbookWalk } from '@lifi/perps-sdk';
import type { OrderbookLevel } from '@lifi/perps-sdk';

const asks: OrderbookLevel[] = [
  { price: '95000', size: '0.1' },
  { price: '95010', size: '0.2' },
];
const walk = calculateOrderbookWalk(asks, '10000');
// { baseSize, filledNotional, vwap, insufficientLiquidity }

Parameter	Type	Description
levels	OrderbookLevel[]	One book side, best-price-first
sizeUsd	DecimalString	USD notional to fill

Returns: BookWalk — { baseSize, filledNotional, vwap, insufficientLiquidity }. baseSize, filledNotional, and vwap are DecimalString values (vwap is '0' for an empty book). insufficientLiquidity is a boolean and is true when the book cannot absorb the full notional (the walk returns the best obtainable fill).

​

buildQuote

Assemble a Quote from a resolved market, its live MarketContext, and its orderbook snapshot: walks the relevant side for the VWAP fill, derives price impact in basis points versus mark, and applies the base taker fee on the filled notional. Throws PerpsError (ValidationError) on a malformed book level.

import { buildQuote } from '@lifi/perps-sdk';

// input: { provider, symbol, type, side, sizeUsd, market, price, bids, asks, feeTier, timestamp }
function quoteFrom(input: Parameters<typeof buildQuote>[0]) {
  return buildQuote(input);
}

Returns: Quote.

---

​

Account Summary

Derive portfolio metrics with the PerpsClient.getAccountSummary() method:

import type { AccountResponse, Position } from '@lifi/perps-sdk';

function summarize(account: AccountResponse, positions: Position[]) {
  return perps.getAccountSummary(account, positions);
  // { portfolioValue, availableMargin, marginUsed, unrealizedPnl } — all strings
}

Parameter	Type	Description
account	AccountResponse	Account from getAccount()
positions	Position[]	Positions from getPositions()

Returns: AccountSummary — { portfolioValue, availableMargin, marginUsed, unrealizedPnl }, all string fields. Each provider computes the roll-up from its own venue figures — see getAccountSummary for the source of each field.

---

​

Activity Pagination

paginateActivity merges a provider’s freshly-fetched activity rows with the replayed overflow tail from the previous page, applies the request’s type and time filters, sorts newest-first, and slices to the page limit. It is exported for provider authors implementing a custom getActivity; most consumers call getActivity() directly and never call this helper.

import { paginateActivity } from '@lifi/perps-sdk';

function nextPage(
  freshItems: Parameters<typeof paginateActivity>[0],
  overflow: Parameters<typeof paginateActivity>[1],
  params: Parameters<typeof paginateActivity>[2],
  encodeCursor: Parameters<typeof paginateActivity>[3]
) {
  return paginateActivity(freshItems, overflow, params, encodeCursor);
}

Parameter	Type	Description
freshItems	ActivityItem[]	Rows the provider fetched for this page
overflow	ActivityItem[]	Rows carried over from the previous page’s overflow tail
params	Pick<ProviderGetActivityParams, 'type' | 'startTime' | 'endTime' | 'limit'>	The request’s type/time filters and page size
encodeCursor	(overflowTail: ActivityItem[]) => string | undefined	Encodes the rows past the page slice into the provider’s own cursor, or returns undefined when nothing remains

Returns: { items: ActivityItem[]; pagination: Pagination }.

---

​

Order Classification

import {
  isTakeProfitOrder,
  isStopLossOrder,
  isTpSlOrder,
  isTriggerOrder,
  isRegularOrder,
  isTwapOrder,
  triggerConditionFor,
  classifyFillFromPosition,
  ACTIVE_ORDER_STATUSES,
  isActiveOrderStatus,
  orderSideLabel,
  SPOT_CATEGORY_ID,
  isSpotCategory,
} from '@lifi/perps-sdk';

​

isTakeProfitOrder / isStopLossOrder / isTpSlOrder

Check whether an order is a TP, SL, or either. They accept anything with an order type.

import { isTpSlOrder } from '@lifi/perps-sdk';
import type { Order } from '@lifi/perps-sdk';

function describe(order: Order) {
  if (isTpSlOrder(order)) {
    console.log('This is a trigger order');
  }
}

​

isTriggerOrder / isRegularOrder / isTwapOrder

Type guards that narrow the Order union. isTriggerOrder matches TriggerOrder (take-profit and stop types), isRegularOrder matches RegularOrder (MARKET and LIMIT), and isTwapOrder matches TwapOrder (TWAP).

import { isTriggerOrder } from '@lifi/perps-sdk';
import type { Order } from '@lifi/perps-sdk';

function triggerPriceOf(order: Order) {
  return isTriggerOrder(order) ? order.triggerPrice : undefined;
}

​

triggerConditionFor

triggerConditionFor(type, side) returns the TriggerCondition a trigger order fires on. Take-profit on a sell and stop-loss on a buy return ABOVE; take-profit on a buy and stop-loss on a sell return BELOW.

import { OrderSide, OrderType, triggerConditionFor } from '@lifi/perps-sdk';

triggerConditionFor(OrderType.TAKE_PROFIT_MARKET, OrderSide.SELL); // TriggerCondition.ABOVE

​

classifyFillFromPosition

Classify a fill into the full Open/Close/Increase/Reduce/Switch taxonomy using the signed position held before the fill. This is the SDK classifier for a fill when the position before the fill is known.

import { OrderSide, classifyFillFromPosition } from '@lifi/perps-sdk';

classifyFillFromPosition('0', OrderSide.BUY, '0.5');   // 'Opened Long'
classifyFillFromPosition('1.0', OrderSide.SELL, '1.0'); // 'Closed Long'

Parameter	Type	Description
startPosition	DecimalString	Signed position before this fill (> 0 long, < 0 short, 0 flat)
side	OrderSide	Side of the fill
sz	DecimalString	Unsigned fill size

Returns: FillClassification. A string that does not match the decimal pattern gives FillClassification.BUY or FillClassification.SELL by side.

​

ACTIVE_ORDER_STATUSES / isActiveOrderStatus

ACTIVE_ORDER_STATUSES is the ReadonlySet<OrderStatus> of lifecycle statuses included in order reads by default: OPEN, PENDING, ACCEPTED, PARTIALLY_FILLED, TRIGGERED. An order in one of these is still live (not terminal): PENDING waits on a parent, and ACCEPTED is venue-accepted but not yet on the book. Any other status is terminal; evict it from a cached orders list on a WS update. isActiveOrderStatus(status) is the membership check.

import { isActiveOrderStatus } from '@lifi/perps-sdk';
import type { OrderStatus } from '@lifi/perps-sdk';

function onOrderUpdate(
  update: { id: string; status: OrderStatus },
  removeFromCache: (id: string) => void
) {
  if (!isActiveOrderStatus(update.status)) {
    removeFromCache(update.id);
  }
}

​

orderSideLabel

orderSideLabel(side, market) returns the direction label of an order. A spot market gives 'Buy' or 'Sell'. A perp market gives 'Long' or 'Short'. The label comes only from side and market.categoryId. reduceOnly and isLiquidation do not change it.

import { OrderSide, orderSideLabel } from '@lifi/perps-sdk';

orderSideLabel(OrderSide.SELL, { categoryId: 'hyperliquid' }); // 'Short'
orderSideLabel(OrderSide.SELL, { categoryId: 'spot' });        // 'Sell'

Parameter	Type	Description
side	OrderSide	Side of the order
market	Pick<MarketDisplay, 'categoryId'>	Any market shape with a categoryId, for example Market, MarketDisplay, or order.market

Returns: OrderSideLabel, the type 'Long' | 'Short' | 'Buy' | 'Sell'. Import the type from @lifi/perps-sdk, for example to select the color of a label.

​

SPOT_CATEGORY_ID / isSpotCategory

SPOT_CATEGORY_ID is the category id ('spot') of spot markets and spot balances on every provider. isSpotCategory(categoryId) is the equality check. Use it in place of a literal 'spot' comparison.

import { isSpotCategory } from '@lifi/perps-sdk';
import type { Balance } from '@lifi/perps-sdk';

function spotBalances(balances: Balance[]) {
  return balances.filter((balance) => isSpotCategory(balance.categoryId));
}

---

​

Parsing & Conversion

import {
  decimalStringToNumber,
  isDecimalString,
  unknownToDecimalString,
  roundDecimalString,
  decimalStringToScaledInteger,
  scaledIntegerToDecimalString,
  numberToDecimalString,
} from '@lifi/perps-sdk';

Each helper has a safe* pair (for example safeRoundDecimalString) that logs a warning and gives undefined in place of the throw.

​

decimalStringToNumber

Read a DecimalString as a number. Use it for chart values and other display input only, because a number loses digits. It throws PerpsError with ValidationError for a string that does not match the decimal pattern or a value too large for a number.

import { decimalStringToNumber } from '@lifi/perps-sdk';

decimalStringToNumber('1234.56'); // 1234.56

​

isDecimalString

Narrows an unknown value to DecimalString. See Numbers for the pattern.

​

unknownToDecimalString

unknownToDecimalString(value, field, tool) turns an unknown venue value into a DecimalString. It spells a finite number or an exponent string in plain notation. It throws PerpsError with SDKError and a message that names field and tool when the value is not a finite decimal.

import { unknownToDecimalString } from '@lifi/perps-sdk';

unknownToDecimalString(1e-7, 'price', 'myProvider'); // '0.0000001'

​

roundDecimalString

Round a DecimalString to decimals places with an explicit DecimalRounding. 'truncate' moves toward zero, 'round' goes half away from zero, and 'up' goes away from zero. It strips trailing zeros. It throws PerpsError with ValidationError for a value that does not match the decimal pattern, or a decimals that is not a non-negative integer.

import { roundDecimalString } from '@lifi/perps-sdk';

roundDecimalString('500.129', 2, 'truncate'); // '500.12'
roundDecimalString('1.50', 1, 'round');       // '1.5'

​

decimalStringToScaledInteger

Scale a DecimalString to an integer number in exact decimal arithmetic. Use it when a provider wire format requires an integer amount. decimalStringToScaledInteger(value, decimals, rounding) requires an explicit off-grid rounding (type DecimalRounding): 'truncate' moves toward zero for sizes and collateral, while 'round' snaps prices half away from zero.

import { decimalStringToScaledInteger } from '@lifi/perps-sdk';

decimalStringToScaledInteger('0.29', 2, 'truncate'); // 29

A value that does not match the decimal pattern, a negative or non-integer decimals, and a result beyond Number.MAX_SAFE_INTEGER throw PerpsError with ValidationError.

​

scaledIntegerToDecimalString

Convert a scaled integer amount (an integer string) to a DecimalString. It throws PerpsError with ValidationError when amount is not an integer string ('1.5', '1e3', '', 'abc') or decimals is not a non-negative integer.

import { scaledIntegerToDecimalString } from '@lifi/perps-sdk';

scaledIntegerToDecimalString('1000000', 6); // '1'

​

numberToDecimalString

Spell a number as a DecimalString in plain notation, never in exponent notation. Use it at a boundary where a venue or browser API gives a number. It throws PerpsError with ValidationError for NaN and infinite values.

import { numberToDecimalString } from '@lifi/perps-sdk';

numberToDecimalString(1e-7); // '0.0000001'

---

​

Formatting

Display formatters for USD amounts, prices, and percentages. Each accepts a FormatInput (number, decimal string, or null/undefined) and an optional FormatOptions. Null, blank, and non-finite input renders the placeholder (default '—'). A string that does not match the decimal pattern is returned unchanged.

import {
  formatNumber,
  formatUsd,
  formatSignedUsd,
  formatSignedPercent,
  formatPrice,
  formatCompactUsd,
} from '@lifi/perps-sdk';

FormatOptions is accepted by every formatter; the defaults differ by formatter:

Field	Type	Default	Description
decimals	number	2 (formatPrice: auto, see below)	Fraction digits
placeholder	string	'—'	Rendered for null, blank, or non-finite input
locale	string	host locale	BCP-47 locale for digit grouping
rounding	RoundingMode	'halfUp'	'halfUp' or 'floor' (truncates toward zero)

formatCompactUsd reads only decimals and placeholder; it ignores locale and rounding.

​

formatNumber

Currency-symbol-free core formatter: two decimals with locale digit grouping by default. The other formatters build on it.

import { formatNumber } from '@lifi/perps-sdk';

formatNumber(1234.5);                          // '1,234.50'
formatNumber(1234.567, { rounding: 'floor' }); // '1,234.56'

​

formatUsd

Unsigned USD, two decimals with digit grouping. Negatives place the - before the $.

import { formatUsd } from '@lifi/perps-sdk';

formatUsd(1234.5);  // '$1,234.50'
formatUsd(-1500);   // '-$1,500.00'

​

formatSignedUsd

USD with an explicit sign, derived after rounding (so sub-cent magnitudes render $0.00).

import { formatSignedUsd } from '@lifi/perps-sdk';

formatSignedUsd(1.43);  // '+$1.43'
formatSignedUsd(-1.43); // '-$1.43'

​

formatSignedPercent

Percentage with an explicit sign and no grouping.

import { formatSignedPercent } from '@lifi/perps-sdk';

formatSignedPercent(1.43);  // '+1.43%'
formatSignedPercent(-1.43); // '-1.43%'

​

formatPrice

Unsigned price with decimals auto-detected from magnitude (override with options.decimals): 2 decimals at >= 1, 4 at >= 0.1, 5 at >= 0.01, otherwise 6. Grouping applies once the absolute value reaches 1000.

import { formatPrice } from '@lifi/perps-sdk';

formatPrice(1234.5);  // '$1,234.50'
formatPrice(0.1234);  // '$0.1234'

​

formatCompactUsd

USD with a B/M/K suffix, using decimals (default 2) for every suffix. Values below 1000 render without a suffix. There is no promotion at a rounding boundary: formatCompactUsd(999_999) renders '$1000.00K'.

import { formatCompactUsd } from '@lifi/perps-sdk';

formatCompactUsd(1_230_000_000); // '$1.23B'
formatCompactUsd(45_600_000);    // '$45.60M'

---

​

Explorer

import { explorerTxUrl, explorerTxUrlFromBase, ExplorerChainId } from '@lifi/perps-sdk';

​

explorerTxUrl / ExplorerChainId

Resolve a tx hash to a fully-qualified block-explorer URL for the settling chain. ExplorerChainId is the const map of supported settling chains and the union of its values: ETHEREUM 1 (etherscan.io), ARBITRUM_ONE 42161 (arbiscan.io), LIGHTER 304 (app.lighter.xyz), ROBINHOOD 4663 (robin.etherscan.io), HYPERLIQUID 999 (app.hyperliquid.xyz), AVALANCHE_C_CHAIN 43114 (snowtrace.io), and BNB_SMART_CHAIN 56 (bscscan.com). explorerTxUrl returns undefined for an empty hash (no on-chain tx to link).

import { ExplorerChainId, explorerTxUrl } from '@lifi/perps-sdk';

explorerTxUrl(ExplorerChainId.HYPERLIQUID, '0xabc123');
// 'https://app.hyperliquid.xyz/explorer/tx/0xabc123'

Parameter	Type	Description
chainId	ExplorerChainId	Settling chain the tx was observed on
txHash	string | undefined	Transaction hash

Returns: string | undefined. Use explorerTxUrlFromBase(baseUrl, txHash) for provider instances whose explorer is configured by URL rather than one of the known ExplorerChainId values; it returns undefined when either input is absent.

---

​

Deposit Assets and Gas

Deposit destinations are provider-owned and resolved through PerpsClient.getDepositFlow(). The SDK exports canonical on-chain asset identities for consumers that render or execute those flows:

import {
  ETHEREUM_NATIVE_GAS,
  ETHEREUM_USDC,
  HYPERLIQUID_USDC,
  LIGHTER_USDC,
  ROBINHOOD_NATIVE_GAS,
  ROBINHOOD_USDG,
  getGasRecommendation,
} from '@lifi/perps-sdk';

Each asset is a DeclaredDepositAsset with { chainId, address, decimals }; identity is the chain/address pair, not the display symbol. getGasRecommendation(client, { chainId }) calls LI.FI’s gas suggestion API for the native-gas leg of a venueDepositPipeline. It returns GasRecommendationResponse, including available: false when LI.FI cannot source gas for that chain. The call goes to LIFI_API_URL (https://li.quest/v1) — the general LI.FI API, not the perps backend apiUrl.

---

​

Setup and Market Selection

import {
  isActiveMarket,
  selectUserSetupActions,
  toPerpsMarketDisplay,
} from '@lifi/perps-sdk';

• selectUserSetupActions(provider.setup) returns the steps a user sees: every choice step, and every non-choice step whose signer is USER. A non-choice step whose signer is SDK is completed inline by checkSetup() and should not be rendered as a user action. When an account is available, prefer checkSetup().checklist, which also carries each step’s satisfied state.
• isActiveMarket(market) is false only when market.isDelisted === true.
• toPerpsMarketDisplay(market) projects a perpetual market to the identity/capability shape embedded in positions, including isDelisted and positionMarginAdjustment.
• toAssetDisplay(asset) projects an Asset to the AssetDisplay identity and label shape.

---

​

Default Markets

DEFAULT_MARKET_ID maps a provider key to the venue Market.id to land on when no market is named: hyperliquid 'BTC', lighter '1', ondo 'BTC-USD.P'. getDefaultMarketId(provider) reads it, and DefaultMarketProvider is the union of those three keys.

import { getDefaultMarketId } from '@lifi/perps-sdk';

const marketId = getDefaultMarketId('hyperliquid'); // 'BTC'

---

​

Signing

import { signTypedData, signTypedDataWithSigner } from '@lifi/perps-sdk';

​

signTypedData

Sign EIP-712 typed data with a private key. Useful for server-side signing without a wallet. Async — returns Promise<Hex>.

import { signTypedData } from '@lifi/perps-sdk';
import type { PerpsTypedData } from '@lifi/perps-sdk';
import type { Hex } from 'viem';

async function sign(privateKey: Hex, typedData: PerpsTypedData) {
  return signTypedData(privateKey, typedData);
}

Parameter	Type	Description
privateKey	Hex	Private key (0x-prefixed)
typedData	PerpsTypedData	EIP-712 typed data from a create endpoint

​

signTypedDataWithSigner

Sign EIP-712 typed data with an externally-provided viem WalletClient — a browser wallet (wagmi), private key, or mnemonic. Use this to sign the user arm of a setup step with the end-user’s wallet. Async — returns Promise<Hex>.

import { signTypedDataWithSigner } from '@lifi/perps-sdk';
import type { PerpsTypedData } from '@lifi/perps-sdk';

async function sign(typedData: PerpsTypedData) {
  return signTypedDataWithSigner(walletClient, typedData);
}

Parameter	Type	Description
userWallet	WalletClient	viem wallet client with an account
typedData	PerpsTypedData	EIP-712 typed data from a create endpoint

---

​

Storage

Session credentials (provider agent keypairs, API keys, and read-only tokens) persist through a pluggable StorageAdapter — an async { get, set, remove } key-value interface. Pass a custom adapter through the provider/client config; the SDK ships two concrete adapters:

import { createMemoryStorage, localStorageAdapter } from '@lifi/perps-sdk';
import type { StorageAdapter } from '@lifi/perps-sdk';

​

createMemoryStorage

In-memory StorageAdapter, for testing or server-side use. State is lost when the process exits.

import { createMemoryStorage } from '@lifi/perps-sdk';

const storage = createMemoryStorage();

Returns: StorageAdapter.

​

localStorageAdapter

Default browser StorageAdapter: persists AES-GCM-256-encrypted values to localStorage, keyed by a non-extractable master key held in IndexedDB. Falls back to a no-op / null when localStorage, IndexedDB, or crypto.subtle is unavailable (e.g. server-side rendering) — it never writes plaintext. See Providers / Hyperliquid — Signing Model for the agent-keypair storage namespace built on this adapter.

import { localStorageAdapter } from '@lifi/perps-sdk';

const storage = localStorageAdapter;

---

​

Hyperliquid-specific

These utilities apply Hyperliquid’s order formatting and margin rules and are exported from @lifi/perps-sdk-provider-hyperliquid (not the core SDK). They are Hyperliquid-only: do not apply them to another provider’s markets. To snap an order price or size for any provider, use snapOrderPrice(sdk, market, price) / snapOrderSize(sdk, market, size), described in Provider plugin snapping.

import {
  calculateLiquidationPrice,
  calculateMaintenanceMarginRate,
  getMaxPriceDecimals,
  positionRemovableMargin,
  snapOrderPrice,
  snapOrderSize,
} from '@lifi/perps-sdk-provider-hyperliquid';

calculateLiquidationPrice and calculateMaintenanceMarginRate return a DecimalString and throw PerpsError with ValidationError when the inputs cannot yield a valid result. safeCalculateLiquidationPrice and safeCalculateMaintenanceMarginRate give undefined instead.

​

calculateMaintenanceMarginRate

Maintenance margin rate as a fraction: 1 / (2 * maxLeverage). maxLeverage is a number. It throws when maxLeverage is not a finite number above zero.

import { calculateMaintenanceMarginRate } from '@lifi/perps-sdk-provider-hyperliquid';

const mmr = calculateMaintenanceMarginRate(50); // '0.01'

​

calculateLiquidationPrice

Liquidation price for a new isolated position. It computes mmr as above. entryPrice and leverage are DecimalString values and maxLeverage is a number. It returns the same value as estimateLiquidationPrice({ entryPrice, leverage, isLong, maintenanceMarginRate: mmr }). For existing positions, prefer Position.liquidationPrice.

import { calculateLiquidationPrice } from '@lifi/perps-sdk-provider-hyperliquid';

const liqPrice = calculateLiquidationPrice('95000', '10', true, 50);
// '86363.6363…'

​

snapOrderPrice

Snap a DecimalString price onto the Hyperliquid tick grid. The price is rounded half-up to 6 - szDecimals decimal places (8 - szDecimals for 'spot'), then to 5 significant figures unless it is an integer. Trailing zeros are stripped and zero returns '0'.

import { snapOrderPrice } from '@lifi/perps-sdk-provider-hyperliquid';

snapOrderPrice('95123.456', 2);       // '95123'
snapOrderPrice('1.23456', 2, 'spot'); // '1.2346'

Parameter	Type	Description
price	DecimalString	Price to snap
szDecimals	number	Asset’s szDecimals, from market metadata
market	string?	Optional market type — 'spot' allows more decimal places than perps; omit for perps rules

​

snapOrderSize

Snap a DecimalString size onto the Hyperliquid lot grid. The size is truncated toward zero to szDecimals places and never rounded up. Trailing zeros are stripped.

import { snapOrderSize } from '@lifi/perps-sdk-provider-hyperliquid';

snapOrderSize('0.100', 3);  // '0.1'
snapOrderSize('0.1239', 3); // '0.123'

​

getMaxPriceDecimals

Get the maximum number of price decimal places for an asset: 6 - szDecimals for perps, 8 - szDecimals for spot (minimum 0).

import { getMaxPriceDecimals } from '@lifi/perps-sdk-provider-hyperliquid';

getMaxPriceDecimals(2);         // 4
getMaxPriceDecimals(2, 'spot'); // 6

Parameter	Type	Description
szDecimals	number	Asset’s szDecimals, from market metadata
market	string?	Optional market type — 'spot' allows more decimal places than perps; omit for perps rules

positionRemovableMargin is documented under Margin adjustment capability. The Lighter and Ondo provider packages export their own snapOrderPrice(market, price), snapOrderSize(market, size), and positionRemovableMargin, with venue-specific rules.

---

​

Provider plugin snapping

Prices and sizes must sit on the venue’s tick and lot grid, or the order is rejected. Route every order price and size through the market’s own provider. snapOrderPrice(sdk, market, price) and snapOrderSize(sdk, market, size) take and give a DecimalString, and resolve the provider from market.providerId:

import { snapOrderPrice, snapOrderSize } from '@lifi/perps-sdk';
import type { Market } from '@lifi/perps-sdk';

function snapToGrid(market: Market) {
  const price = snapOrderPrice(perps.client, market, '95123.456');
  const size = snapOrderSize(perps.client, market, '0.1239');
  return { price, size };
}

• snapOrderPrice rounds half-up onto the venue’s tick grid and returns a wire-ready DecimalString. It throws PerpsError with ValidationError when market lacks the tick metadata the venue needs, and with SDKError when market.providerId names no registered provider.
• snapOrderSize truncates toward zero to the venue’s lot grid (never rounds up) and returns a DecimalString. size is a non-negative magnitude.

perps.client.getProvider(market.providerId) returns the provider plugin (or undefined for an unregistered key). The plugin carries the same two methods, plus two more methods and one optional member:

• estimateLiquidationPrice(market, { entryPrice, leverage, isLong }) takes DecimalString inputs and estimates the liquidation price of a new isolated position with the venue’s margin model. It returns a DecimalString, or undefined when the model cannot be evaluated.
• positionRemovableMargin(position) is the method behind perps.getPositionRemovableMargin.
• triggerOrders is the optional member with the TP/SL settings of the venue: modifyCanChangeType, and for Lighter marketSlippage. See Provider trigger order settings for the fields and for an example that converts a slippage percent to the limitPrice of a Lighter MARKET leg with calculateSlippagePrice and snapOrderPrice.

---

​

Provider-Author Internals

The core SDK exports a small set of symbols intended for provider plugin authors, not consuming applications. They are documented here for completeness only.

These symbols are exported from @lifi/perps-sdk but are not part of the consumer-facing API. Building a UI or trading flow never requires them.

Storage: parseStoredRecord, readValidatedRecord — parse and validate a record read from the configured storage adapter.

Transport: fetchWithRetry, resolveRetryPolicy, DISABLED_RETRY, LIFI_REQUEST_KEY, LIFI_RETRY_DEFAULTS — the retrying HTTP client a provider plugin uses to call its venue’s REST API.

Reference data registries: AssetRegistry, getAssetRegistry, MarketRegistry, getMarketRegistry, toMarketDisplay — per-provider hash-index caches over /assets and /markets. getAssetRegistry(client, provider) and getMarketRegistry(client, provider) return a stable instance per (client, provider) pair. Each registry exposes sync(), which fetches and dedupes concurrent in-flight calls (freshness follows the endpoint’s cache-control header rather than a fixed TTL), and get(id), an O(1) lookup that returns undefined and logs one warning for an unknown id. toMarketDisplay(market) projects a full Market down to MarketDisplay.

WebSocket base: WsProviderBase, ReconnectingWebSocket, cachePromise, WS_CHANNEL_TEARDOWN_LINGER_MS, wsLog — the reconnecting WebSocket transport and channel-subscription base class a provider plugin extends for streaming reads.

Quote resolution: resolveQuote, resolveQuoteMarket, resolveSubscribeQuote, QUOTE_THROTTLE_MS — the shared getQuote implementation a provider plugin calls to fulfill its own quote and quote-subscription methods.

Safe-function and venue-row helpers: createSafeFunction(name, fn) wraps a throwing function into a pair that logs one warning and gives undefined on a throw. createWarnOnce() gives a (key, message) logger that warns once per key. warnSkippedVenueRow(provider, row, field, value, { marketId?, expected? }) logs a deduplicated warning when a provider drops a venue row with a malformed field. timestampToIsoString(value) reads a venue time (epoch milliseconds or a date string) as an ISO-8601 string and throws PerpsError with ValidationError for an invalid time. safeTimestampToIsoString gives undefined instead.

Provider lookup: requireProvider(client, provider) gives the registered provider plugin and throws PerpsError with SDKError when the plugin is not registered.

WebSocket decoding: DecodeChain runs the asynchronous decode of each WebSocket frame in arrival order. DecodeChainMode is 'every' or 'latest': 'every' decodes every frame, and 'latest' replaces the frames that wait behind a running decode with the newest one. push(decode) queues a decode, reset() drops the queued one, and onError receives each decode failure.

Error and retry helpers: errorCodeFromStatus(status, fallback, statusCodes?) maps an HTTP status to a PerpsErrorCode (a 429 is always RateLimitExceeded; every other status takes fallback unless statusCodes overrides it). isAbortError(error) is true for an AbortError; transports rethrow aborts untouched instead of retrying or wrapping them. resolveRetryPolicy(base, config, providerKey) merges a RetryConfig onto a provider’s default policy: config[providerKey], then config.default, then base; a flat RetryPolicy applies to every provider and false disables retries.