@lifi/perps-sdk 12.1.0 → 14.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": "14.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": "^13.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/client/PerpsClient.ts

@@ -9,6 +9,9 @@ import type {
   MarketRef,
   MarketSettings,
   MetaActionType,
+  Order,
+  OrdersResponse,
+  PortfolioHistoryResponse,
   Position,
   PositionMarginConstraints,
   Provider,
@@ -29,6 +32,14 @@ import { getAssetRegistry } from '../registry/assetRegistry.js'
 import { createAction } from '../services/createAction.js'
 import { executeAction } from '../services/executeAction.js'
 import { getAccount as fetchAccount } from '../services/getAccount.js'
+import {
+  getOrder as fetchOrder,
+  type GetOrderParams,
+} from '../services/getOrder.js'
+import {
+  getOrders as fetchOrders,
+  type GetOrdersParams,
+} from '../services/getOrders.js'
 import { getProviders } from '../services/getProviders.js'
 import type {
   BuildProviderSetupParams,
@@ -40,6 +51,7 @@ import type {
   ExecuteProviderSetupResult,
   GetAccountResult,
   GetDepositFlowParams,
+  GetPortfolioHistoryParams,
   GetSetupParams,
   GetWithdrawableBalancesParams,
   ModifyOrdersParams,
@@ -52,7 +64,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,
@@ -184,6 +200,22 @@ export class PerpsClient {
     return resolveProvider(this.sdkClient, provider)
   }
 
+  /** Read active or historical orders from the selected venue. */
+  async getOrders(
+    params: GetOrdersParams,
+    options?: SDKRequestOptions
+  ): Promise<OrdersResponse> {
+    return fetchOrders(this.sdkClient, params, options)
+  }
+
+  /** Read one venue order through the provider's unified mapper. */
+  async getOrder(
+    params: GetOrderParams,
+    options?: SDKRequestOptions
+  ): Promise<Order> {
+    return fetchOrder(this.sdkClient, params, options)
+  }
+
   /**
    * Ask the provider plugin for the signer-bearing wire fields of `action` —
    * the on-wire `signerAddress` and any signer-derived params (e.g.
@@ -579,6 +611,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

@@ -87,7 +87,7 @@ export { createMemoryStorage } from './storage/storage.js'
 export type { StorageAdapter } from './storage/types.js'
 export { errorCodeFromStatus } from './transport/errorCodeFromStatus.js'
 export type { FetchWithRetryOptions } from './transport/fetchWithRetry.js'
-export { fetchWithRetry } from './transport/fetchWithRetry.js'
+export { fetchWithRetry, isAbortError } from './transport/fetchWithRetry.js'
 export type {
   ProviderRetryConfig,
   ResolvedRetryPolicy,
@@ -111,6 +111,7 @@ export type {
   ExecuteMetaActionParams,
   GetAccountResult,
   GetDepositFlowParams,
+  GetPortfolioHistoryParams,
   GetSetupParams,
   GetWithdrawableBalancesParams,
   ModifyOrdersParams,
@@ -156,9 +157,9 @@ export type {
   ProviderGetMarketSettingsParams,
   ProviderGetOrderParams,
   ProviderGetOrdersParams,
+  ProviderGetPortfolioHistoryParams,
   ProviderGetPositionsParams,
   ProviderGetQuoteParams,
-  ProviderGetRunningTwapsParams,
   ProviderGetWithdrawableBalancesParams,
   QuoteListener,
   SignActionProgress,
@@ -220,9 +221,13 @@ export {
   classifyFill,
   FillClassification,
   isActiveOrderStatus,
+  isRegularOrder,
   isStopLossOrder,
   isTakeProfitOrder,
   isTpSlOrder,
+  isTriggerOrder,
+  isTwapOrder,
+  triggerConditionFor,
 } from './utils/orderClassification.js'
 export {
   expectedRealizedPnlForOpenOrder,
@@ -250,12 +255,14 @@ export type { RemovableIsolatedMarginParams } from './utils/transferMargin.js'
 export { removableIsolatedMargin } from './utils/transferMargin.js'
 export { fromBaseUnits, fromBaseUnitsNumber } from './utils/units.js'
 export { validateMargin } from './utils/validation.js'
+export { createWarnOnce } from './utils/warnOnce.js'
 // Version
 export { name, version } from './version.js'
 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/registry/assetRegistry.ts

@@ -1,19 +1,39 @@
 import type { Asset, AssetsResponse } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
 import { buildUrl, request } from '../transport/request.js'
 import type { PerpsSDKClient } from '../types/provider.js'
 import { ReferenceDataRegistry } from './referenceDataRegistry.js'
 
-/**
- * Per-provider index over the backend's `/assets` token registry, keyed by
- * `Asset.id` — the provider-native asset id (Lighter: the stringified
- * `asset_id`, Hyperliquid spot: the venue token index). Obtain via
- * {@link getAssetRegistry}.
- *
- * @public
- */
+const addressKey = (address: string): string =>
+  /^0x[0-9a-f]{40}$/i.test(address) ? address.toLowerCase() : address
+
+/** Provider `/assets` index by native `id` and by L1 contract address. @public */
 export class AssetRegistry extends ReferenceDataRegistry<Asset> {
   constructor(client: PerpsSDKClient, provider: string) {
-    super(client, provider, 'asset')
+    super(client, provider, 'asset', {
+      l1Address: (asset) =>
+        asset.l1Address === undefined ? undefined : addressKey(asset.l1Address),
+    })
+  }
+
+  /** Lookup by provider identity; hexadecimal L1 addresses are case-insensitive. */
+  override get(id: string, key: 'id' | 'l1Address' = 'id'): Asset | undefined {
+    return key === 'id' ? super.get(id) : this.getByIndex(addressKey(id), key)
+  }
+
+  /** Resolve registry membership or report a stale or mis-keyed asset registry. */
+  require(id: string, key: 'id' | 'l1Address' = 'id'): Asset {
+    const asset = this.get(id, key)
+    if (asset === undefined) {
+      const error = new PerpsError(
+        PerpsErrorCode.ValidationError,
+        `[${this.provider}] stale or mis-keyed asset registry: unknown ${key} '${id}'`
+      )
+      error.tool = this.provider
+      throw error
+    }
+    return asset
   }
 
   /**

package/src/registry/referenceDataRegistry.ts

@@ -1,27 +1,23 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
 import type { PerpsSDKClient } from '../types/provider.js'
+import { createWarnOnce } from '../utils/warnOnce.js'
 
-/**
- * Per-provider hash index over one of the provider's reference-data lists
- * (`/markets`, `/assets`), keyed by the list's own primary key.
- *
- * NOT a cache: it holds no freshness policy of its own. Every {@link sync}
- * refetches through the HTTP layer, whose `cache-control` headers decide
- * whether the response comes from disk or the network. A lookup miss warns
- * once per id and returns `undefined`; subsequent syncs reconcile the index
- * without replaying the warning for an id that remains absent.
- *
- * @internal
- */
+/** Atomic provider reference indexes; HTTP cache headers govern freshness. @internal */
 export abstract class ReferenceDataRegistry<T> {
   private index = new Map<string, T>()
+  private secondaryIndexes = new Map<string, Map<string, T>>()
   private current: readonly T[] = []
   private inflight: Promise<readonly T[]> | undefined
-  private warnedIds = new Set<string>()
+  private readonly warnOnce = createWarnOnce()
 
   protected constructor(
     protected readonly client: PerpsSDKClient,
     readonly provider: string,
-    private readonly kind: string
+    private readonly kind: string,
+    private readonly secondaryKeys: Readonly<
+      Record<string, (item: T) => string | undefined>
+    > = {}
   ) {}
 
   /** Fetch the provider's full list through the HTTP layer. */
@@ -55,16 +51,47 @@ export abstract class ReferenceDataRegistry<T> {
     if (item !== undefined) {
       return item
     }
-    if (!this.warnedIds.has(id)) {
-      this.warnedIds.add(id)
-      console.warn(`[${this.provider}] unknown ${this.kind} id '${id}'`)
-    }
+    this.warnOnce(id, `[${this.provider}] unknown ${this.kind} id '${id}'`)
     return undefined
   }
 
+  protected getByIndex(id: string, key: string): T | undefined {
+    return this.secondaryIndexes.get(key)?.get(id)
+  }
+
   private async load(): Promise<readonly T[]> {
     const items = await this.fetchItems()
-    this.index = new Map(items.map((item) => [this.keyOf(item), item]))
+    const index = new Map<string, T>()
+    for (const item of items) {
+      const key = this.keyOf(item)
+      if (index.has(key)) {
+        throw new PerpsError(
+          PerpsErrorCode.ValidationError,
+          `[${this.provider}] stale or mis-keyed ${this.kind} registry: duplicate id '${key}'`
+        )
+      }
+      index.set(key, item)
+    }
+    const secondaryIndexes = new Map<string, Map<string, T>>()
+    for (const [name, keyOf] of Object.entries(this.secondaryKeys)) {
+      const secondary = new Map<string, T>()
+      for (const item of items) {
+        const key = keyOf(item)
+        if (key === undefined) {
+          continue
+        }
+        if (secondary.has(key)) {
+          throw new PerpsError(
+            PerpsErrorCode.ValidationError,
+            `[${this.provider}] stale or mis-keyed ${this.kind} registry: duplicate ${name} '${key}'`
+          )
+        }
+        secondary.set(key, item)
+      }
+      secondaryIndexes.set(name, secondary)
+    }
+    this.index = index
+    this.secondaryIndexes = secondaryIndexes
     this.current = items
     return items
   }

package/src/services/getOrders.ts

@@ -1,8 +1,9 @@
-import type { OrdersResponse } from '@lifi/perps-types'
+import type { OrderStatus, OrdersResponse } from '@lifi/perps-types'
 import type { Address } from 'viem'
 import { requireProvider } from '../client/requireProvider.js'
 import type { SDKRequestOptions } from '../types/config.js'
 import type { PerpsSDKClient } from '../types/provider.js'
+import { ACTIVE_ORDER_STATUSES } from '../utils/orderClassification.js'
 
 /**
  * Parameters for {@link getOrders}.
@@ -12,6 +13,7 @@ import type { PerpsSDKClient } from '../types/provider.js'
 export interface GetOrdersParams {
   provider: string
   address: Address
+  statuses?: OrderStatus[]
   /** Optional opaque `Market.id` filter, not a display symbol. */
   marketId?: string
   /** Maximum items returned; provider defaults and caps apply. */
@@ -20,22 +22,7 @@ export interface GetOrdersParams {
   cursor?: string
 }
 
-/**
- * Get open orders and trigger orders for an account. Delegates to the
- * registered venue plugin (direct-to-venue); requires the provider plugin to be
- * registered on the client.
- *
- * @throws {PerpsError} When the provider plugin is not registered, or on
- *   backend / network / parsing errors.
- * @example
- * ```ts
- * const { openOrders, triggerOrders } = await getOrders(client, {
- *   provider: 'hyperliquid',
- *   address: '0x1234...',
- * })
- * ```
- * @public
- */
+/** Read account orders with active lifecycle statuses as the default filter. */
 export async function getOrders(
   client: PerpsSDKClient,
   params: GetOrdersParams,
@@ -44,6 +31,7 @@ export async function getOrders(
   return requireProvider(client, params.provider).getOrders(
     {
       address: params.address,
+      statuses: params.statuses ?? [...ACTIVE_ORDER_STATUSES],
       marketId: params.marketId,
       limit: params.limit,
       cursor: params.cursor,

package/src/transport/fetchWithRetry.ts

@@ -18,9 +18,10 @@ export interface FetchWithRetryOptions {
 /**
  * True when `error` is an `AbortSignal` cancellation (the native `fetch` abort
  * rejection) rather than a genuine network failure. An abort is a deliberate
- * caller action, so it is rethrown untouched instead of being retried.
+ * caller action, so every transport rethrows it untouched instead of retrying
+ * it or wrapping it in a provider error.
  *
- * @internal
+ * @public
  */
 export function isAbortError(error: unknown): boolean {
   return error instanceof Error && error.name === 'AbortError'

package/src/types/api.ts

@@ -14,6 +14,7 @@ import type {
   OnboardParams,
   OrderSide,
   OrderType,
+  PortfolioHistoryRange,
   ProviderAction,
   SignedActionStep,
   TimeInForce,
@@ -175,8 +176,8 @@ export interface PlaceOrderParams {
 }
 
 /**
- * Parameters for placing trigger-only orders (TP/SL on existing positions).
- * Sends a TRIGGER_ONLY order that skips the main order wire.
+ * Sends `ActionType.PLACE_TRIGGER_ORDER` with
+ * `{ market, side, takeProfit?, stopLoss? }`.
  *
  * @public
  */
@@ -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

@@ -13,9 +13,12 @@ import type {
   MarketRef,
   MarketSettings,
   Order,
+  OrderStatus,
   OrdersResponse,
   PerpsMarket,
   PerpsSigner,
+  PortfolioHistoryRange,
+  PortfolioHistoryResponse,
   Position,
   PositionMarginConstraints,
   PositionsResponse,
@@ -25,7 +28,6 @@ import type {
   SignedActionStep,
   SigningMethod,
   TradeType,
-  TwapOrder,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
 import type {
@@ -221,6 +223,7 @@ export interface ProviderGetMarketSettingsParams {
  */
 export interface ProviderGetOrdersParams {
   address: Address
+  statuses?: OrderStatus[]
   /** Optional opaque `Market.id` filter (not a display symbol). */
   marketId?: string
   /** Maximum items returned; provider defaults and caps apply. */
@@ -229,17 +232,6 @@ export interface ProviderGetOrdersParams {
   cursor?: string
 }
 
-/**
- * Read params for {@link PerpsProvider.getRunningTwaps}.
- *
- * @public
- */
-export interface ProviderGetRunningTwapsParams {
-  address: Address
-  /** Optional opaque `Market.id` filter (not a display symbol). */
-  marketId?: string
-}
-
 /**
  * Read params for {@link PerpsProvider.getOrder}.
  *
@@ -287,6 +279,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.
@@ -445,15 +447,6 @@ export interface PerpsProviderPlugin {
     options?: SDKRequestOptions
   ): Promise<OrdersResponse>
 
-  /**
-   * Fetch the account's currently running TWAP parent orders directly from the
-   * venue. Child slice orders are excluded.
-   */
-  getRunningTwaps?(
-    params: ProviderGetRunningTwapsParams,
-    options?: SDKRequestOptions
-  ): Promise<TwapOrder[]>
-
   getOrder(
     params: ProviderGetOrderParams,
     options?: SDKRequestOptions
@@ -469,6 +462,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/utils/orderClassification.ts

@@ -1,17 +1,15 @@
-/**
- * Order classification utilities.
- *
- * Type guards and classifiers that operate on SDK types to determine
- * order categories (TP/SL, open/close). These use the OrderType enum
- * for classification — no string matching.
- */
-
-import type { OpenOrder } from '@lifi/perps-types'
+import type {
+  Order,
+  RegularOrder,
+  TriggerOrder,
+  TwapOrder,
+} from '@lifi/perps-types'
 import {
   FillClassification,
   OrderSide,
   OrderStatus,
   OrderType,
+  TriggerCondition,
 } from '@lifi/perps-types'
 import { stringToFloat } from './parse.js'
 
@@ -36,7 +34,7 @@ const SL_TYPES = new Set<OrderType>([
  * Check if an open order is a Take Profit trigger order.
  * @public
  */
-export function isTakeProfitOrder(order: Pick<OpenOrder, 'type'>): boolean {
+export function isTakeProfitOrder(order: Pick<Order, 'type'>): boolean {
   return TP_TYPES.has(order.type)
 }
 
@@ -44,7 +42,7 @@ export function isTakeProfitOrder(order: Pick<OpenOrder, 'type'>): boolean {
  * Check if an open order is a Stop Loss trigger order.
  * @public
  */
-export function isStopLossOrder(order: Pick<OpenOrder, 'type'>): boolean {
+export function isStopLossOrder(order: Pick<Order, 'type'>): boolean {
   return SL_TYPES.has(order.type)
 }
 
@@ -52,17 +50,37 @@ export function isStopLossOrder(order: Pick<OpenOrder, 'type'>): boolean {
  * Check if an open order is a TP or SL trigger order.
  * @public
  */
-export function isTpSlOrder(order: Pick<OpenOrder, 'type'>): boolean {
+export function isTpSlOrder(order: Pick<Order, 'type'>): boolean {
   return TP_TYPES.has(order.type) || SL_TYPES.has(order.type)
 }
 
-/**
- * Order statuses representing an order still resting on the book (visible
- * in `openOrders` / `triggerOrders`). Anything not in this set is terminal —
- * filled, cancelled, rejected, expired — and should be evicted from the
- * cached orders list when seen in a WS update.
- * @public
- */
+/** Narrow an order to a price-activated order. */
+export function isTriggerOrder(order: Order): order is TriggerOrder {
+  return isTpSlOrder(order)
+}
+
+/** Narrow an order to a market or limit order. */
+export function isRegularOrder(order: Order): order is RegularOrder {
+  return order.type === OrderType.MARKET || order.type === OrderType.LIMIT
+}
+
+/** Narrow an order to a time-weighted execution parent. */
+export function isTwapOrder(order: Order): order is TwapOrder {
+  return order.type === OrderType.TWAP
+}
+
+/** Derive the trigger price relation from the trigger type and execution side. */
+export function triggerConditionFor(
+  type: TriggerOrder['type'],
+  side: OrderSide
+): TriggerCondition {
+  const takeProfit = TP_TYPES.has(type)
+  return takeProfit === (side === OrderSide.SELL)
+    ? TriggerCondition.ABOVE
+    : TriggerCondition.BELOW
+}
+
+/** Lifecycle statuses included in order reads by default. */
 export const ACTIVE_ORDER_STATUSES: ReadonlySet<OrderStatus> = new Set([
   OrderStatus.OPEN,
   OrderStatus.PENDING,