@lifi/perps-sdk 0.0.0-preview-64fca0d

package/src/utils/format.ts

@@ -0,0 +1,212 @@
+/**
+ * Options shared by the human-facing display formatters.
+ *
+ * @public
+ */
+export interface FormatOptions {
+  /** Fixed number of decimal places. Defaults are per-formatter. */
+  decimals?: number
+  /** Rendered when the value is null/undefined/NaN/non-finite. Defaults to `'—'`. */
+  placeholder?: string
+  /** BCP 47 locale controlling digit grouping and separators (e.g. `'en-US'`). */
+  locale?: string
+}
+
+const DEFAULT_PLACEHOLDER = '—'
+
+type FormatInput = number | string | null | undefined
+
+/**
+ * Tolerantly coerce a display input to a finite number.
+ *
+ * Strips `$`, `,`, and surrounding whitespace from strings. Returns `null`
+ * when the value is null/undefined/blank or does not resolve to a finite
+ * number, so callers can render a placeholder instead of `$0.00` or `$NaN`.
+ */
+function toFiniteNumber(value: FormatInput): number | null {
+  let n: number
+  if (typeof value === 'string') {
+    const cleaned = value.replace(/[$,\s]/g, '')
+    if (!cleaned) {
+      return null
+    }
+    n = Number(cleaned)
+  } else if (typeof value === 'number') {
+    n = value
+  } else {
+    return null
+  }
+  return Number.isFinite(n) ? n : null
+}
+
+/**
+ * Round to `decimals` then split into a sign (`'-'` or `''`) and the
+ * locale-formatted absolute body. Deriving the sign from the rounded value
+ * avoids `-$0.00` for values that round to zero.
+ */
+function signAndBody(
+  n: number,
+  decimals: number,
+  locale: string | undefined,
+  grouping: boolean
+): { sign: '-' | ''; body: string } {
+  const rounded = Number(n.toFixed(decimals))
+  const sign = rounded < 0 ? '-' : ''
+  const body = Math.abs(rounded).toLocaleString(locale, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+    useGrouping: grouping,
+  })
+  return { sign, body }
+}
+
+/**
+ * Auto-detect a sensible number of decimal places from a value's magnitude:
+ * `>=1` → 2, `>=0.1` → 4, `>=0.01` → 5, otherwise 6.
+ */
+function autoDecimals(abs: number): number {
+  if (abs >= 1) {
+    return 2
+  }
+  if (abs >= 0.1) {
+    return 4
+  }
+  if (abs >= 0.01) {
+    return 5
+  }
+  return 6
+}
+
+/**
+ * Format a USD value, unsigned: `$1,234.50`, `-$1,500.00`, `$0.00`.
+ *
+ * Two decimal places with locale digit grouping. Negatives place the `-`
+ * before the `$`. Null/undefined/non-finite input renders the placeholder.
+ *
+ * @public
+ */
+export function formatUsd(
+  value: FormatInput,
+  options: FormatOptions = {}
+): string {
+  const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER, locale } = options
+  const n = toFiniteNumber(value)
+  if (n === null) {
+    return placeholder
+  }
+  const { sign, body } = signAndBody(n, decimals, locale, true)
+  return `${sign}$${body}`
+}
+
+/**
+ * Format a USD value with an explicit sign: `+$1.43`, `-$1.43`, `$0.00`.
+ *
+ * The sign is derived after rounding, so sub-cent magnitudes render `$0.00`
+ * (no spurious `+`/`-`). Null/undefined/non-finite input renders the
+ * placeholder.
+ *
+ * @public
+ */
+export function formatSignedUsd(
+  value: FormatInput,
+  options: FormatOptions = {}
+): string {
+  const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER, locale } = options
+  const n = toFiniteNumber(value)
+  if (n === null) {
+    return placeholder
+  }
+  const rounded = Number(n.toFixed(decimals))
+  const sign = rounded > 0 ? '+' : rounded < 0 ? '-' : ''
+  const body = Math.abs(rounded).toLocaleString(locale, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+    useGrouping: true,
+  })
+  return `${sign}$${body}`
+}
+
+/**
+ * Format a percentage with an explicit sign and no grouping: `+1.43%`,
+ * `-1.43%`, `0.00%`.
+ *
+ * The sign is derived after rounding, so sub-threshold magnitudes render
+ * `0.00%`. Null/undefined/non-finite input renders the placeholder.
+ *
+ * @public
+ */
+export function formatSignedPercent(
+  value: FormatInput,
+  options: FormatOptions = {}
+): string {
+  const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER, locale } = options
+  const n = toFiniteNumber(value)
+  if (n === null) {
+    return placeholder
+  }
+  const rounded = Number(n.toFixed(decimals))
+  const sign = rounded > 0 ? '+' : rounded < 0 ? '-' : ''
+  const body = Math.abs(rounded).toLocaleString(locale, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+    useGrouping: false,
+  })
+  return `${sign}${body}%`
+}
+
+/**
+ * Format a price, unsigned, with decimals auto-detected from magnitude:
+ * `$1,234.50`, `$0.1234`, `-$1,500.00`.
+ *
+ * Decimals follow {@link autoDecimals} unless `options.decimals` is given.
+ * Grouping applies once the absolute value reaches 1000. Negatives place the
+ * `-` before the `$`. Null/undefined/non-finite input renders the placeholder.
+ *
+ * @public
+ */
+export function formatPrice(
+  value: FormatInput,
+  options: FormatOptions = {}
+): string {
+  const { placeholder = DEFAULT_PLACEHOLDER, locale } = options
+  const n = toFiniteNumber(value)
+  if (n === null) {
+    return placeholder
+  }
+  const abs = Math.abs(n)
+  const decimals = options.decimals ?? autoDecimals(abs)
+  const { sign, body } = signAndBody(n, decimals, locale, abs >= 1000)
+  return `${sign}$${body}`
+}
+
+/**
+ * Format a USD value compactly with a `B`/`M`/`K` suffix: `$1.23B`, `$45.6M`,
+ * `$789.0K`, `$12.34`.
+ *
+ * Negatives place the `-` before the `$`. Null/undefined/non-finite input
+ * renders the placeholder.
+ *
+ * @public
+ */
+export function formatCompactUsd(
+  value: FormatInput,
+  options: FormatOptions = {}
+): string {
+  const { decimals = 2, placeholder = DEFAULT_PLACEHOLDER } = options
+  const n = toFiniteNumber(value)
+  if (n === null) {
+    return placeholder
+  }
+  const sign = n < 0 ? '-' : ''
+  const abs = Math.abs(n)
+  if (abs >= 1_000_000_000) {
+    return `${sign}$${(abs / 1_000_000_000).toFixed(decimals)}B`
+  }
+  if (abs >= 1_000_000) {
+    return `${sign}$${(abs / 1_000_000).toFixed(decimals)}M`
+  }
+  if (abs >= 1_000) {
+    return `${sign}$${(abs / 1_000).toFixed(decimals)}K`
+  }
+  return `${sign}$${abs.toFixed(decimals)}`
+}

package/src/utils/orderClassification.ts

@@ -0,0 +1,96 @@
+/**
+ * Order classification utilities.
+ *
+ * Type guards and classifiers that operate on SDK types to determine
+ * order categories (TP/SL, open/close). These use the OrderType enum
+ * for classification — no string matching.
+ */
+
+import type { OpenOrder } from '@lifi/perps-types'
+import {
+  FillClassification,
+  OrderSide,
+  OrderStatus,
+  OrderType,
+} from '@lifi/perps-types'
+import { stringToFloat } from './parse.js'
+
+export { FillClassification }
+
+const TP_TYPES = new Set<OrderType>([
+  OrderType.TAKE_PROFIT_MARKET,
+  OrderType.TAKE_PROFIT_LIMIT,
+])
+
+const SL_TYPES = new Set<OrderType>([
+  OrderType.STOP_MARKET,
+  OrderType.STOP_LIMIT,
+])
+
+/**
+ * Check if an open order is a Take Profit trigger order.
+ * @public
+ */
+export function isTakeProfitOrder(order: Pick<OpenOrder, 'type'>): boolean {
+  return TP_TYPES.has(order.type)
+}
+
+/**
+ * Check if an open order is a Stop Loss trigger order.
+ * @public
+ */
+export function isStopLossOrder(order: Pick<OpenOrder, 'type'>): boolean {
+  return SL_TYPES.has(order.type)
+}
+
+/**
+ * Check if an open order is a TP or SL trigger order.
+ * @public
+ */
+export function isTpSlOrder(order: Pick<OpenOrder, 'type'>): boolean {
+  return TP_TYPES.has(order.type) || SL_TYPES.has(order.type)
+}
+
+/**
+ * Order statuses representing an order still resting on the book (visible
+ * in `openOrders` / `triggerOrders`). Anything not in this set is terminal —
+ * filled, cancelled, rejected, expired — and should be evicted from the
+ * cached orders list when seen in a WS update.
+ * @public
+ */
+export const ACTIVE_ORDER_STATUSES: ReadonlySet<OrderStatus> = new Set([
+  OrderStatus.OPEN,
+  OrderStatus.PENDING,
+  OrderStatus.PARTIALLY_FILLED,
+  OrderStatus.TRIGGERED,
+])
+
+/**
+ * Whether `status` is one of {@link ACTIVE_ORDER_STATUSES}.
+ *
+ * @public
+ */
+export function isActiveOrderStatus(status: OrderStatus): boolean {
+  return ACTIVE_ORDER_STATUSES.has(status)
+}
+
+/**
+ * Classify a fill as open or close based on realizedPnl.
+ * @deprecated Use `Fill.classification` instead — it uses startPosition
+ * for accurate open/increase/reduce/close/reverse classification.
+ * @public
+ */
+export function classifyFill(
+  side: OrderSide,
+  realizedPnl: string | null | undefined
+): FillClassification {
+  const isClose = realizedPnl != null && stringToFloat(realizedPnl) !== 0
+  if (side === OrderSide.BUY) {
+    return isClose
+      ? FillClassification.CLOSED_SHORT
+      : FillClassification.OPENED_LONG
+  }
+  return isClose
+    ? FillClassification.CLOSED_LONG
+    : FillClassification.OPENED_SHORT
+}

package/src/utils/orderMath.ts

@@ -0,0 +1,134 @@
+import {
+  type OpenOrder,
+  OrderSide,
+  type Position,
+  PositionSide,
+  type TriggerOrder,
+} from '@lifi/perps-types'
+import { realizedPnlOnClose } from './positionMath.js'
+
+/**
+ * Pick the matching open position for an order's market, if any.
+ *
+ * @param marketId - The order's `market.id`.
+ * @param positions - Open positions list (any market).
+ * @public
+ */
+export function findMatchingPosition(
+  marketId: string,
+  positions: readonly Position[]
+): Position | undefined {
+  return positions.find((p) => p.market.id === marketId)
+}
+
+/**
+ * Resolve the close-size against a position, applying the spec's cap rules:
+ *  - `orderSize === 0` is the Hyperliquid convention for "close entire
+ *    position" → 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.
+ * @public
+ */
+export function resolveCloseSize(
+  orderSize: number,
+  positionSize: number
+): number {
+  if (orderSize === 0) {
+    return positionSize
+  }
+  return Math.min(orderSize, positionSize)
+}
+
+/**
+ * Expected rPnL for a resting limit order against a matching position.
+ *
+ * Reducing requires opposite sides (long position + SELL, short position +
+ * BUY). Same-side orders add to the position and have no rPnL → `null`.
+ *
+ * @returns Realised PnL if the order would reduce the position, otherwise
+ *   `null`.
+ * @public
+ */
+export function expectedRealizedPnlForOpenOrder(
+  order: OpenOrder,
+  position: Position | undefined
+): number | null {
+  if (!position) {
+    return null
+  }
+
+  const isLong = position.side === PositionSide.LONG
+  const reducesPosition =
+    (isLong && order.side === OrderSide.SELL) ||
+    (!isLong && order.side === OrderSide.BUY)
+  if (!reducesPosition) {
+    return null
+  }
+
+  const limitPrice = Number.parseFloat(order.price)
+  const entryPrice = Number.parseFloat(position.entryPrice)
+  const orderSize = Math.abs(Number.parseFloat(order.size))
+  const positionSize = Math.abs(Number.parseFloat(position.size))
+  if (
+    !Number.isFinite(limitPrice) ||
+    !Number.isFinite(entryPrice) ||
+    !Number.isFinite(orderSize) ||
+    !Number.isFinite(positionSize) ||
+    positionSize <= 0
+  ) {
+    return null
+  }
+
+  const closeSize = resolveCloseSize(orderSize, positionSize)
+  return realizedPnlOnClose({
+    entryPrice,
+    closePrice: limitPrice,
+    closeSize,
+    isLong,
+  })
+}
+
+/**
+ * Expected rPnL for a TP/SL trigger order against a matching position.
+ *
+ * A trigger order is by construction a closing leg — its direction is the
+ * opposite of the position's. With no matching position there is nothing to
+ * close, so rPnL is `null`. The trigger price (always present on the SDK
+ * `TriggerOrder` shape) is used as the rPnL price; the optional `limitPrice`
+ * for STOP_LIMIT / TAKE_PROFIT_LIMIT is the post-trigger limit, not the rPnL
+ * price.
+ * @public
+ */
+export function expectedRealizedPnlForTriggerOrder(
+  order: TriggerOrder,
+  position: Position | undefined
+): number | null {
+  if (!position) {
+    return null
+  }
+
+  const isLong = position.side === PositionSide.LONG
+  const triggerPrice = Number.parseFloat(order.triggerPrice)
+  const entryPrice = Number.parseFloat(position.entryPrice)
+  const orderSize = Math.abs(Number.parseFloat(order.size))
+  const positionSize = Math.abs(Number.parseFloat(position.size))
+  if (
+    !Number.isFinite(triggerPrice) ||
+    !Number.isFinite(entryPrice) ||
+    !Number.isFinite(orderSize) ||
+    !Number.isFinite(positionSize) ||
+    positionSize <= 0
+  ) {
+    return null
+  }
+
+  const closeSize = resolveCloseSize(orderSize, positionSize)
+  return realizedPnlOnClose({
+    entryPrice,
+    closePrice: triggerPrice,
+    closeSize,
+    isLong,
+  })
+}

package/src/utils/parse.ts

@@ -0,0 +1,30 @@
+/**
+ * Parse a string to a float, stripping common formatting artefacts.
+ *
+ * Handles:
+ * - Currency prefixes/suffixes ($, USD, etc.)
+ * - Explicit sign prefixes (+/-)
+ * - Thousands separators (commas)
+ * - Percentage suffixes (%)
+ * - Whitespace
+ *
+ * @param value - The string to parse
+ * @returns Parsed number; `0` for empty/blank input, `NaN` when a non-empty
+ *   string contains no parseable number
+ * @example
+ * ```ts
+ * stringToFloat('$1,234.50') // 1234.5
+ * stringToFloat('') // 0
+ * ```
+ * @public
+ */
+export function stringToFloat(value: string): number {
+  if (!value) {
+    return 0
+  }
+  const cleaned = value.trim().replace(/[$%]/g, '').replace(/,/g, '').trim()
+  if (!cleaned) {
+    return 0
+  }
+  return parseFloat(cleaned)
+}

package/src/utils/positionMath.ts

@@ -0,0 +1,149 @@
+/**
+ * Pure-function helpers for predicting how a perp position changes after a
+ * fill.
+ *
+ * Sign convention: long = +1, short = -1. Sizes passed to these helpers are
+ * always non-negative magnitudes; direction is carried by `isLong`.
+ */
+
+/**
+ * Direction sign for a position.
+ *
+ * @param isLong - True for long positions, false for short.
+ * @returns +1 for long, -1 for short.
+ * @public
+ */
+export function directionSign(isLong: boolean): 1 | -1 {
+  return isLong ? 1 : -1
+}
+
+/**
+ * Estimated liquidation price for an isolated-margin position, parameterised
+ * by the venue's maintenance margin rate.
+ *
+ * Standard isolated-margin model (new position, no existing exposure):
+ *   margin_per_unit      = entryPrice / leverage
+ *   maintenance_per_unit = entryPrice * mmr
+ *   margin_available     = margin_per_unit - maintenance_per_unit
+ *   liq_price            = entryPrice - side * margin_available / (1 - mmr * side)
+ *
+ * For existing positions, prefer `Position.liquidationPrice` from the venue.
+ *
+ * @param maintenanceMarginRate - Venue maintenance margin rate as a fraction
+ *   (e.g. 0.01 = 1%).
+ * @returns Estimated liquidation price, or undefined if the inputs cannot
+ *   produce one (zero leverage, degenerate denominator).
+ * @public
+ */
+export function estimateIsolatedLiquidationPrice(params: {
+  entryPrice: number
+  leverage: number
+  isLong: boolean
+  maintenanceMarginRate: number
+}): number | undefined {
+  const { entryPrice, leverage, isLong, maintenanceMarginRate } = params
+  if (leverage === 0) {
+    return undefined
+  }
+  const side = directionSign(isLong)
+  const denominator = 1 - maintenanceMarginRate * side
+  if (denominator === 0) {
+    return undefined
+  }
+  const marginAvailable = entryPrice * (1 / leverage - maintenanceMarginRate)
+  return entryPrice - (side * marginAvailable) / denominator
+}
+
+/**
+ * Predicted average entry price after adding to an existing position.
+ *
+ * Weighted average of the current entry and the new fill price, weighted by
+ * the size of each leg in coin units. Both legs assumed in the same direction
+ * (this helper is for adding to, not flipping, a position).
+ *
+ * @param currentSize - Existing position size in coin units (>= 0).
+ * @param currentEntry - Existing position's average entry price.
+ * @param addSize - Size being added in coin units (>= 0).
+ * @param fillPrice - Price the new size is expected to fill at (mid for
+ *   market, limitPrice for limit orders).
+ * @returns The new weighted-average entry price, or undefined if the inputs
+ *   cannot produce a valid average (zero combined size, non-finite values).
+ * @public
+ */
+export function predictAverageEntryPrice(params: {
+  currentSize: number
+  currentEntry: number
+  addSize: number
+  fillPrice: number
+}): number | undefined {
+  const { currentSize, currentEntry, addSize, fillPrice } = params
+  const totalSize = currentSize + addSize
+  if (totalSize <= 0) {
+    return undefined
+  }
+  if (!Number.isFinite(currentEntry) || !Number.isFinite(fillPrice)) {
+    return undefined
+  }
+  return (currentSize * currentEntry + addSize * fillPrice) / totalSize
+}
+
+/**
+ * Predicted effective leverage after adding margin and notional.
+ *
+ * leverage = totalNotional / totalMargin. The caller computes notional from
+ * size and price (`calculateNotionalValue`) and supplies the additional
+ * margin the user is about to put up.
+ *
+ * @returns The new effective leverage, or undefined if total margin is
+ *   non-positive.
+ * @public
+ */
+export function predictNewLeverage(params: {
+  currentNotional: number
+  currentMargin: number
+  addNotional: number
+  addMargin: number
+}): number | undefined {
+  const { currentNotional, currentMargin, addNotional, addMargin } = params
+  const totalMargin = currentMargin + addMargin
+  if (totalMargin <= 0) {
+    return undefined
+  }
+  return (currentNotional + addNotional) / totalMargin
+}
+
+/**
+ * Predicted unrealised PnL at the current mark price.
+ *
+ * `pnl = (markPrice - entryPrice) * size * directionSign(isLong)`
+ *
+ * @param size - Position size as a non-negative magnitude.
+ * @public
+ */
+export function predictUnrealizedPnl(params: {
+  entryPrice: number
+  markPrice: number
+  size: number
+  isLong: boolean
+}): number {
+  const { entryPrice, markPrice, size, isLong } = params
+  return (markPrice - entryPrice) * size * directionSign(isLong)
+}
+
+/**
+ * Realised PnL on the portion of a position being closed.
+ *
+ * `rPnl = (closePrice - entryPrice) * closeSize * directionSign(isLong)`
+ *
+ * @param closeSize - Size being closed as a non-negative magnitude.
+ * @public
+ */
+export function realizedPnlOnClose(params: {
+  entryPrice: number
+  closePrice: number
+  closeSize: number
+  isLong: boolean
+}): number {
+  const { entryPrice, closePrice, closeSize, isLong } = params
+  return (closePrice - entryPrice) * closeSize * directionSign(isLong)
+}

package/src/utils/signTypedData.ts

@@ -0,0 +1,41 @@
+import type { PerpsTypedData } from '@lifi/perps-types'
+import type { Account, Hex, WalletClient } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+
+/**
+ * Sign EIP-712 typed data with a raw private key (agent keypair).
+ *
+ * @public
+ */
+export async function signTypedData(
+  privateKey: Hex,
+  typedData: PerpsTypedData
+): Promise<Hex> {
+  return privateKeyToAccount(privateKey).signTypedData({
+    domain: typedData.domain,
+    types: typedData.types,
+    primaryType: typedData.primaryType,
+    message: typedData.message,
+  })
+}
+
+/**
+ * Sign EIP-712 typed data with an externally-provided WalletClient. Works
+ * with browser wallets (wagmi), private keys, mnemonics — any viem
+ * WalletClient. Used by provider plugins to sign the EIP712 USER arm with the
+ * end-user's wallet.
+ *
+ * @public
+ */
+export async function signTypedDataWithSigner(
+  userWallet: WalletClient<any, any, Account>,
+  typedData: PerpsTypedData
+): Promise<Hex> {
+  return userWallet.signTypedData({
+    account: userWallet.account,
+    domain: typedData.domain,
+    types: typedData.types,
+    primaryType: typedData.primaryType,
+    message: typedData.message,
+  })
+}

package/src/utils/sleep.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve after `ms` milliseconds.
+ *
+ * @internal
+ */
+export const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms))

package/src/utils/units.ts

@@ -0,0 +1,39 @@
+/**
+ * Token unit conversion utilities.
+ */
+
+import { formatUnits } from 'viem'
+
+/**
+ * Convert a base-unit amount (bigint string) to a human-readable decimal string.
+ *
+ * @param amount - Amount in base units (e.g. "1000000" for 1 USDC)
+ * @param decimals - Token decimals (e.g. 6 for USDC)
+ * @returns Decimal string (e.g. "1.0"); `"0"` when `amount` is not a valid
+ *   bigint
+ * @example
+ * ```ts
+ * fromBaseUnits('1000000', 6) // '1'
+ * ```
+ * @public
+ */
+export function fromBaseUnits(amount: string, decimals: number): string {
+  try {
+    return formatUnits(BigInt(amount), decimals)
+  } catch {
+    return '0'
+  }
+}
+
+/**
+ * Convert a base-unit amount to a number.
+ *
+ * @param amount - Amount in base units
+ * @param decimals - Token decimals
+ * @returns Numeric value, or 0 if parsing fails
+ * @public
+ */
+export function fromBaseUnitsNumber(amount: string, decimals: number): number {
+  const value = Number(fromBaseUnits(amount, decimals))
+  return Number.isFinite(value) ? value : 0
+}