@lifi/perps-sdk 12.1.0 → 13.0.0

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

@@ -3,12 +3,11 @@ import type { GetQuoteParams } from '../services/getQuote.js';
 import type { PerpsSDKClient, QuoteListener } from '../types/provider.js';
 import type { EventForSubscription, WsProvider, WsStatusListener } from './types.js';
 /**
- * Factory for a per-provider WS plugin. Invoked once per provider key the
- * first time `subscribe(...)` is called against it.
+ * Call parameters of a {@link WsProviderFactory}.
  *
  * @public
  */
-export type WsProviderFactory = (params: {
+export interface WsProviderFactoryParams {
     provider: string;
     /** WS URL discovered from `/providers`. */
     wsUrl: string;
@@ -25,7 +24,18 @@ export type WsProviderFactory = (params: {
      * duplicating backend orchestration in the WS layer.
      */
     client: PerpsSDKClient;
-}) => WsProvider;
+}
+/**
+ * Factory for a per-provider WS plugin. Invoked once per provider key the
+ * first time `subscribe(...)` is called against it.
+ *
+ * @public
+ */
+export interface WsProviderFactory {
+    (params: WsProviderFactoryParams): WsProvider;
+    /** `true` when the venue socket serves the `candle` channel. */
+    readonly streamsCandles: boolean;
+}
 /**
  * Options for {@link PerpsWsClient}.
  *
@@ -43,7 +53,7 @@ export interface PerpsWsClientOptions {
     wsProviders?: Record<string, WsProviderFactory>;
 }
 /**
- * Realtime client: lazily instantiates a per-provider {@link WsProvider} on
+ * WebSocket client: lazily instantiates a per-provider {@link WsProvider} on
  * first subscription and fans subscriptions out to it.
  *
  * @public
@@ -56,7 +66,16 @@ export declare class PerpsWsClient {
     private closed;
     constructor(client: PerpsSDKClient, options?: PerpsWsClientOptions);
     /**
-     * Subscribe to a realtime channel, lazily creating the provider's WS
+     * Whether `provider`'s socket serves the `candle` channel, as reported by
+     * its registered factory. Returns `false` when no factory is registered.
+     * Synchronous: it reads the factory without instantiating the provider and
+     * makes no network call, so a caller can branch before the first subscribe.
+     *
+     * @public
+     */
+    streamsCandles(provider: string): boolean;
+    /**
+     * Subscribe to a WebSocket channel, lazily creating the provider's WS
      * connection. Returns an unsubscribe function.
      *
      * @param onStatus - Optional listener for the underlying connection's

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

@@ -1 +1 @@
-{"version":3,"file":"PerpsWsClient.d.ts","sourceRoot":"","sources":["../../../src/websocket/PerpsWsClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzE,OAAO,KAAK,EACV,oBAAoB,EAEpB,UAAU,EACV,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAEnB;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE;IACvC,QAAQ,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB;;;;OAIG;IACH,MAAM,EAAE,cAAc,CAAA;CACvB,KAAK,UAAU,CAAA;AAEhB;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;CAChD;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,YAAY,CAAyC;IAC7D,OAAO,CAAC,MAAM,CAAQ;gBAEV,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,oBAAyB;IAKtE;;;;;;;;;;;;OAYG;IACG,SAAS,CAAC,CAAC,SAAS,YAAY,EACpC,GAAG,EAAE,CAAC,EACN,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,IAAI,EAClD,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC;IAOtB;;;;;;;;;;OAUG;IACG,cAAc,CAClB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;IAatB;;;;;;;OAOG;IACH,KAAK;IASL;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIjC,OAAO,CAAC,UAAU;YASJ,mBAAmB;YAqBnB,YAAY;CAsC3B"}
+{"version":3,"file":"PerpsWsClient.d.ts","sourceRoot":"","sources":["../../../src/websocket/PerpsWsClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzE,OAAO,KAAK,EACV,oBAAoB,EAEpB,UAAU,EACV,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAEnB;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB;;;;OAIG;IACH,MAAM,EAAE,cAAc,CAAA;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,MAAM,EAAE,uBAAuB,GAAG,UAAU,CAAA;IAC7C,gEAAgE;IAChE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;CAChD;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,YAAY,CAAyC;IAC7D,OAAO,CAAC,MAAM,CAAQ;gBAEV,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,oBAAyB;IAKtE;;;;;;;OAOG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIzC;;;;;;;;;;;;OAYG;IACG,SAAS,CAAC,CAAC,SAAS,YAAY,EACpC,GAAG,EAAE,CAAC,EACN,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,IAAI,EAClD,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC;IAOtB;;;;;;;;;;OAUG;IACG,cAAc,CAClB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;IAatB;;;;;;;OAOG;IACH,KAAK;IASL;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIjC,OAAO,CAAC,UAAU;YASJ,mBAAmB;YAqBnB,YAAY;CAsC3B"}

package/package.json

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

package/src/client/PerpsClient.ts

@@ -9,6 +9,7 @@ import type {
   MarketRef,
   MarketSettings,
   MetaActionType,
+  PortfolioHistoryResponse,
   Position,
   PositionMarginConstraints,
   Provider,
@@ -40,6 +41,7 @@ import type {
   ExecuteProviderSetupResult,
   GetAccountResult,
   GetDepositFlowParams,
+  GetPortfolioHistoryParams,
   GetSetupParams,
   GetWithdrawableBalancesParams,
   ModifyOrdersParams,
@@ -52,7 +54,11 @@ import type {
   SubmitOnboardingParams,
   WithdrawParams,
 } from '../types/api.js'
-import type { PerpsClientSigner, SwitchChainHook } from '../types/config.js'
+import type {
+  PerpsClientSigner,
+  SDKRequestOptions,
+  SwitchChainHook,
+} from '../types/config.js'
 import type { DepositFlow } from '../types/deposit.js'
 import type {
   ActionSignerContribution,
@@ -579,6 +585,31 @@ export class PerpsClient {
     })
   }
 
+  /**
+   * The account's portfolio value and cumulative PnL over `params.range` at
+   * `params.provider`, read directly from the venue.
+   *
+   * @throws {PerpsError} When the provider plugin is not registered, when it
+   *   declares no portfolio history read, or when the venue read fails.
+   * @public
+   */
+  async getPortfolioHistory(
+    params: GetPortfolioHistoryParams,
+    options?: SDKRequestOptions
+  ): Promise<PortfolioHistoryResponse> {
+    const plugin = this.requireProvider(params.provider)
+    if (typeof plugin.getPortfolioHistory !== 'function') {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `Provider '${params.provider}' does not implement getPortfolioHistory.`
+      )
+    }
+    return plugin.getPortfolioHistory(
+      { address: params.address, range: params.range },
+      options
+    )
+  }
+
   /**
    * Return the unsatisfied entries on `Provider.setup` for this account as a
    * flat, self-describing list. Trading is gated on `isReady === true`.

package/src/index.ts

@@ -111,6 +111,7 @@ export type {
   ExecuteMetaActionParams,
   GetAccountResult,
   GetDepositFlowParams,
+  GetPortfolioHistoryParams,
   GetSetupParams,
   GetWithdrawableBalancesParams,
   ModifyOrdersParams,
@@ -156,6 +157,7 @@ export type {
   ProviderGetMarketSettingsParams,
   ProviderGetOrderParams,
   ProviderGetOrdersParams,
+  ProviderGetPortfolioHistoryParams,
   ProviderGetPositionsParams,
   ProviderGetQuoteParams,
   ProviderGetRunningTwapsParams,
@@ -256,6 +258,7 @@ export { cachePromise } from './websocket/cachePromise.js'
 export type {
   PerpsWsClientOptions,
   WsProviderFactory,
+  WsProviderFactoryParams,
 } from './websocket/PerpsWsClient.js'
 export { PerpsWsClient } from './websocket/PerpsWsClient.js'
 export type { ReconnectingWebSocketOptions } from './websocket/ReconnectingWebSocket.js'

package/src/types/api.ts

@@ -14,6 +14,7 @@ import type {
   OnboardParams,
   OrderSide,
   OrderType,
+  PortfolioHistoryRange,
   ProviderAction,
   SignedActionStep,
   TimeInForce,
@@ -298,6 +299,17 @@ export interface GetWithdrawableBalancesParams {
   address: Address
 }
 
+/**
+ * Parameters for {@link PerpsClient.getPortfolioHistory}.
+ *
+ * @public
+ */
+export interface GetPortfolioHistoryParams {
+  provider: string
+  address: Address
+  range: PortfolioHistoryRange
+}
+
 /**
  * One entry on {@link ProviderSetup.checklist}: a user-facing setup
  * descriptor plus its satisfied state for the queried account.

package/src/types/provider.ts

@@ -16,6 +16,8 @@ import type {
   OrdersResponse,
   PerpsMarket,
   PerpsSigner,
+  PortfolioHistoryRange,
+  PortfolioHistoryResponse,
   Position,
   PositionMarginConstraints,
   PositionsResponse,
@@ -287,6 +289,16 @@ export interface ProviderGetActivityParams {
   type?: ActivityType[]
 }
 
+/**
+ * Read params for {@link PerpsProvider.getPortfolioHistory}.
+ *
+ * @public
+ */
+export interface ProviderGetPortfolioHistoryParams {
+  address: Address
+  range: PortfolioHistoryRange
+}
+
 /**
  * Read params for {@link PerpsProviderPlugin.getQuote}. `provider` is implicit
  * in the provider instance and so is not duplicated here.
@@ -469,6 +481,15 @@ export interface PerpsProviderPlugin {
     options?: SDKRequestOptions
   ): Promise<ActivitiesResponse>
 
+  /**
+   * Read the account's portfolio value and cumulative PnL over
+   * `params.range`, oldest point first, directly from the venue.
+   */
+  getPortfolioHistory?(
+    params: ProviderGetPortfolioHistoryParams,
+    options?: SDKRequestOptions
+  ): Promise<PortfolioHistoryResponse>
+
   /**
    * Produce a one-shot fill {@link Quote} for `params.symbol` at `params.size`
    * USD notional on this venue. The provider resolves the symbol against its

package/src/version.ts

@@ -10,4 +10,4 @@ export const name = '@lifi/perps-sdk'
  *
  * @public
  */
-export const version = '12.1.0'
+export const version = '13.0.0'

package/src/websocket/PerpsWsClient.ts

@@ -12,12 +12,11 @@ import type {
 } from './types.js'
 
 /**
- * Factory for a per-provider WS plugin. Invoked once per provider key the
- * first time `subscribe(...)` is called against it.
+ * Call parameters of a {@link WsProviderFactory}.
  *
  * @public
  */
-export type WsProviderFactory = (params: {
+export interface WsProviderFactoryParams {
   provider: string
   /** WS URL discovered from `/providers`. */
   wsUrl: string
@@ -34,7 +33,19 @@ export type WsProviderFactory = (params: {
    * duplicating backend orchestration in the WS layer.
    */
   client: PerpsSDKClient
-}) => WsProvider
+}
+
+/**
+ * Factory for a per-provider WS plugin. Invoked once per provider key the
+ * first time `subscribe(...)` is called against it.
+ *
+ * @public
+ */
+export interface WsProviderFactory {
+  (params: WsProviderFactoryParams): WsProvider
+  /** `true` when the venue socket serves the `candle` channel. */
+  readonly streamsCandles: boolean
+}
 
 /**
  * Options for {@link PerpsWsClient}.
@@ -54,7 +65,7 @@ export interface PerpsWsClientOptions {
 }
 
 /**
- * Realtime client: lazily instantiates a per-provider {@link WsProvider} on
+ * WebSocket client: lazily instantiates a per-provider {@link WsProvider} on
  * first subscription and fans subscriptions out to it.
  *
  * @public
@@ -72,7 +83,19 @@ export class PerpsWsClient {
   }
 
   /**
-   * Subscribe to a realtime channel, lazily creating the provider's WS
+   * Whether `provider`'s socket serves the `candle` channel, as reported by
+   * its registered factory. Returns `false` when no factory is registered.
+   * Synchronous: it reads the factory without instantiating the provider and
+   * makes no network call, so a caller can branch before the first subscribe.
+   *
+   * @public
+   */
+  streamsCandles(provider: string): boolean {
+    return this.options.wsProviders?.[provider]?.streamsCandles ?? false
+  }
+
+  /**
+   * Subscribe to a WebSocket channel, lazily creating the provider's WS
    * connection. Returns an unsubscribe function.
    *
    * @param onStatus - Optional listener for the underlying connection's