@lifi/perps-sdk 5.0.0 → 6.1.0

package/src/types/provider.ts

@@ -10,11 +10,14 @@ import type {
   ActivityType,
   FillsResponse,
   Market,
+  MarketRef,
+  MarketSettings,
   Order,
   OrdersResponse,
   PerpsMarket,
   PerpsSigner,
   Position,
+  PositionMarginConstraints,
   PositionsResponse,
   ProviderAction,
   Quote,
@@ -40,22 +43,14 @@ import type { DepositFlow } from './deposit.js'
  */
 export interface PerpsSDKClient {
   readonly config: PerpsBaseConfig
-  /** The end-user's wallet — accepts any viem WalletClient (browser, private key, mnemonic). */
+  /** End-user wallet for USER-signed or on-chain EVM legs, when configured. */
   readonly userWallet?: PerpsClientSigner
-  /** Registered providers, bound to this client, in construction order. */
+  /** Providers bound to this client, in registration order. */
   readonly providers: PerpsProvider[]
-  /** Look up a registered bound {@link PerpsProvider} by its `type` key. */
+  /** Look up a bound provider by its wire `type` key. */
   getProvider(key: string): PerpsProvider | undefined
 }
 
-/**
- * Per-call context passed by `PerpsClient` to a provider's {@link
- * PerpsProvider.signActions} method. Carries the end-user's wallet (when
- * configured); providers that own a session credential (e.g. the Hyperliquid
- * agent keypair, Lighter's API key) resolve it internally.
- *
- * @public
- */
 /**
  * Progress for one on-chain leg of an `EVM_TX` batch (e.g. a native deposit's
  * `approve` then `deposit`). Emitted twice per leg: `submitted` once the wallet
@@ -65,19 +60,26 @@ export interface PerpsSDKClient {
  * @public
  */
 export interface SignActionProgress {
-  /** 0-based index of this leg within the batch. */
   index: number
-  /** Total legs in the batch. */
   total: number
   action: ActionType
-  /** Contract function the leg invokes, e.g. `"approve"` or the deposit method. */
   functionName: string
   chainId: number
+  /** Whether the transaction was broadcast or its receipt confirmed. */
   status: 'submitted' | 'confirmed'
   txHash: string
 }
 
+/**
+ * Per-call context passed by `PerpsClient` to a provider's
+ * {@link PerpsProviderPlugin.signActions} implementation. Carries the
+ * configured end-user wallet, descriptor-declared signer roles, an optional
+ * chain-switch helper, and an optional progress callback.
+ *
+ * @public
+ */
 export interface SignActionsContext {
+  /** End-user wallet used for USER-signed or EVM transaction legs. */
   userWallet?: PerpsClientSigner
   /**
    * The signing batch's declared signers, from the action's `ProviderAction`
@@ -139,8 +141,10 @@ export interface ActionSignerContribution {
  * @public
  */
 export interface LiquidationEstimateParams {
+  /** Entry price in quote currency per base unit. */
   entryPrice: number
   leverage: number
+  /** `true` for long, `false` for short. */
   isLong: boolean
 }
 
@@ -179,12 +183,26 @@ export interface ProviderGetDepositFlowParams {
  */
 export interface ProviderGetPositionsParams {
   address: Address
-  /** Optional filter — opaque `Market.id` (not `displaySymbol`). */
+  /** Optional opaque `Market.id` filter (not a display symbol). */
   marketId?: string
+  /** Maximum items returned; provider defaults and caps apply. */
   limit?: number
+  /** Opaque pagination cursor from the previous response. */
   cursor?: string
 }
 
+/**
+ * Read params for {@link PerpsProviderPlugin.getMarketSettings}.
+ *
+ * @public
+ */
+export interface ProviderGetMarketSettingsParams {
+  address: Address
+  /** The market's `id` and `categoryId`; the category identifies spot
+   * markets, which carry no venue leverage state. */
+  market: MarketRef
+}
+
 /**
  * Read params for {@link PerpsProvider.getOrders}.
  *
@@ -192,9 +210,11 @@ export interface ProviderGetPositionsParams {
  */
 export interface ProviderGetOrdersParams {
   address: Address
-  /** Optional filter — opaque `Market.id` (not `displaySymbol`). */
+  /** Optional opaque `Market.id` filter (not a display symbol). */
   marketId?: string
+  /** Maximum items returned; provider defaults and caps apply. */
   limit?: number
+  /** Opaque pagination cursor from the previous response. */
   cursor?: string
 }
 
@@ -205,6 +225,7 @@ export interface ProviderGetOrdersParams {
  */
 export interface ProviderGetOrderParams {
   address: Address
+  /** Venue order id, opaque to the SDK. */
   id: string
 }
 
@@ -215,9 +236,13 @@ export interface ProviderGetOrderParams {
  */
 export interface ProviderGetFillsParams {
   address: Address
+  /** Maximum items returned; provider defaults and caps apply. */
   limit?: number
+  /** Opaque pagination cursor from the previous response. */
   cursor?: string
+  /** Include fills at or after this Unix timestamp in milliseconds. */
   startTime?: number
+  /** Include fills at or before this Unix timestamp in milliseconds. */
   endTime?: number
 }
 
@@ -228,10 +253,15 @@ export interface ProviderGetFillsParams {
  */
 export interface ProviderGetActivityParams {
   address: Address
+  /** Maximum items returned; provider defaults and caps apply. */
   limit?: number
+  /** Opaque pagination cursor from the previous response. */
   cursor?: string
+  /** Include activity at or after this Unix timestamp in milliseconds. */
   startTime?: number
+  /** Include activity at or before this Unix timestamp in milliseconds. */
   endTime?: number
+  /** Optional filter for activity types. */
   type?: ActivityType[]
 }
 
@@ -242,11 +272,13 @@ export interface ProviderGetActivityParams {
  * @public
  */
 export interface ProviderGetQuoteParams {
-  /** Human `displaySymbol`, e.g. `"BTC"`. Resolved against the provider's own markets, scoped by `type`. */
+  /** Human `displaySymbol`, resolved against this provider and `type`. */
   symbol: string
+  /** Trade direction used to choose asks for buys or bids for sells. */
   side: QuoteSide
   /** USD notional to fill. */
   size: number
+  /** Product family used to disambiguate spot and perpetual markets. */
   type: TradeType
 }
 
@@ -350,6 +382,18 @@ export interface PerpsProviderPlugin {
     options?: SDKRequestOptions
   ): Promise<PositionsResponse>
 
+  /**
+   * The user's current venue-side settings for one market — the margin mode
+   * and leverage the next order on it will use. Optional because venues
+   * expose this unevenly: Hyperliquid reads it directly (`activeAssetData`),
+   * Lighter only reports it on an account's position row. `undefined` means
+   * the venue has nothing to read for this market.
+   */
+  getMarketSettings?(
+    params: ProviderGetMarketSettingsParams,
+    options?: SDKRequestOptions
+  ): Promise<MarketSettings | undefined>
+
   getOrders(
     params: ProviderGetOrdersParams,
     options?: SDKRequestOptions
@@ -436,6 +480,18 @@ export interface PerpsProviderPlugin {
     params: LiquidationEstimateParams
   ): number | undefined
 
+  /**
+   * Exact venue-owned constraints for changing `position`'s dedicated margin.
+   * Pure — providers normalize raw venue quantities onto the position before
+   * returning these inputs.
+   *
+   * @returns `undefined` when this position has no individual margin
+   *   adjustment (for example a cross position or a cross-only venue).
+   */
+  positionMarginConstraints(
+    position: Position
+  ): PositionMarginConstraints | undefined
+
   /**
    * Project a typed {@link AccountConfig} against the provider's `setup`
    * + `options` descriptors into `AccountConfigSetting[]`. Used by

package/src/utils/calculations.ts

@@ -169,41 +169,15 @@ export function effectiveLeverage(params: {
   return positionValueUsd / marginUsd
 }
 
-/**
- * Margin that can be removed from a position while keeping its leverage at or
- * below the asset's maximum.
- *
- * The minimum margin to stay within `maxLeverage` is the required margin for
- * the position's notional (see {@link calculateRequiredMargin}); anything above
- * that is removable.
- *
- * @param marginUsed - Margin currently backing the position in USD
- * @param positionValueUsd - Position notional value in USD
- * @param maxLeverage - Maximum leverage allowed for the asset
- * @returns Removable margin in USD (never negative); falls back to the full
- *   `marginUsed` when `maxLeverage` is zero (no constraint available)
- * @public
- */
-export function removableMargin(params: {
-  marginUsed: number
-  positionValueUsd: number
-  maxLeverage: number
-}): number {
-  const { marginUsed, positionValueUsd, maxLeverage } = params
-  if (maxLeverage === 0) {
-    return marginUsed
-  }
-  const minMargin = calculateRequiredMargin(positionValueUsd, maxLeverage)
-  return Math.max(0, marginUsed - minMargin)
-}
-
 /**
  * Signed expected PnL for a trigger price — see {@link calculateExpectedPnl}.
  *
  * @public
  */
 export interface ExpectedPnl {
+  /** Signed expected profit/loss in USD. */
   amount: number
+  /** Signed expected return as a percentage (10 means 10%). */
   percent: number
 }
 

package/src/utils/format.ts

@@ -19,7 +19,11 @@ export interface FormatOptions {
   rounding?: RoundingMode
 }
 
-/** Rounding mode for {@link FormatOptions.rounding}. */
+/**
+ * Rounding mode for {@link FormatOptions.rounding}.
+ *
+ * @public
+ */
 export type RoundingMode = 'halfUp' | 'floor'
 
 const DEFAULT_PLACEHOLDER = '—'

package/src/utils/orderClassification.ts

@@ -15,6 +15,11 @@ import {
 } from '@lifi/perps-types'
 import { stringToFloat } from './parse.js'
 
+/**
+ * Re-exported fill taxonomy used by {@link classifyFillFromPosition}.
+ *
+ * @public
+ */
 export { FillClassification }
 
 const TP_TYPES = new Set<OrderType>([

package/src/utils/transferMargin.ts

@@ -0,0 +1,98 @@
+import {
+  PerpsErrorCode,
+  type Position,
+  type PositionMarginConstraints,
+  positionSupportsMarginRemoval,
+} from '@lifi/perps-types'
+import Big from 'big.js'
+import { PerpsError } from '../errors/PerpsError.js'
+
+function positionAmount(value: string, field: string): Big {
+  try {
+    return new Big(value)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimal string on Position.${field}: '${value}'`
+    )
+  }
+}
+
+function constraintAmount(value: string, field: string): Big {
+  try {
+    return new Big(value)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid decimal string on PositionMarginConstraints.${field}: '${value}'`
+    )
+  }
+}
+
+function requirePositive(value: Big, field: string): Big {
+  if (value.lte(0)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `${field} must be greater than zero.`
+    )
+  }
+  return value
+}
+
+/**
+ * Exact inputs for {@link removableIsolatedMargin}.
+ *
+ * @public
+ */
+export interface RemovableIsolatedMarginParams {
+  position: Position
+  constraints: PositionMarginConstraints
+}
+
+/**
+ * Calculate margin that can be removed from an isolated position using the
+ * provider's exact retained-margin requirement. Position equity is allocated
+ * margin plus unrealized PnL.
+ *
+ * The result snaps down to the provider's accepted amount increment. Markets
+ * that are add-only and cross-margined positions return `'0'`.
+ *
+ * @throws {PerpsError} `ValidationError` for malformed, non-positive, or
+ *   inconsistent risk inputs.
+ * @public
+ */
+export function removableIsolatedMargin({
+  position,
+  constraints,
+}: RemovableIsolatedMarginParams): string {
+  if (!positionSupportsMarginRemoval(position)) {
+    return '0'
+  }
+
+  const marginUsed = requirePositive(
+    positionAmount(position.marginUsed, 'marginUsed'),
+    'Position.marginUsed'
+  )
+  const unrealizedPnl = positionAmount(position.unrealizedPnl, 'unrealizedPnl')
+  const minimumMargin = requirePositive(
+    constraintAmount(
+      constraints.minimumMarginRequirement,
+      'minimumMarginRequirement'
+    ),
+    'PositionMarginConstraints.minimumMarginRequirement'
+  )
+  const amountIncrement = requirePositive(
+    constraintAmount(constraints.amountIncrement, 'amountIncrement'),
+    'PositionMarginConstraints.amountIncrement'
+  )
+
+  const removable = marginUsed.plus(unrealizedPnl).minus(minimumMargin)
+  if (removable.lte(0)) {
+    return '0'
+  }
+  return removable
+    .div(amountIncrement)
+    .round(0, Big.roundDown)
+    .times(amountIncrement)
+    .toFixed()
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/perps-sdk'
-export const version = '5.0.0'
+export const version = '6.1.0'

package/src/websocket/PerpsWsClient.ts

@@ -18,7 +18,6 @@ import type {
  * @public
  */
 export type WsProviderFactory = (params: {
-  /** Provider key (e.g. `'lighter'`, `'hyperliquid'`). */
   provider: string
   /** WS URL discovered from `/providers`. */
   wsUrl: string

package/src/websocket/ReconnectingWebSocket.ts

@@ -44,7 +44,9 @@ const WS_PROVIDER_KEY = 'reconnecting-websocket'
  * @public
  */
 export interface ReconnectingWebSocketOptions {
+  /** Maximum reconnect attempts before status becomes `disconnected`; defaults to 10. */
   maxRetries?: number
+  /** Keepalive interval in milliseconds; defaults to 30,000. */
   pingIntervalMs?: number
   /**
    * Keepalive frame sent every `pingIntervalMs` while the socket is open.
@@ -52,9 +54,9 @@ export interface ReconnectingWebSocketOptions {
    */
   pingPayload?: string
   /**
-   * Stale-stream watchdog window. With `pingPayload` configured, the socket is
-   * force-reconnected when no inbound frame arrives within this window.
-   * Defaults to 3× `pingIntervalMs`.
+   * Stale-stream watchdog window in milliseconds. With `pingPayload` configured,
+   * the socket is force-reconnected when no inbound frame arrives within this
+   * window. Defaults to 3× `pingIntervalMs`.
    */
   staleWindowMs?: number
 }

package/src/websocket/WsProviderBase.ts

@@ -76,6 +76,13 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
     })
   }
 
+  /**
+   * Acquire a ref-counted subscription to a provider channel and return an
+   * idempotent release function. Optional status listeners are reference-counted
+   * alongside the channel listener.
+   *
+   * @public
+   */
   async subscribe(
     sub: Subscription,
     listener: SubscriptionListener,
@@ -112,6 +119,11 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
     }
   }
 
+  /**
+   * Reconnect the underlying socket only when it is terminally disconnected.
+   *
+   * @public
+   */
   reconnect(): void {
     if (this.rws.getStatus() !== 'disconnected') {
       return
@@ -119,6 +131,11 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
     this.rws.reconnect()
   }
 
+  /**
+   * Release all channel and status listeners and close the underlying socket.
+   *
+   * @public
+   */
   close(): void {
     for (const entry of this.channels.values()) {
       if (entry.pendingTeardown !== undefined) {

package/src/websocket/cachePromise.ts

@@ -9,6 +9,8 @@
  * @param read - Returns the currently cached promise, or `undefined` if none.
  * @param write - Stores (or with `undefined`, clears) the cached promise.
  * @param factory - Creates the promise when the slot is empty.
+ *
+ * @public
  */
 export function cachePromise<T>(
   read: () => Promise<T> | undefined,

package/src/websocket/types.ts

@@ -50,6 +50,10 @@ export type WsStatusListener = (status: WsConnectionStatus) => void
  * @public
  */
 export interface WsProvider {
+  /**
+   * Subscribe to one venue channel and return an idempotent unsubscribe.
+   * `onStatus` receives the provider socket's health transitions.
+   */
   subscribe(
     sub: Subscription,
     listener: SubscriptionListener,
@@ -71,5 +75,6 @@ export interface WsProvider {
     params: ProviderGetQuoteParams,
     onQuote: QuoteListener
   ): Promise<() => void>
+  /** Permanently close the provider's realtime connection. */
   close(): void
 }