@lifi/perps-sdk 5.0.0 → 6.1.0

package/src/registry/marketRegistry.ts

@@ -1,5 +1,10 @@
-import type { Market, MarketDisplay, MarketsResponse } from '@lifi/perps-types'
-import { PerpsErrorCode } from '@lifi/perps-types'
+import type {
+  Market,
+  MarketDisplay,
+  MarketsResponse,
+  PerpsMarketDisplay,
+} from '@lifi/perps-types'
+import { PerpsErrorCode, PositionMarginAdjustment } from '@lifi/perps-types'
 import { PerpsError } from '../errors/PerpsError.js'
 import { buildUrl, request } from '../transport/request.js'
 import type { PerpsSDKClient } from '../types/provider.js'
@@ -18,12 +23,20 @@ export class MarketRegistry extends ReferenceDataRegistry<Market> {
     super(client, provider, 'market')
   }
 
-  /** The most recently synced market list. Empty before the first {@link sync}. */
+  /**
+   * The most recently synced market list. Empty before the first {@link sync}.
+   *
+   * @public
+   */
   get markets(): readonly Market[] {
     return this.items
   }
 
-  /** The synced markets that are available for live and write operations. */
+  /**
+   * The synced markets that are available for live and write operations.
+   *
+   * @public
+   */
   get activeMarkets(): readonly Market[] {
     return this.items.filter(isActiveMarket)
   }
@@ -32,10 +45,10 @@ export class MarketRegistry extends ReferenceDataRegistry<Market> {
    * Lookup by `Market.id`, throwing when the backend list does not know the
    * id. The list is the source of truth for enriched historical and live
    * market metadata, so an id the venue references but the backend does not
-   * know is a hard error —
-   * never a silent fallback to an unenriched stand-in.
+   * know is a hard error — never a silent fallback to an unenriched stand-in.
    *
    * @throws {PerpsError} `MarketNotFound`.
+   * @public
    */
   require(marketId: string): Market {
     const market = this.get(marketId)
@@ -56,6 +69,7 @@ export class MarketRegistry extends ReferenceDataRegistry<Market> {
    * rejects them.
    *
    * @throws {PerpsError} `MarketNotFound` when the market is absent or delisted.
+   * @public
    */
   requireActive(marketId: string): Market {
     const market = this.require(marketId)
@@ -86,7 +100,12 @@ export class MarketRegistry extends ReferenceDataRegistry<Market> {
 
 const registries = new WeakMap<PerpsSDKClient, Map<string, MarketRegistry>>()
 
-/** A market is active unless the provider explicitly marks it delisted. */
+/**
+ * Return whether a market is available for live quoting and trading. A market
+ * remains active unless the backend explicitly sets `isDelisted` to `true`.
+ *
+ * @public
+ */
 export const isActiveMarket = (market: Market): boolean =>
   market.isDelisted !== true
 
@@ -127,3 +146,41 @@ export const toMarketDisplay = (market: Market): MarketDisplay => ({
   quoteAsset: market.quoteAsset,
   ...(market.isDelisted === undefined ? {} : { isDelisted: market.isDelisted }),
 })
+
+/**
+ * Project a perpetual {@link Market} to the identity embedded on a
+ * {@link Position}, preserving its individual-margin capability.
+ *
+ * @throws {PerpsError} `ValidationError` when passed a spot market.
+ * @public
+ */
+export const toPerpsMarketDisplay = (market: Market): PerpsMarketDisplay => {
+  if (!('positionMarginAdjustment' in market)) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Market '${market.id}' is not a perpetual market.`
+    )
+  }
+  const capability = market.positionMarginAdjustment
+  if (
+    capability !== PositionMarginAdjustment.NONE &&
+    capability !== PositionMarginAdjustment.ADD_ONLY &&
+    capability !== PositionMarginAdjustment.ADD_AND_REMOVE
+  ) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Market '${market.id}' is not a perpetual market.`
+    )
+  }
+  return {
+    providerId: market.providerId,
+    id: market.id,
+    categoryId: market.categoryId,
+    baseAsset: market.baseAsset,
+    quoteAsset: market.quoteAsset,
+    ...(market.isDelisted === undefined
+      ? {}
+      : { isDelisted: market.isDelisted }),
+    positionMarginAdjustment: capability,
+  }
+}

package/src/services/createAction.ts

@@ -16,8 +16,10 @@ import type { PerpsSDKClient } from '../types/provider.js'
 export interface CreateActionParams<T extends ActionType = ActionType> {
   provider: string
   address: Address
+  /** Optional provider-owned signer address sent to the backend. */
   signerAddress?: Address
   action: T
+  /** Action-specific payload matching `action`. */
   params: ActionParamsMap[T]
 }
 

package/src/services/executeAction.ts

@@ -16,7 +16,9 @@ import type { PerpsSDKClient } from '../types/provider.js'
 export interface ExecuteActionParams {
   provider: string
   address: Address
+  /** Optional provider-owned signer address used for submission. */
   signerAddress?: Address
+  /** Action descriptor shared by the signed steps. */
   action: ActionType
   actions: SignedActionStep[]
 }

package/src/services/getActivity.ts

@@ -12,11 +12,13 @@ import type { PerpsSDKClient } from '../types/provider.js'
 export interface GetActivityParams {
   provider: string
   address: Address
+  /** Maximum items returned; provider defaults and caps apply. */
   limit?: number
+  /** Opaque pagination cursor from the previous response. */
   cursor?: string
-  /** Filter: activity after this timestamp (ms) */
+  /** Include activity at or after this Unix timestamp in milliseconds. */
   startTime?: number
-  /** Filter: activity before this timestamp (ms) */
+  /** Include activity at or before this Unix timestamp in milliseconds. */
   endTime?: number
   type?: ActivityType[]
 }

package/src/services/getFills.ts

@@ -12,11 +12,13 @@ import type { PerpsSDKClient } from '../types/provider.js'
 export interface GetFillsParams {
   provider: string
   address: Address
+  /** Maximum items returned; provider defaults and caps apply. */
   limit?: number
+  /** Opaque pagination cursor from the previous response. */
   cursor?: string
-  /** Filter: fills after this timestamp (ms) */
+  /** Include fills at or after this Unix timestamp in milliseconds. */
   startTime?: number
-  /** Filter: fills before this timestamp (ms) */
+  /** Include fills at or before this Unix timestamp in milliseconds. */
   endTime?: number
 }
 

package/src/services/getMarkets.ts

@@ -11,7 +11,7 @@ import type { PerpsSDKClient } from '../types/provider.js'
  */
 export interface GetMarketsParams {
   provider: string
-  /** Optional filter — opaque `Market.id`s (not display symbols). */
+  /** Optional comma-joined filter of opaque `Market.id`s. */
   marketIds?: string[]
 }
 

package/src/services/getMarketsContext.ts

@@ -10,7 +10,7 @@ import type { PerpsSDKClient } from '../types/provider.js'
  */
 export interface GetMarketsContextParams {
   provider: string
-  /** Optional filter — opaque `Market.id`s (not display symbols). */
+  /** Optional filter of opaque `Market.id`s (not display symbols). */
   marketIds?: string[]
 }
 

package/src/services/getOhlcv.ts

@@ -10,13 +10,14 @@ import type { PerpsSDKClient } from '../types/provider.js'
  */
 export interface GetOhlcvParams {
   provider: string
-  /** Opaque provider `Market.id` (not `displaySymbol`). */
+  /** Opaque provider `Market.id`, not a display symbol. */
   marketId: string
   interval: OhlcvInterval
-  /** Unix timestamp in milliseconds */
+  /** Unix timestamp in milliseconds for the start bound. */
   startTime?: number
-  /** Unix timestamp in milliseconds */
+  /** Unix timestamp in milliseconds for the end bound. */
   endTime?: number
+  /** Maximum candles returned; provider defaults and caps apply. */
   limit?: number
 }
 

package/src/services/getOrder.ts

@@ -12,6 +12,7 @@ import type { PerpsSDKClient } from '../types/provider.js'
 export interface GetOrderParams {
   provider: string
   address: Address
+  /** Venue order id, opaque to the SDK. */
   id: string
 }
 

package/src/services/getOrderbook.ts

@@ -10,9 +10,9 @@ import type { PerpsSDKClient } from '../types/provider.js'
  */
 export interface GetOrderbookParams {
   provider: string
-  /** Opaque provider `Market.id` (not `displaySymbol`). */
+  /** Opaque provider `Market.id`, not a display symbol. */
   marketId: string
-  /** Number of levels to return (default varies by DEX) */
+  /** Optional number of price levels; venue defaults apply when omitted. */
   depth?: number
 }
 

package/src/services/getOrders.ts

@@ -12,9 +12,11 @@ import type { PerpsSDKClient } from '../types/provider.js'
 export interface GetOrdersParams {
   provider: string
   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
 }
 

package/src/services/getPositions.ts

@@ -12,9 +12,11 @@ import type { PerpsSDKClient } from '../types/provider.js'
 export interface GetPositionsParams {
   provider: string
   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
 }
 

package/src/services/getQuote.ts

@@ -10,11 +10,13 @@ import type { PerpsSDKClient } from '../types/provider.js'
  */
 export interface GetQuoteParams {
   provider: string
-  /** Human `displaySymbol`, e.g. `"BTC"`. */
+  /** Human `displaySymbol`, e.g. `"BTC"`, resolved by the provider. */
   symbol: string
+  /** Buy consumes asks; sell consumes bids. */
   side: QuoteSide
   /** USD notional to fill. */
   size: number
+  /** Product family used to distinguish spot and perpetual markets. */
   type: TradeType
 }
 

package/src/storage/parseStoredRecord.ts

@@ -15,6 +15,8 @@ import type { StorageAdapter } from './types.js'
  *
  * @param raw Stored string, or `null` when the key is absent.
  * @param isValid Shape guard run against the parsed value.
+ *
+ * @public
  */
 export function parseStoredRecord<T>(
   raw: string | null,
@@ -40,6 +42,8 @@ export function parseStoredRecord<T>(
  * Returns `null` for both the genuine-absence and the evicted-poison cases;
  * callers that must distinguish them should compare against the pre-read
  * presence of the key themselves.
+ *
+ * @public
  */
 export async function readValidatedRecord<T>(
   storage: StorageAdapter,

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

@@ -3,6 +3,7 @@ import type {
   AccountResponse,
   ActionStep,
   ExecuteActionResponse,
+  MarginMode,
   MarketRef,
   ModifyOrderInput,
   OrderSide,
@@ -27,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:
@@ -78,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
@@ -116,14 +123,27 @@ 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
+   * default. Lighter's order tx carries the mode directly; Hyperliquid
+   * 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
@@ -138,6 +158,7 @@ export interface PlaceOrderParams {
 export interface PlaceTriggerOrderParams {
   provider: string
   address: Address
+  /** Opaque provider market reference. */
   market: MarketRef
   side: OrderSide
   takeProfit?: TriggerOrderInput
@@ -152,6 +173,7 @@ export interface PlaceTriggerOrderParams {
 export interface WithdrawParams {
   provider: string
   address: Address
+  /** Provider-specific withdrawal payload, including amount/destination. */
   withdrawal: WithdrawalParams
 }
 
@@ -165,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
 }
 
@@ -181,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
 }
 
@@ -196,6 +219,7 @@ export interface CancelOrdersParams {
 export interface ModifyOrdersParams {
   provider: string
   address: Address
+  /** Provider-specific order modifications. */
   modifications: ModifyOrderInput[]
 }
 
@@ -250,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[]
 }