@lifi/perps-sdk 6.0.0 → 6.1.0

package/dist/types/websocket/WsProviderBase.d.ts

@@ -36,8 +36,25 @@ export declare abstract class WsProviderBase<TSub = unknown> implements WsProvid
     private readonly statusListeners;
     private readonly wireSubs;
     constructor(rws: ReconnectingWebSocket, providerKey: string);
+    /**
+     * 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
+     */
     subscribe(sub: Subscription, listener: SubscriptionListener, onStatus?: WsStatusListener): Promise<() => void>;
+    /**
+     * Reconnect the underlying socket only when it is terminally disconnected.
+     *
+     * @public
+     */
     reconnect(): void;
+    /**
+     * Release all channel and status listeners and close the underlying socket.
+     *
+     * @public
+     */
     close(): void;
     /** Deliver an event to every listener on `key`. */
     protected emit(key: string, event: SubscriptionEvent): void;

package/dist/types/websocket/WsProviderBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WsProviderBase.d.ts","sourceRoot":"","sources":["../../../src/websocket/WsProviderBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AACvE,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAGnB;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAA;AAiBhD;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,cAAc,CAAC,IAAI,GAAG,OAAO,CAAE,YAAW,UAAU;IACxE,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAA;IAC7C,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAEtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsC;IACtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;gBAEvC,GAAG,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM;IAcrD,SAAS,CACb,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC;IAgCtB,SAAS,IAAI,IAAI;IAOjB,KAAK,IAAI,IAAI;IAab,mDAAmD;IACnD,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAU3D;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAgBlD;;;;;;OAMG;cACa,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE,4EAA4E;IAC5E,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;YAI5B,UAAU;IAqBxB,qFAAqF;IACrF,QAAQ,CAAC,cAAc,CACrB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;IAEtB,iFAAiF;IACjF,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;IAEnD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAEtE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnE,6DAA6D;IAC7D,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAEnD,mFAAmF;IACnF,SAAS,CAAC,OAAO,IAAI,IAAI;IAEzB,OAAO,CAAC,YAAY;YAYN,cAAc;IAgD5B,OAAO,CAAC,cAAc;CAwCvB"}
+{"version":3,"file":"WsProviderBase.d.ts","sourceRoot":"","sources":["../../../src/websocket/WsProviderBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AACvE,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAGnB;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAA;AAiBhD;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,cAAc,CAAC,IAAI,GAAG,OAAO,CAAE,YAAW,UAAU;IACxE,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAA;IAC7C,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAEtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsC;IACtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;gBAEvC,GAAG,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM;IAc3D;;;;;;OAMG;IACG,SAAS,CACb,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC;IAgCtB;;;;OAIG;IACH,SAAS,IAAI,IAAI;IAOjB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAab,mDAAmD;IACnD,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAU3D;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAgBlD;;;;;;OAMG;cACa,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE,4EAA4E;IAC5E,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;YAI5B,UAAU;IAqBxB,qFAAqF;IACrF,QAAQ,CAAC,cAAc,CACrB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;IAEtB,iFAAiF;IACjF,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;IAEnD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAEtE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnE,6DAA6D;IAC7D,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAEnD,mFAAmF;IACnF,SAAS,CAAC,OAAO,IAAI,IAAI;IAEzB,OAAO,CAAC,YAAY;YAYN,cAAc;IAgD5B,OAAO,CAAC,cAAc;CAwCvB"}

package/dist/types/websocket/cachePromise.d.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 declare function cachePromise<T>(read: () => Promise<T> | undefined, write: (promise: Promise<T> | undefined) => void, factory: () => Promise<T>): Promise<T>;
 //# sourceMappingURL=cachePromise.d.ts.map

package/dist/types/websocket/cachePromise.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cachePromise.d.ts","sourceRoot":"","sources":["../../../src/websocket/cachePromise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,EAClC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,KAAK,IAAI,EAChD,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CAaZ"}
+{"version":3,"file":"cachePromise.d.ts","sourceRoot":"","sources":["../../../src/websocket/cachePromise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,EAClC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,KAAK,IAAI,EAChD,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CAaZ"}

package/dist/types/websocket/types.d.ts

@@ -41,6 +41,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, onStatus?: WsStatusListener): Promise<() => void>;
     /**
      * Recover a terminally exhausted connection. Safe no-op unless status is
@@ -55,6 +59,7 @@ export interface WsProvider {
      * public base fee tier. Returns an idempotent unsubscribe.
      */
     subscribeQuote(params: ProviderGetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
+    /** Permanently close the provider's realtime connection. */
     close(): void;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types/websocket/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/websocket/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACd,MAAM,sBAAsB,CAAA;AAE7B;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,YAAY,IAAI,OAAO,CAChE,iBAAiB,EACjB;IAAE,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAA;CAAE,CAC1B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;AAErE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,cAAc,GAAG,cAAc,CAAA;AAE9E;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAA;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,CACP,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;IACtB;;;OAGG;IACH,SAAS,IAAI,IAAI,CAAA;IACjB;;;;;;OAMG;IACH,cAAc,CACZ,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;IACtB,KAAK,IAAI,IAAI,CAAA;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/websocket/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACd,MAAM,sBAAsB,CAAA;AAE7B;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,YAAY,IAAI,OAAO,CAChE,iBAAiB,EACjB;IAAE,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAA;CAAE,CAC1B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;AAErE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,cAAc,GAAG,cAAc,CAAA;AAE9E;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAA;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,SAAS,CACP,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;IACtB;;;OAGG;IACH,SAAS,IAAI,IAAI,CAAA;IACjB;;;;;;OAMG;IACH,cAAc,CACZ,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;IACtB,4DAA4D;IAC5D,KAAK,IAAI,IAAI,CAAA;CACd"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "LI.FI Perps SDK for perpetuals trading",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -45,7 +45,7 @@
     "big.js": "^7.0.1",
     "partysocket": "^1.1.19",
     "viem": "^2.48.8",
-    "@lifi/perps-types": "^4.0.0"
+    "@lifi/perps-types": "^4.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/client/PerpsClient.ts

@@ -426,6 +426,8 @@ export class PerpsClient {
    * Roll an already-fetched {@link AccountResponse} (plus its positions) up
    * into an {@link AccountSummary}, delegating to the owning provider so the
    * venue-specific collateral and margin semantics are applied correctly.
+   *
+   * @public
    */
   getAccountSummary(
     account: AccountResponse,

package/src/errors/PerpsError.ts

@@ -9,10 +9,17 @@ import { PerpsErrorCode } from '@lifi/perps-types'
  * @public
  */
 export class PerpsError extends Error {
+  /** Machine-readable error code for programmatic handling. */
   code: PerpsErrorCode
+  /** Stable error name used by `instanceof`/logging. */
   override name = 'PerpsError'
+  /** Originating package or provider key, when known. */
   tool?: string
 
+  /**
+   * Create an SDK error. Defaults to `DefaultError` and a generic message when
+   * callers do not provide either value.
+   */
   constructor(
     code: PerpsErrorCode = PerpsErrorCode.DefaultError,
     message = 'Unknown error occurred'

package/src/registry/assetRegistry.ts

@@ -16,7 +16,11 @@ export class AssetRegistry extends ReferenceDataRegistry<Asset> {
     super(client, provider, 'asset')
   }
 
-  /** The most recently synced asset list. Empty before the first {@link sync}. */
+  /**
+   * The most recently synced asset list. Empty before the first {@link sync}.
+   *
+   * @public
+   */
   get assets(): readonly Asset[] {
     return this.items
   }

package/src/registry/marketRegistry.ts

@@ -23,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)
   }
@@ -37,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)
@@ -61,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)
@@ -91,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
 

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

@@ -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
 }