@lifi/perps-sdk 6.0.0 → 6.2.0

package/src/storage/types.ts

@@ -1,13 +1,17 @@
 /**
- * Storage adapter interface for persisting SDK session credentials (provider
- * agent keypairs, API keys, read-only tokens). Implement this to use custom
- * storage (e.g. encrypted storage, a database, async key-value stores).
+ * Asynchronous key-value storage for SDK session credentials (provider agent
+ * keypairs, API keys, and read-only tokens). Values are opaque strings; an
+ * adapter should preserve them exactly and return `null` when a key is absent.
+ * Implement this interface for encrypted storage, a database, or another
+ * application-owned store.
+ *
+ * @public
  */
 export interface StorageAdapter {
-  /** Get a value by key. */
+  /** Read the value for `key`, or `null` when the key is absent. */
   get(key: string): Promise<string | null>
-  /** Set a value by key. */
+  /** Persist `value` under `key`, replacing any existing value. */
   set(key: string, value: string): Promise<void>
-  /** Remove a value by key. */
+  /** Remove `key`; resolving successfully when it is already absent. */
   remove(key: string): Promise<void>
 }

package/src/transport/fetchWithRetry.ts

@@ -7,8 +7,11 @@ import type { ResolvedRetryPolicy, RetryClassification } from './retryPolicy.js'
  * @public
  */
 export interface FetchWithRetryOptions {
+  /** Fully resolved retry policy controlling attempts, delays, and classification. */
   policy: ResolvedRetryPolicy
+  /** Optional fetch implementation; defaults to the global `fetch`. */
   fetchImpl?: typeof fetch
+  /** Abort signal; cancellation is propagated without retrying. */
   signal?: AbortSignal
 }
 

package/src/transport/retryPolicy.ts

@@ -24,6 +24,7 @@ export type RetryClassification =
  * @public
  */
 export interface RetryClassifyContext {
+  /** Non-2xx response being classified for retry or terminal failure. */
   response: Response
 }
 
@@ -34,9 +35,13 @@ export interface RetryClassifyContext {
  * @public
  */
 export interface RetryAttemptContext {
+  /** Zero-based attempt index for the response/error. */
   attempt: number
+  /** Response received, when the attempt reached the server. */
   response?: Response
+  /** Network error thrown before a response was received. */
   error?: unknown
+  /** Classification returned by the policy's classifier. */
   classification: RetryClassification
 }
 
@@ -50,11 +55,17 @@ export interface RetryAttemptContext {
  * @public
  */
 export interface RetryPolicy {
+  /** Maximum total attempts, including the initial request. */
   maxAttempts?: number
+  /** Initial exponential-backoff ceiling in milliseconds. */
   baseDelayMs?: number
+  /** Maximum backoff delay in milliseconds. */
   maxDelayMs?: number
+  /** Whether a valid `Retry-After` response header takes precedence. */
   respectRetryAfter?: boolean
+  /** Classify a response; `undefined` delegates to the base classifier. */
   classify?: (ctx: RetryClassifyContext) => RetryClassification | undefined
+  /** Final per-attempt veto after classification requests a retry. */
   shouldRetry?: (ctx: RetryAttemptContext) => boolean | Promise<boolean>
 }
 
@@ -65,12 +76,19 @@ export interface RetryPolicy {
  * @public
  */
 export interface ResolvedRetryPolicy {
+  /** Whether retries are enabled. */
   enabled: boolean
+  /** Maximum total attempts, including the initial request. */
   maxAttempts: number
+  /** Initial exponential-backoff ceiling in milliseconds. */
   baseDelayMs: number
+  /** Maximum backoff delay in milliseconds. */
   maxDelayMs: number
+  /** Whether a valid `Retry-After` header is honored. */
   respectRetryAfter: boolean
+  /** Final response classifier used for each failed attempt. */
   classify: (ctx: RetryClassifyContext) => RetryClassification
+  /** Optional final veto after classification requests a retry. */
   shouldRetry?: (ctx: RetryAttemptContext) => boolean | Promise<boolean>
 }
 
@@ -82,7 +100,9 @@ export interface ResolvedRetryPolicy {
  * @public
  */
 export interface ProviderRetryConfig {
+  /** Fallback policy for providers without an explicit key. */
   default?: RetryPolicy | false
+  /** Override keyed by provider type, or `lifi` for backend requests. */
   [providerKey: string]: RetryPolicy | false | undefined
 }
 

package/src/types/api.ts

@@ -28,10 +28,15 @@ import type { PerpsProviderPlugin } from './provider.js'
  * @public
  */
 export interface PerpsConfig {
+  /** Integrator identifier sent in the `x-lifi-integrator` request header. */
   integrator: string
+  /** LI.FI API key used for authenticated backend requests. */
   apiKey: string
+  /** Perps API base URL; defaults to {@link DEFAULT_API_URL}. */
   apiUrl?: string
+  /** Skip the SDK-version compatibility check when set. */
   disableVersionCheck?: boolean
+  /** Hook that can rewrite URL/request options before transport. */
   requestInterceptor?: RequestInterceptor
   /**
    * Provider plugins or per-provider config. Two shapes are accepted:
@@ -79,10 +84,11 @@ export interface PerpsConfig {
  * @public
  */
 export interface PerpsClientOptions {
+  /** Integrator identifier sent in the `x-lifi-integrator` request header. */
   integrator: string
-  /** API key for authenticated requests (get one at https://portal.li.fi/) */
+  /** API key for authenticated requests (get one at https://portal.li.fi/). */
   apiKey: string
-  /** Defaults to DEFAULT_API_URL */
+  /** Perps API base URL; defaults to {@link DEFAULT_API_URL}. */
   apiUrl?: string
   /**
    * Provider plugins or per-provider config. Accepts the same two shapes as
@@ -117,11 +123,15 @@ export interface BuildProviderSetupParams {
 export interface PlaceOrderParams {
   provider: string
   address: Address
+  /** Opaque provider market reference. */
   market: MarketRef
   side: OrderSide
   type: OrderType
+  /** Base-asset size as a decimal wire string. */
   size: string
+  /** Limit price as a decimal wire string; required by limit-style orders. */
   price: string
+  /** Optional leverage multiplier; provider defaults apply when omitted. */
   leverage?: number
   /**
    * Margin mode the order trades under; omitted falls to the venue's cross
@@ -129,8 +139,11 @@ export interface PlaceOrderParams {
    * applies it via a prepended leverage update (requires `leverage`).
    */
   marginMode?: MarginMode
+  /** Whether the order may only reduce an existing position. */
   reduceOnly?: boolean
+  /** Time-in-force policy; provider defaults apply when omitted. */
   timeInForce?: TimeInForce
+  /** Optional Unix timestamp or provider wire expiry string. */
   expiresAt?: string
   takeProfit?: TriggerOrderInput
   stopLoss?: TriggerOrderInput
@@ -145,6 +158,7 @@ export interface PlaceOrderParams {
 export interface PlaceTriggerOrderParams {
   provider: string
   address: Address
+  /** Opaque provider market reference. */
   market: MarketRef
   side: OrderSide
   takeProfit?: TriggerOrderInput
@@ -159,6 +173,7 @@ export interface PlaceTriggerOrderParams {
 export interface WithdrawParams {
   provider: string
   address: Address
+  /** Provider-specific withdrawal payload, including amount/destination. */
   withdrawal: WithdrawalParams
 }
 
@@ -172,11 +187,13 @@ export interface WithdrawParams {
 export interface SendAssetActionParams {
   provider: string
   address: Address
-  /** Canonical `Asset.id` of the asset being moved (for Hyperliquid spot
-   * assets, the token index as a string) — never a display symbol. */
+  /** Canonical `Asset.id` (Hyperliquid spot uses the token index as a string); never a display symbol. */
   collateral: string
+  /** Source DEX/account identifier understood by the provider. */
   sourceDex: string
+  /** Destination DEX/account identifier understood by the provider. */
   destinationDex: string
+  /** Transfer amount as a provider-compatible decimal wire string. */
   amount: string
 }
 
@@ -188,10 +205,9 @@ export interface SendAssetActionParams {
 export interface CancelOrdersParams {
   provider: string
   address: Address
-  /** Venue order ids. Venues whose ids are scoped per market (e.g. Lighter's
-   * `order_index`) also accept the composite `"<market_id>:<order_id>"`. */
+  /** Venue order ids. Market-scoped venues such as Lighter also accept `"<market_id>:<order_id>"`. */
   ids: string[]
-  /** Market context for per-market order ids; the order's `market.id`. */
+  /** Market context for per-market order ids; use the order's opaque `market.id`. */
   assetId?: string
 }
 
@@ -203,6 +219,7 @@ export interface CancelOrdersParams {
 export interface ModifyOrdersParams {
   provider: string
   address: Address
+  /** Provider-specific order modifications. */
   modifications: ModifyOrderInput[]
 }
 
@@ -257,9 +274,7 @@ export interface ProviderSetup {
  * Parameters for the internal `PerpsClient.executeProviderSetup` batch submit.
  */
 export interface ExecuteProviderSetupParams {
-  /** Provider to satisfy setup for */
   provider: string
-  /** User wallet address */
   address: Address
   /** The unsatisfied setup steps from checkSetup() */
   setup: ActionStep[]

package/src/types/config.ts

@@ -30,6 +30,7 @@ export type SwitchChainHook = (
  * @public
  */
 export interface ProviderConfig {
+  /** Optional provider category/market ids used to filter WS subscriptions. */
   markets?: string[]
 }
 
@@ -64,6 +65,7 @@ export type RequestInterceptor = (
  * @public
  */
 export interface SDKRequestOptions {
+  /** Abort the request and any pending backoff delay. */
   signal?: AbortSignal
   /**
    * Lighter auth token consumed by provider-direct venue reads (getOrders,
@@ -85,12 +87,20 @@ export interface SDKRequestOptions {
  * @public
  */
 export interface PerpsBaseConfig {
+  /** Integrator identifier sent in the `x-lifi-integrator` header. */
   integrator: string
+  /** API key applied to backend requests when non-empty. */
   apiKey: string
+  /** Resolved perps API base URL. */
   apiUrl: string
+  /** Whether SDK version compatibility checks are disabled. */
   disableVersionCheck?: boolean
+  /** Optional outgoing-request URL/options interceptor. */
   requestInterceptor?: RequestInterceptor
+  /** Optional per-provider WS market filters. */
   providers?: ProviderConfigs
+  /** Optional global or per-provider retry configuration. */
   retry?: RetryConfig
+  /** Fetch implementation used by core HTTP transport. */
   fetch?: typeof fetch
 }

package/src/types/deposit.ts

@@ -9,9 +9,11 @@ import type { Address } from 'viem'
  * @public
  */
 export interface DeclaredDepositAsset {
+  /** EVM chain id on which the asset is held or broadcast. */
   chainId: number
-  /** EIP-55 checksummed address; the zero address denotes the chain's native gas token. */
+  /** EIP-55 checksummed address; the zero address denotes native gas. */
   address: Address
+  /** Decimal places used by the token; native gas assets use 18. */
   decimals: number
 }
 
@@ -25,6 +27,7 @@ export interface DeclaredDepositAsset {
  */
 export interface DepositFlowLifiSwap {
   kind: 'lifiSwap'
+  /** Destination collateral token and its full chain identity. */
   destination: DeclaredDepositAsset
   /**
    * Credited address when it is not the user's own — a venue-provisioned
@@ -43,10 +46,13 @@ export interface DepositFlowLifiSwap {
  */
 export interface DepositFlowFirstDepositPipeline {
   kind: 'firstDepositPipeline'
-  /** Chain the deposit legs broadcast on; the user's wallet must be switched to it. */
+  /** Chain on which the deposit legs broadcast; the wallet must be switched here. */
   chainId: number
+  /** Native gas asset needed to broadcast the deposit legs. */
   gasAsset: DeclaredDepositAsset
+  /** Collateral asset credited by the first deposit. */
   collateral: DeclaredDepositAsset
+  /** Action type used to stage the deposit pipeline. */
   bridgeAction: ActionType.DEPOSIT
 }
 
@@ -59,7 +65,7 @@ export interface DepositFlowFirstDepositPipeline {
  */
 export interface DepositFlowSetupRequired {
   kind: 'setupRequired'
-  /** Outstanding `Provider.setup` action types, in the order they must be run. */
+  /** Setup action types that must be completed, in execution order. */
   setup: ActionType[]
 }
 

package/src/types/provider.ts

@@ -43,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
@@ -68,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`
@@ -142,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
 }
 
@@ -182,9 +183,11 @@ 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
 }
 
@@ -207,9 +210,11 @@ export interface ProviderGetMarketSettingsParams {
  */
 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
 }
 
@@ -220,6 +225,7 @@ export interface ProviderGetOrdersParams {
  */
 export interface ProviderGetOrderParams {
   address: Address
+  /** Venue order id, opaque to the SDK. */
   id: string
 }
 
@@ -230,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
 }
 
@@ -243,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[]
 }
 
@@ -257,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
 }
 
@@ -556,6 +573,17 @@ export interface PerpsProviderPlugin {
    * — e.g. evicting a locally stored credential the venue no longer accepts.
    */
   onExecuteResults?(address: Address, results: ActionResult[]): Promise<void>
+
+  /**
+   * Resolve a venue transaction hash to a block-explorer URL. Core calls it for
+   * every `/executeAction` result the backend returned a `txHash` on, so the
+   * explorer target stays provider-owned.
+   *
+   * Optional: a venue with no explorer (Ondo settles offchain) omits it, and
+   * results then carry the hash alone. May also return `undefined` for an
+   * instance whose explorer is not configured.
+   */
+  resolveExplorerLink?(txHash: string): string | undefined
 }
 
 /**

package/src/utils/calculations.ts

@@ -175,7 +175,9 @@ export function effectiveLeverage(params: {
  * @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

@@ -1,9 +1,8 @@
 import {
-  MarginMode,
   PerpsErrorCode,
   type Position,
-  PositionMarginAdjustment,
   type PositionMarginConstraints,
+  positionSupportsMarginRemoval,
 } from '@lifi/perps-types'
 import Big from 'big.js'
 import { PerpsError } from '../errors/PerpsError.js'
@@ -66,11 +65,7 @@ export function removableIsolatedMargin({
   position,
   constraints,
 }: RemovableIsolatedMarginParams): string {
-  if (
-    position.marginMode !== MarginMode.ISOLATED ||
-    position.market.positionMarginAdjustment !==
-      PositionMarginAdjustment.ADD_AND_REMOVE
-  ) {
+  if (!positionSupportsMarginRemoval(position)) {
     return '0'
   }
 

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/perps-sdk'
-export const version = '6.0.0'
+export const version = '6.2.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
 }