@lifi/perps-sdk 0.1.1-alpha.8 → 0.2.0-alpha.0

package/src/utils/hyperliquid/liquidation.ts

@@ -0,0 +1,71 @@
+/**
+ * Hyperliquid-specific liquidation price calculation.
+ *
+ * Uses the exact formula from Hyperliquid docs:
+ * https://hyperliquid.gitbook.io/hyperliquid-docs/trading/liquidations
+ *
+ * liq_price = price - side * margin_available / position_size / (1 - l * side)
+ *
+ * Where:
+ * - l = 1 / (2 * maxLeverage) (maintenance margin fraction)
+ * - side = 1 (long) or -1 (short)
+ * - margin_available = isolated_margin - maintenance_margin_required
+ */
+
+/**
+ * Calculate the maintenance margin fraction for a Hyperliquid asset.
+ *
+ * Maintenance margin is half of the initial margin at max leverage.
+ *
+ * @param maxLeverage - Maximum leverage for the asset (e.g., 50 for BTC)
+ * @returns Maintenance margin fraction (e.g., 0.01 for 50x max leverage),
+ *   or undefined if maxLeverage is zero
+ */
+export function calculateMaintenanceMarginRate(
+  maxLeverage: number
+): number | undefined {
+  if (maxLeverage === 0) {
+    return undefined
+  }
+  return 1 / (2 * maxLeverage)
+}
+
+/**
+ * Calculate liquidation price using the exact Hyperliquid formula.
+ *
+ * For isolated margin, new position prediction. For existing positions,
+ * prefer Position.liquidationPrice from the API.
+ *
+ * Formula derivation (isolated margin, single position):
+ *   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)
+ *
+ * Where mmr = 1 / (2 * maxLeverage).
+ *
+ * @param entryPrice - Position entry price
+ * @param leverage - User-selected leverage (e.g., 10)
+ * @param isLong - True if long position, false if short
+ * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Determines
+ *   the maintenance margin rate: mmr = 1 / (2 * maxLeverage)
+ * @returns Estimated liquidation price, or undefined if inputs are invalid
+ */
+export function calculateLiquidationPrice(
+  entryPrice: number,
+  leverage: number,
+  isLong: boolean,
+  maxLeverage: number
+): number | undefined {
+  if (leverage === 0 || maxLeverage === 0) {
+    return undefined
+  }
+  const mmr = 1 / (2 * maxLeverage)
+  const side = isLong ? 1 : -1
+  const denominator = 1 - mmr * side
+  if (denominator === 0) {
+    return undefined
+  }
+  const marginAvailable = entryPrice * (1 / leverage - mmr)
+  return entryPrice - (side * marginAvailable) / denominator
+}

package/src/utils/hyperliquid/orderFormatting.ts

@@ -0,0 +1,96 @@
+/**
+ * Hyperliquid order size and price formatting for exchange submission.
+ *
+ * These encode Hyperliquid-specific order submission rules. Getting size/price
+ * formatting wrong causes rejected orders.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size
+ */
+
+import { stringToFloat } from '../parse.js'
+
+/**
+ * Max combined decimals (size + price) enforced by Hyperliquid.
+ * Perps: 6, Spot: 8
+ */
+const MAX_DECIMALS_PERPS = 6
+const MAX_DECIMALS_SPOT = 8
+
+function getMaxDecimals(market?: string): number {
+  return market === 'spot' ? MAX_DECIMALS_SPOT : MAX_DECIMALS_PERPS
+}
+
+/**
+ * Derive the maximum number of price decimal places for a given asset.
+ *
+ * @param szDecimals - The asset's szDecimals (from market meta)
+ * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
+ * @returns Maximum allowed price decimals
+ */
+export function getMaxPriceDecimals(
+  szDecimals: number,
+  market?: string
+): number {
+  return Math.max(0, getMaxDecimals(market) - szDecimals)
+}
+
+/**
+ * Format a size value for order submission.
+ *
+ * Per Hyperliquid docs (tick-and-lot-size):
+ * - Size must be rounded to the asset's szDecimals
+ * - Trailing zeroes must be removed for signing
+ *
+ * @param size - The size value to format
+ * @param szDecimals - Number of decimal places allowed for this asset (from meta)
+ * @returns Size as a string with correct precision, no trailing zeros
+ */
+export function formatOrderSize(size: number, szDecimals: number): string {
+  // Truncate (don't round up) to avoid exceeding available balance
+  const multiplier = 10 ** szDecimals
+  const truncated = Math.floor(size * multiplier) / multiplier
+  // Remove trailing zeros by round-tripping through stringToFloat
+  return stringToFloat(truncated.toFixed(szDecimals)).toString()
+}
+
+/**
+ * Format a price value for order submission.
+ *
+ * Per Hyperliquid docs (tick-and-lot-size):
+ * - Maximum 5 significant figures
+ * - Max decimals = MAX_DECIMALS - szDecimals (6 for perps, 8 for spot)
+ * - Integer prices always allowed regardless of significant figures
+ * - Trailing zeroes must be removed for signing
+ *
+ * @param price - The price value to format
+ * @param szDecimals - The asset's szDecimals (affects max price decimals)
+ * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
+ * @returns Price as a string with correct precision, no trailing zeros
+ */
+export function formatOrderPrice(
+  price: number,
+  szDecimals: number,
+  market?: string
+): string {
+  const maxPriceDecimals = getMaxPriceDecimals(szDecimals, market)
+
+  // Round to max allowed decimals
+  let rounded = stringToFloat(price.toFixed(maxPriceDecimals))
+
+  // Integer prices are always allowed regardless of significant figures
+  if (Number.isInteger(rounded)) {
+    return rounded.toString()
+  }
+
+  // Count significant figures (digits excluding leading zeros)
+  const absStr = Math.abs(rounded).toString().replace('.', '')
+  const sigFigs = absStr.replace(/^0+/, '').length
+
+  // If more than 5 significant figures, round to 5
+  if (sigFigs > 5) {
+    rounded = stringToFloat(rounded.toPrecision(5))
+  }
+
+  // Return without trailing zeros
+  return rounded.toString()
+}

package/src/utils/orderClassification.ts

@@ -0,0 +1,64 @@
+/**
+ * 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, 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.
+ */
+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.
+ */
+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.
+ */
+export function isTpSlOrder(order: Pick<OpenOrder, 'type'>): boolean {
+  return TP_TYPES.has(order.type) || SL_TYPES.has(order.type)
+}
+
+/**
+ * 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.
+ */
+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,130 @@
+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 asset, if any.
+ *
+ * @param assetId - The order's `asset.assetId`.
+ * @param positions - Open positions list (any symbol).
+ */
+export function findMatchingPosition(
+  assetId: string,
+  positions: readonly Position[]
+): Position | undefined {
+  return positions.find((p) => p.asset.assetId === assetId)
+}
+
+/**
+ * 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.
+ */
+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`.
+ */
+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.
+ */
+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,28 @@
+/**
+ * Robust string-to-number parsing utilities.
+ */
+
+/**
+ * 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, or NaN if the string contains no valid number
+ */
+export function stringToFloat(value: string): number {
+  if (!value) {
+    return 0
+  }
+  // Strip whitespace, currency symbols, thousands commas, and % suffix
+  const cleaned = value.trim().replace(/[$%]/g, '').replace(/,/g, '').trim()
+  if (!cleaned) {
+    return 0
+  }
+  return parseFloat(cleaned)
+}

package/src/utils/positionMath.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+export function directionSign(isLong: boolean): 1 | -1 {
+  return isLong ? 1 : -1
+}
+
+/**
+ * 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).
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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/request.ts

@@ -1,9 +1,9 @@
+import type { PerpsErrorBody } from '@lifi/perps-types'
 import { PerpsErrorCode } from '@lifi/perps-types'
 import type {
   PerpsBaseConfig,
   SDKRequestOptions,
 } from '../client/createPerpsClient.js'
-import { HTTPError } from '../errors/HTTPError.js'
 import { PerpsError } from '../errors/PerpsError.js'
 import { version } from '../version.js'
 import { sleep } from './sleep.js'
@@ -23,8 +23,7 @@ const DEFAULT_RETRIES = 1
  * @param options - Fetch options plus retries
  * @param sdkOptions - SDK-specific options (signal, etc.)
  * @returns Parsed JSON response
- * @throws {HTTPError} On non-2xx responses
- * @throws {PerpsError} On network or parsing errors
+ * @throws {PerpsError} On non-2xx responses or network errors
  */
 export async function request<T>(
   config: PerpsBaseConfig,
@@ -45,6 +44,10 @@ export async function request<T>(
     headers['x-lifi-api-key'] = config.apiKey
   }
 
+  if (sdkOptions?.lighterAuthToken) {
+    headers.Authorization = `Bearer ${sdkOptions.lighterAuthToken}`
+  }
+
   // Merge signal from sdkOptions into options
   let finalOptions: RequestInit = {
     ...options,
@@ -61,10 +64,13 @@ export async function request<T>(
     const response = await fetch(url, finalOptions)
 
     if (!response.ok) {
-      const error = new HTTPError(response, url)
-      await error.buildAdditionalDetails()
+      // Parse the backend's error body
+      let body: PerpsErrorBody | undefined
+      try {
+        body = await response.json()
+      } catch {}
 
-      // Retry on 5xx errors
+      // Retry on 5xx before throwing
       if (retries > 0 && response.status >= 500) {
         await sleep(500)
         return request<T>(
@@ -75,12 +81,25 @@ export async function request<T>(
         )
       }
 
+      // Rehydrate backend error — code/message/tool come straight from the response
+      const fallbackMessage = `Request failed with status code ${response.status}`
+      if (
+        body &&
+        typeof body.code === 'number' &&
+        typeof body.message === 'string'
+      ) {
+        const error = new PerpsError(body.code, body.message)
+        error.tool = body.tool ?? 'unknown'
+        throw error
+      }
+      const error = new PerpsError(PerpsErrorCode.DefaultError, fallbackMessage)
+      error.tool = 'unknown'
       throw error
     }
 
     return (await response.json()) as T
   } catch (error) {
-    if (error instanceof HTTPError || error instanceof PerpsError) {
+    if (error instanceof PerpsError) {
       throw error
     }
 

package/src/utils/signTypedData.ts

@@ -1,31 +1,35 @@
 import type { Hex, PerpsTypedData } from '@lifi/perps-types'
+import type { Account, WalletClient } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
 
 /**
- * Sign EIP-712 typed data with a private key.
- *
- * @param privateKey - The private key to sign with
- * @param typedData - The typed data to sign
- * @returns The signature as a hex string
- *
- * @example
- * ```ts
- * const signature = await signTypedData(agentPrivateKey, typedData)
- * ```
+ * Sign EIP-712 typed data with a raw private key (agent keypair).
  */
 export async function signTypedData(
   privateKey: Hex,
   typedData: PerpsTypedData
 ): Promise<Hex> {
-  const account = privateKeyToAccount(privateKey)
-
-  // viem's signTypedData expects the typed data in a specific format
-  const signature = await account.signTypedData({
+  return privateKeyToAccount(privateKey).signTypedData({
     domain: typedData.domain,
     types: typedData.types,
     primaryType: typedData.primaryType,
     message: typedData.message,
   })
+}
 
-  return signature
+/**
+ * Sign EIP-712 typed data with an externally-provided WalletClient. Works
+ * with browser wallets (wagmi), private keys, mnemonics — any viem
+ * WalletClient.
+ */
+export async function signTypedDataWithSigner(
+  signer: WalletClient<any, any, Account>,
+  typedData: PerpsTypedData
+): Promise<Hex> {
+  return signer.signTypedData({
+    domain: typedData.domain,
+    types: typedData.types,
+    primaryType: typedData.primaryType,
+    message: typedData.message,
+  })
 }

package/src/utils/units.ts

@@ -0,0 +1,32 @@
+/**
+ * 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")
+ */
+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
+ */
+export function fromBaseUnitsNumber(amount: string, decimals: number): number {
+  const value = Number(fromBaseUnits(amount, decimals))
+  return Number.isFinite(value) ? value : 0
+}

package/src/utils/validation.ts

@@ -0,0 +1,35 @@
+/**
+ * Order validation utilities.
+ */
+
+/**
+ * Validate margin input against available balance and exchange minimums.
+ *
+ * @param margin - Margin amount in USD
+ * @param _leverage - Position leverage (reserved for future use)
+ * @param availableBalance - Available balance, or null if unknown
+ * @param _feeRate - Fee rate as decimal, or null if unknown (reserved for future use)
+ * @param minMarginUsd - Minimum margin requirement in USD (exchange-specific)
+ * @returns Error code: 'insufficient' | 'below-minimum' | '' (valid)
+ */
+export function validateMargin(
+  margin: number,
+  _leverage: number,
+  availableBalance: number | null,
+  _feeRate: number | null,
+  minMarginUsd: number
+): string {
+  if (margin <= 0) {
+    return ''
+  }
+
+  if (availableBalance !== null && margin > availableBalance) {
+    return 'insufficient'
+  }
+
+  if (margin < minMarginUsd) {
+    return 'below-minimum'
+  }
+
+  return ''
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/perps-sdk'
-export const version = '0.1.1-alpha.8'
+export const version = '0.2.0-alpha.0'