@lifi/perps-sdk 13.0.0 → 14.0.0

package/dist/types/version.d.ts

@@ -9,5 +9,5 @@ export declare const name = "@lifi/perps-sdk";
  *
  * @public
  */
-export declare const version = "13.0.0";
+export declare const version = "14.0.0";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk",
-  "version": "13.0.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.3.0"
+    "@lifi/perps-types": "^13.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/client/PerpsClient.ts

@@ -9,6 +9,8 @@ import type {
   MarketRef,
   MarketSettings,
   MetaActionType,
+  Order,
+  OrdersResponse,
   PortfolioHistoryResponse,
   Position,
   PositionMarginConstraints,
@@ -30,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,
@@ -190,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.

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,
@@ -160,7 +160,6 @@ export type {
   ProviderGetPortfolioHistoryParams,
   ProviderGetPositionsParams,
   ProviderGetQuoteParams,
-  ProviderGetRunningTwapsParams,
   ProviderGetWithdrawableBalancesParams,
   QuoteListener,
   SignActionProgress,
@@ -222,9 +221,13 @@ export {
   classifyFill,
   FillClassification,
   isActiveOrderStatus,
+  isRegularOrder,
   isStopLossOrder,
   isTakeProfitOrder,
   isTpSlOrder,
+  isTriggerOrder,
+  isTwapOrder,
+  triggerConditionFor,
 } from './utils/orderClassification.js'
 export {
   expectedRealizedPnlForOpenOrder,
@@ -252,6 +255,7 @@ 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'

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

@@ -176,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
  */

package/src/types/provider.ts

@@ -13,6 +13,7 @@ import type {
   MarketRef,
   MarketSettings,
   Order,
+  OrderStatus,
   OrdersResponse,
   PerpsMarket,
   PerpsSigner,
@@ -27,7 +28,6 @@ import type {
   SignedActionStep,
   SigningMethod,
   TradeType,
-  TwapOrder,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
 import type {
@@ -223,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. */
@@ -231,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}.
  *
@@ -457,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

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,

package/src/utils/orderMath.ts

@@ -1,10 +1,12 @@
 import {
-  type OpenOrder,
   OrderSide,
+  OrderStatus,
   type Position,
   PositionSide,
+  type RegularOrder,
   type TriggerOrder,
 } from '@lifi/perps-types'
+import { isActiveOrderStatus } from './orderClassification.js'
 import { realizedPnlOnClose } from './positionMath.js'
 
 /**
@@ -55,10 +57,10 @@ export function resolveCloseSize(
  * @public
  */
 export function expectedRealizedPnlForOpenOrder(
-  order: OpenOrder,
+  order: RegularOrder,
   position: Position | undefined
 ): number | null {
-  if (!position) {
+  if (!position || !isActiveOrderStatus(order.status)) {
     return null
   }
 
@@ -70,7 +72,7 @@ export function expectedRealizedPnlForOpenOrder(
     return null
   }
 
-  const limitPrice = Number.parseFloat(order.price)
+  const limitPrice = Number.parseFloat(order.price ?? '')
   const entryPrice = Number.parseFloat(position.entryPrice)
   const orderSize = Math.abs(Number.parseFloat(order.remainingSize))
   const positionSize = Math.abs(Number.parseFloat(position.size))
@@ -100,29 +102,29 @@ export function expectedRealizedPnlForOpenOrder(
   })
 }
 
-/**
- * Expected rPnL for a TP/SL trigger order against a matching position.
- *
- * A trigger order is by construction a closing leg — its direction is the
- * opposite of the position's. With no matching position there is nothing to
- * close, so rPnL is `null`. The trigger price (always present on the SDK
- * `TriggerOrder` shape) is used as the rPnL price; the optional `limitPrice`
- * for STOP_LIMIT / TAKE_PROFIT_LIMIT is the post-trigger limit, not the rPnL
- * price.
- * @public
- */
+/** Project the unfilled closing quantity of an active trigger at its trigger price. */
 export function expectedRealizedPnlForTriggerOrder(
   order: TriggerOrder,
   position: Position | undefined
 ): number | null {
-  if (!position) {
+  if (
+    !position ||
+    !isActiveOrderStatus(order.status) ||
+    order.status === OrderStatus.PENDING
+  ) {
     return null
   }
 
   const isLong = position.side === PositionSide.LONG
+  if (
+    (isLong && order.side !== OrderSide.SELL) ||
+    (!isLong && order.side !== OrderSide.BUY)
+  ) {
+    return null
+  }
   const triggerPrice = Number.parseFloat(order.triggerPrice)
   const entryPrice = Number.parseFloat(position.entryPrice)
-  const orderSize = Math.abs(Number.parseFloat(order.size))
+  const orderSize = Math.abs(Number.parseFloat(order.remainingSize))
   const positionSize = Math.abs(Number.parseFloat(position.size))
   if (
     !Number.isFinite(triggerPrice) ||
@@ -133,6 +135,12 @@ export function expectedRealizedPnlForTriggerOrder(
   ) {
     return null
   }
+  if (
+    orderSize === 0 &&
+    (Number.parseFloat(order.originalSize) !== 0 || !order.reduceOnly)
+  ) {
+    return null
+  }
 
   const closeSize = resolveCloseSize(orderSize, positionSize)
   return realizedPnlOnClose({

package/src/utils/warnOnce.ts

@@ -0,0 +1,29 @@
+/**
+ * The number of keys one warner remembers. Venue wire data supplies the keys,
+ * so the memory must not grow for as long as the process runs.
+ */
+const KEY_MEMORY_LIMIT = 256
+
+/**
+ * Build a warner that writes each distinct key once. The warner forgets the
+ * oldest key when its memory is full, so a key it saw long ago can warn a
+ * second time.
+ *
+ * @internal
+ */
+export const createWarnOnce = (): ((key: string, message: string) => void) => {
+  const seen = new Set<string>()
+  return (key, message) => {
+    if (seen.has(key)) {
+      return
+    }
+    if (seen.size >= KEY_MEMORY_LIMIT) {
+      const oldest = seen.values().next().value
+      if (oldest !== undefined) {
+        seen.delete(oldest)
+      }
+    }
+    seen.add(key)
+    console.warn(message)
+  }
+}

package/src/version.ts

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