@lifi/perps-sdk 21.1.0 → 23.0.0

package/dist/types/wire/orderAmounts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orderAmounts.d.ts","sourceRoot":"","sources":["../../../src/wire/orderAmounts.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAElB,KAAK,MAAM,EAEZ,MAAM,mBAAmB,CAAA;AAI1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAG1D,cAAc;AACd,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;IACpC,MAAM,EAAE,aAAa,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,aAAa,CAAA;IACpB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,cAAc;AACd,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,MAAM,EAAE,aAAa,CAAA;IACrB,uCAAuC;IACvC,IAAI,EAAE,aAAa,CAAA;IACnB,oCAAoC;IACpC,QAAQ,EAAE,aAAa,CAAA;CACxB;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,iBAAiB,GACvB,YAAY,GAAG,IAAI,CAqDrB"}
+{"version":3,"file":"orderAmounts.d.ts","sourceRoot":"","sources":["../../../src/wire/orderAmounts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAI9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAG1D,cAAc;AACd,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;IACpC,MAAM,EAAE,aAAa,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,aAAa,CAAA;CACrB;AAED,cAAc;AACd,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAA;IACrB,sEAAsE;IACtE,IAAI,EAAE,aAAa,CAAA;IACnB,qDAAqD;IACrD,QAAQ,EAAE,aAAa,CAAA;CACxB;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,iBAAiB,GACvB,YAAY,GAAG,IAAI,CAiCrB"}

package/dist/types/wire/withdraw.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withdraw.d.ts","sourceRoot":"","sources":["../../../src/wire/withdraw.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAGjE;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,IAAI,CACP,mBAAmB,EACnB,WAAW,GAAG,eAAe,GAAG,eAAe,CAChD,GACA,aAAa,CASf"}
+{"version":3,"file":"withdraw.d.ts","sourceRoot":"","sources":["../../../src/wire/withdraw.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAEjE;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,IAAI,CACP,mBAAmB,EACnB,WAAW,GAAG,eAAe,GAAG,eAAe,CAChD,GACA,aAAa,CASf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk",
-  "version": "21.1.0",
+  "version": "23.0.0",
   "description": "LI.FI Perps SDK for perpetuals trading",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -46,7 +46,7 @@
     "big.js": "^7.0.1",
     "partysocket": "^1.1.19",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^19.0.0"
+    "@lifi/perps-types": "^20.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/client/PerpsClient.ts

@@ -7,6 +7,7 @@ import type {
   ActionStep,
   AvailableToTrade,
   CreateActionResponse,
+  DecimalString,
   ExecuteActionResponse,
   MarketRef,
   MarketSettings,
@@ -647,13 +648,16 @@ export class PerpsClient {
    *   backend account fetch fails.
    * @public
    */
-  async getAccount(params: {
-    provider: string
-    address: Address
-  }): Promise<GetAccountResult> {
+  async getAccount(
+    params: {
+      provider: string
+      address: Address
+    },
+    options?: SDKRequestOptions
+  ): Promise<GetAccountResult> {
     const plugin = this.requireProvider(params.provider)
     const [response, metadata] = await Promise.all([
-      fetchAccount(this.sdkClient, params),
+      fetchAccount(this.sdkClient, params, options),
       this.getProviderMetadata(params.provider),
     ])
     const settings = plugin.projectConfig(response.config, metadata.setup)
@@ -673,16 +677,19 @@ export class PerpsClient {
    * @throws {PerpsError} `Unauthorized` when the venue rejects the credential.
    * @public
    */
-  async getMarketSettings(params: {
-    provider: string
-    address: Address
-    market: MarketRef
-  }): Promise<MarketSettings> {
+  async getMarketSettings(
+    params: {
+      provider: string
+      address: Address
+      market: MarketRef
+    },
+    options?: SDKRequestOptions
+  ): Promise<MarketSettings> {
     const plugin = this.requireProvider(params.provider)
-    return plugin.getMarketSettings({
-      address: params.address,
-      market: params.market,
-    })
+    return plugin.getMarketSettings(
+      { address: params.address, market: params.market },
+      options
+    )
   }
 
   /**
@@ -753,7 +760,7 @@ export class PerpsClient {
    *   venue formula reads is malformed.
    * @public
    */
-  getPositionRemovableMargin(position: Position): string | undefined {
+  getPositionRemovableMargin(position: Position): DecimalString | undefined {
     return this.requireProvider(
       position.market.providerId
     ).positionRemovableMargin(position)
@@ -786,8 +793,12 @@ export class PerpsClient {
    *   plugin's existence probe fails.
    * @public
    */
-  async accountExists(provider: string, address: Address): Promise<boolean> {
-    return this.requireProvider(provider).accountExists({ address })
+  async accountExists(
+    provider: string,
+    address: Address,
+    options?: SDKRequestOptions
+  ): Promise<boolean> {
+    return this.requireProvider(provider).accountExists({ address }, options)
   }
 
   /**
@@ -801,10 +812,11 @@ export class PerpsClient {
    * @public
    */
   async getDepositFlow(
-    params: GetDepositFlowParams
+    params: GetDepositFlowParams,
+    options?: SDKRequestOptions
   ): Promise<DepositFlow | undefined> {
     const plugin = this.requireProvider(params.provider)
-    return plugin.getDepositFlow?.({ address: params.address })
+    return plugin.getDepositFlow?.({ address: params.address }, options)
   }
 
   /**
@@ -818,10 +830,11 @@ export class PerpsClient {
    * @public
    */
   async getWithdrawFlow(
-    params: GetWithdrawFlowParams
+    params: GetWithdrawFlowParams,
+    options?: SDKRequestOptions
   ): Promise<WithdrawFlow | undefined> {
     const plugin = this.requireProvider(params.provider)
-    return plugin.getWithdrawFlow?.({ address: params.address })
+    return plugin.getWithdrawFlow?.({ address: params.address }, options)
   }
 
   /**
@@ -844,12 +857,14 @@ export class PerpsClient {
    * @public
    */
   async getWithdrawableBalances(
-    params: GetWithdrawableBalancesParams
+    params: GetWithdrawableBalancesParams,
+    options?: SDKRequestOptions
   ): Promise<WithdrawableBalance[] | undefined> {
     const plugin = this.requireProvider(params.provider)
-    const rows = await plugin.getWithdrawableBalances?.({
-      address: params.address,
-    })
+    const rows = await plugin.getWithdrawableBalances?.(
+      { address: params.address },
+      options
+    )
     if (rows === undefined) {
       return undefined
     }
@@ -1448,7 +1463,7 @@ export class PerpsClient {
     address: Address
     market: MarketRef
     action: 'add' | 'remove'
-    amount: string
+    amount: DecimalString
   }): Promise<ExecuteActionResponse> {
     return this.execute({
       ...params,

package/src/decimal/convert.ts

@@ -2,7 +2,7 @@ import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
 import { formatUnits } from 'viem'
 import { PerpsError } from '../errors/PerpsError.js'
-import { parseDecimal } from './parse.js'
+import { requireDecimal } from './requireDecimal.js'
 
 /**
  * Off-grid resolution for {@link decimalToBaseUnits}:
@@ -14,19 +14,14 @@ import { parseDecimal } from './parse.js'
  */
 export type BaseUnitsRounding = 'truncate' | 'round'
 
-/**
- * @deprecated Use `BaseUnitsRounding`. Removed in the next major.
- */
-export type ScaleToIntegerPolicy = BaseUnitsRounding
-
 /**
  * Scale a decimal string to a scaled integer in exact decimal arithmetic — an
  * on-grid input maps to its exact scaled integer with no binary float
  * artifacts (`'0.29'` at 2 decimals is 29, never 28). Off-grid input resolves
  * per `rounding`; there is no silent default.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a decimal
- *   numeric string, `decimals` is not a non-negative integer, or the scaled
+ * @throws {PerpsError} `ValidationError` when `value` is not a
+ *   {@link DecimalString}, `decimals` is not a non-negative integer, or the scaled
  *   result's magnitude exceeds `Number.MAX_SAFE_INTEGER`.
  * @public
  */
@@ -41,16 +36,7 @@ export const decimalToBaseUnits = (
       `Invalid decimals for integer scaling: ${decimals}`
     )
   }
-  let parsed: Big
-  try {
-    parsed = new Big(value)
-  } catch {
-    throw new PerpsError(
-      PerpsErrorCode.ValidationError,
-      `Invalid decimal string for integer scaling: '${value}'`
-    )
-  }
-  const scaled = parsed
+  const scaled = requireDecimal(value, 'decimalToBaseUnits(value)')
     .times(new Big(10).pow(decimals))
     .round(0, rounding === 'truncate' ? Big.roundDown : Big.roundHalfUp)
   if (scaled.abs().gt(Number.MAX_SAFE_INTEGER)) {
@@ -62,17 +48,15 @@ export const decimalToBaseUnits = (
   return scaled.toNumber()
 }
 
-/**
- * @deprecated Use `decimalToBaseUnits`. Removed in the next major.
- */
-export const scaleToInteger = decimalToBaseUnits
+const BASE_UNITS_PATTERN = /^-?\d+$/
 
 /**
- * Convert a base-unit amount (bigint string) to a decimal string.
+ * Convert a base-unit amount (integer string) to a 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; `"0"` when `amount` is not a valid bigint
+ * @throws {PerpsError} `ValidationError` when `amount` is not an integer
+ *   string, or `decimals` is not a non-negative integer.
  * @example
  * ```ts
  * baseUnitsToDecimal('1000000', 6) // '1'
@@ -80,27 +64,22 @@ export const scaleToInteger = decimalToBaseUnits
  * @public
  */
 export function baseUnitsToDecimal(
-  amount: string,
+  amount: DecimalString,
   decimals: number
 ): DecimalString {
-  try {
-    return formatUnits(BigInt(amount), decimals)
-  } catch {
-    return '0'
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid \`baseUnitsToDecimal(decimals)\`: ${decimals} is not a non-negative integer.`
+    )
   }
-}
-
-/**
- * @deprecated Use `baseUnitsToDecimal`. Removed in the next major.
- */
-export const fromBaseUnits = baseUnitsToDecimal
-
-/**
- * @deprecated Compose `parseDecimal(baseUnitsToDecimal(...))`. Removed in the
- * next major.
- */
-export function fromBaseUnitsNumber(amount: string, decimals: number): number {
-  return parseDecimal(baseUnitsToDecimal(amount, decimals)) ?? 0
+  if (!BASE_UNITS_PATTERN.test(amount)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid \`baseUnitsToDecimal(amount)\`: '${amount}' is not an integer base-unit string.`
+    )
+  }
+  return formatUnits(BigInt(amount), decimals)
 }
 
 /**
@@ -114,8 +93,8 @@ export function fromBaseUnitsNumber(amount: string, decimals: number): number {
  * float artifact: `'0.01'` at 18 decimals gives
  * `'0.010000000000000000'`, which `Number#toFixed` cannot.
  *
- * @throws {PerpsError} `ValidationError` when `value` is not a decimal
- *   numeric string, or `decimals` is not a non-negative integer.
+ * @throws {PerpsError} `ValidationError` when `value` is not a
+ *   {@link DecimalString}, or `decimals` is not a non-negative integer.
  * @public
  */
 export function truncateDecimal(
@@ -128,16 +107,10 @@ export function truncateDecimal(
       `Invalid decimals for truncation: ${decimals}`
     )
   }
-  let parsed: Big
-  try {
-    parsed = new Big(value)
-  } catch {
-    throw new PerpsError(
-      PerpsErrorCode.ValidationError,
-      `Invalid decimal string for truncation: '${value}'`
-    )
-  }
-  const truncated = parsed.round(decimals, Big.roundDown)
+  const truncated = requireDecimal(value, 'truncateDecimal(value)').round(
+    decimals,
+    Big.roundDown
+  )
   // big.js carries the sign through a round to zero; '-0.00' is not a spelling.
   return (truncated.eq(0) ? new Big(0) : truncated).toFixed(decimals)
 }

package/src/decimal/format.ts

@@ -1,3 +1,5 @@
+import type { DecimalString } from '@lifi/perps-types'
+
 /**
  * Options shared by the human-facing display formatters.
  *
@@ -28,7 +30,7 @@ export type RoundingMode = 'halfUp' | 'floor'
 
 const DEFAULT_PLACEHOLDER = '—'
 
-type FormatInput = number | string | null | undefined
+type FormatInput = number | DecimalString | string | null | undefined
 
 /**
  * Extra decimal places used to normalise IEEE-754 representation noise before

package/src/decimal/parse.ts

@@ -1,4 +1,4 @@
-import type { DecimalString } from '@lifi/perps-types'
+import { DECIMAL_PATTERN, type DecimalString } from '@lifi/perps-types'
 
 /**
  * Parse a string to a float, stripping common formatting artefacts.
@@ -24,11 +24,6 @@ function toFloat(value: string): number {
   return parseFloat(cleaned)
 }
 
-/**
- * @deprecated Use `parseDecimal`. Removed in the next major.
- */
-export const stringToFloat = toFloat
-
 const FORMATTED_NUMBER =
   /^(?:[+-]\s*)?(?:\$\s*)?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?(?:\s*(?:%|USD))?$/i
 
@@ -54,3 +49,12 @@ export function parseDecimal(
   const parsed = toFloat(value)
   return Number.isFinite(parsed) ? parsed : undefined
 }
+
+/**
+ * Narrows an unknown value to a {@link DecimalString}.
+ *
+ * @public
+ */
+export function isDecimalString(value: unknown): value is DecimalString {
+  return typeof value === 'string' && DECIMAL_PATTERN.test(value)
+}

package/src/{wire → decimal}/requireDecimal.ts

@@ -1,13 +1,10 @@
-import {
-  type DecimalString,
-  isDecimalString,
-  PerpsErrorCode,
-} from '@lifi/perps-types'
+import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
 import { PerpsError } from '../errors/PerpsError.js'
+import { isDecimalString } from './parse.js'
 
 /**
- * Parse a wire-tier decimal input, naming the field it came from when the
+ * Parse a decimal input, naming the field it came from when the
  * value breaks the {@link DecimalString} contract, so a malformed amount
  * fails at the SDK boundary instead of inside big.js.
  *

package/src/index.ts

@@ -17,17 +17,11 @@ export {
 } from './client/createPerpsClient.js'
 export { PerpsClient } from './client/PerpsClient.js'
 export { requireProvider } from './client/requireProvider.js'
-export type {
-  BaseUnitsRounding,
-  ScaleToIntegerPolicy,
-} from './decimal/convert.js'
+export type { BaseUnitsRounding } from './decimal/convert.js'
 export {
   baseUnitsToDecimal,
   decimalToBaseUnits,
-  fromBaseUnits,
-  fromBaseUnitsNumber,
   numberToDecimalString,
-  scaleToInteger,
   truncateDecimal,
 } from './decimal/convert.js'
 export type { FormatOptions, RoundingMode } from './decimal/format.js'
@@ -39,7 +33,7 @@ export {
   formatSignedUsd,
   formatUsd,
 } from './decimal/format.js'
-export { parseDecimal, stringToFloat } from './decimal/parse.js'
+export { isDecimalString, parseDecimal } from './decimal/parse.js'
 export { PerpsErrorMessage } from './errors/constants.js'
 export { PerpsError } from './errors/PerpsError.js'
 export {
@@ -52,18 +46,13 @@ export {
   applySlippage,
   buildQuote,
   calculateExpectedPnl,
-  calculatePositionSize,
   calculateRealizedPnlPercent,
   calculateSize,
   calculateTriggerPercent,
   calculateTriggerPrice,
   estimateFees,
   estimateRealizedPnl,
-  expectedRealizedPnlForOpenOrder,
-  expectedRealizedPnlForTriggerOrder,
   findMatchingPosition,
-  percentFromPrice,
-  priceFromPercent,
   resolveCloseSize,
   walkOrderbook,
 } from './math/order.js'
@@ -75,18 +64,12 @@ export {
   calculateRequiredMargin,
   calculateRoe,
   calculateUnrealizedPnl,
-  directionSign,
-  effectiveLeverage,
   estimateAverageEntryPrice,
-  estimateIsolatedLiquidationPrice,
   estimateLiquidationPrice,
   estimateNewLeverage,
   estimateUnrealizedPnl,
-  liquidationDistancePercent,
-  predictAverageEntryPrice,
-  predictNewLeverage,
-  predictUnrealizedPnl,
-  realizedPnlOnClose,
+  positionSupportsMarginAdjustment,
+  positionSupportsMarginRemoval,
   wouldImmediatelyLiquidate,
 } from './math/position.js'
 // Registries

package/src/math/fills.ts

@@ -1,4 +1,8 @@
-import { FillClassification, OrderSide } from '@lifi/perps-types'
+import {
+  type DecimalString,
+  FillClassification,
+  OrderSide,
+} from '@lifi/perps-types'
 import { parseDecimal } from '../decimal/parse.js'
 
 /**
@@ -19,9 +23,9 @@ export { FillClassification }
  * @public
  */
 export function classifyFillFromPosition(
-  startPosition: string,
+  startPosition: DecimalString,
   side: string,
-  sz: string
+  sz: DecimalString
 ): FillClassification {
   const start = parseFloat(startPosition)
   const delta = side === 'B' ? parseFloat(sz) : -parseFloat(sz)
@@ -66,7 +70,7 @@ export function classifyFillFromPosition(
  */
 export function classifyFill(
   side: OrderSide,
-  realizedPnl: string | null | undefined
+  realizedPnl: DecimalString | null | undefined
 ): FillClassification {
   const isClose = realizedPnl != null && parseDecimal(realizedPnl) !== 0
   if (side === OrderSide.BUY) {

package/src/math/order.ts

@@ -22,6 +22,7 @@ import {
 } from '@lifi/perps-types'
 import type Big from 'big.js'
 import { areFinite, DivBig } from '../decimal/big.js'
+import { numberToDecimalString } from '../decimal/convert.js'
 import { PerpsError } from '../errors/PerpsError.js'
 import {
   isActiveOrderStatus,
@@ -57,11 +58,6 @@ export function calculateSize(
   return new DivBig(marginUsd).times(leverage).div(price).toNumber()
 }
 
-/**
- * @deprecated Use `calculateSize`. Removed in the next major.
- */
-export const calculatePositionSize = calculateSize
-
 /**
  * Estimate trading fees.
  *
@@ -176,11 +172,6 @@ export function calculateTriggerPrice(
   return (isLong ? entry.plus(priceDelta) : entry.minus(priceDelta)).toNumber()
 }
 
-/**
- * @deprecated Use `calculateTriggerPrice`. Removed in the next major.
- */
-export const priceFromPercent = calculateTriggerPrice
-
 /**
  * Calculate the percentage gain/loss a trigger price realises.
  *
@@ -208,11 +199,6 @@ export function calculateTriggerPercent(
   return priceDiff.div(entryPrice).times(leverage).times(100).toNumber()
 }
 
-/**
- * @deprecated Use `calculateTriggerPercent`. Removed in the next major.
- */
-export const percentFromPrice = calculateTriggerPercent
-
 /**
  * Calculate realized PnL as a percentage of position value at close.
  *
@@ -334,7 +320,8 @@ interface BuildQuoteInput {
  * the market's `funding` (`null` for spot, which has none).
  *
  * @throws {PerpsError} `ValidationError` when a book level does not parse to
- *   a finite number — see {@link walkOrderbook}.
+ *   a finite number — see {@link walkOrderbook} — or when a quoted figure is
+ *   not finite (a non-finite `sizeUsd`, mark price or taker fee).
  * @public
  */
 export function buildQuote(input: BuildQuoteInput): Quote {
@@ -356,14 +343,14 @@ export function buildQuote(input: BuildQuoteInput): Quote {
     marketId: market.id,
     type: input.type,
     side,
-    sizeUsd: sizeUsd.toString(),
-    baseSize: walk.baseSize.toString(),
+    sizeUsd: numberToDecimalString(sizeUsd),
+    baseSize: numberToDecimalString(walk.baseSize),
     markPrice: price.markPrice,
-    expectedFillPrice: walk.vwap.toString(),
-    priceImpactBps: priceImpactBps.toString(),
+    expectedFillPrice: numberToDecimalString(walk.vwap),
+    priceImpactBps: numberToDecimalString(priceImpactBps),
     feeTier,
     isDefaultFeeTier: true,
-    feeUsd: feeUsd.toString(),
+    feeUsd: numberToDecimalString(feeUsd),
     funding: price.funding ?? null,
     insufficientLiquidity: walk.insufficientLiquidity,
     timestamp: input.timestamp,
@@ -530,13 +517,3 @@ export function estimateRealizedPnl(
   }
   return null
 }
-
-/**
- * @deprecated Use `estimateRealizedPnl`. Removed in the next major.
- */
-export const expectedRealizedPnlForOpenOrder = regularOrderRealizedPnl
-
-/**
- * @deprecated Use `estimateRealizedPnl`. Removed in the next major.
- */
-export const expectedRealizedPnlForTriggerOrder = triggerOrderRealizedPnl