@lifi/perps-sdk 0.0.0-preview-050dcd3 → 0.0.0-preview-ef23ec2

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,

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/version.ts

@@ -10,4 +10,4 @@ export const name = '@lifi/perps-sdk'
  *
  * @public
  */
-export const version = '0.0.0-preview-050dcd3'
+export const version = '0.0.0-preview-ef23ec2'

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