@lifi/perps-types 12.2.0 → 13.0.0

package/src/account.ts

@@ -3,15 +3,17 @@ import type {
   ActionType,
   ActivityType,
   FillClassification,
-  FillStatus,
   LiquidityRole,
   MarginMode,
   OrderSide,
+  OrderStatus,
   OrderType,
   PositionSide,
+  TimeInForce,
+  TriggerCondition,
 } from './enums.js'
 import type { MarketDisplay, PerpsMarketDisplay } from './market.js'
-import type { Address } from './primitives.js'
+import type { Address, ProviderId } from './primitives.js'
 
 /**
  * Maker and taker fee rates for the account's current venue tier.
@@ -80,33 +82,63 @@ export interface PositionMarginConstraints {
   amountIncrement: string
 }
 
-/**
- * Normalized non-trigger order currently open at a provider.
- *
- * @public
- */
-export interface OpenOrder {
+/** Shared identity, quantities, and lifecycle of a venue order. */
+export interface OrderBase {
+  /** Venue-assigned id: Hyperliquid `oid`, Lighter `order_index`, Ondo `orderId`. */
   orderId: string
+  /** Client-set id, absent when the placer set none. */
+  clientOrderId?: string
   market: MarketDisplay
   side: OrderSide
-  type: OrderType
-  /** Quantity the order was submitted for, in base-asset units. */
+  status: OrderStatus
+  /** Venue text for a REJECTED or CANCELLED order, when the venue gives one. */
+  statusReason?: string
   originalSize: string
-  /** Quantity still resting on the book, in base-asset units. */
   remainingSize: string
-  /** Limit/order price in quote-asset units. */
-  price: string
-  /** Quantity already filled in base-asset units. */
   filledSize: string
+  averagePrice?: string
   reduceOnly: boolean
-  label?: string
-  /** ISO-8601 creation timestamp. */
+  /** Parent of a placement TP/SL leg or TWAP child; absent on position-level triggers. */
+  parentOrderId?: string
+  /** Set only when the venue row carries a transaction hash. */
+  explorerLink?: string
   createdAt: string
+  updatedAt: string
+}
+
+/** Market or limit order with a time-in-force policy. */
+export interface RegularOrder extends OrderBase {
+  type: OrderType.MARKET | OrderType.LIMIT
+  price?: string
+  timeInForce: TimeInForce
+  expiresAt?: string
 }
 
+/** Price-activated take-profit or stop-loss order. */
+export interface TriggerOrder extends OrderBase {
+  type:
+    | OrderType.STOP_MARKET
+    | OrderType.STOP_LIMIT
+    | OrderType.TAKE_PROFIT_MARKET
+    | OrderType.TAKE_PROFIT_LIMIT
+  triggerPrice: string
+  triggerCondition: TriggerCondition
+  limitPrice?: string
+}
+
+/** Time-weighted execution parent. */
+export interface TwapOrder extends OrderBase {
+  type: OrderType.TWAP
+  durationSeconds: number
+  startedAt: string
+}
+
+/** Venue order discriminated only by its execution type. */
+export type Order = RegularOrder | TriggerOrder | TwapOrder
+
 /**
- * Asset balance normalized across providers. `units` and `valueUsd` are
- * decimal strings; `valueUsd` is the balance's USD valuation.
+ * Asset balance normalized across providers. `units`, `price` and `valueUsd`
+ * are decimal strings; `valueUsd` is the balance's USD valuation.
  *
  * @public
  */
@@ -117,6 +149,8 @@ export interface Balance {
   units: string
   /** USD value the SDK fills from the prices map; consumers render with zero math. */
   valueUsd: string
+  /** USD price of one unit. Absent when the provider holds no price for the asset. */
+  price?: string
   /**
    * Fraction of `valueUsd` that backs available margin (a loan-to-value
    * ratio). Absent means 1 — full value. Set below 1 for collateral the
@@ -179,25 +213,6 @@ export interface MarketSettings {
   leverage: number
 }
 
-/**
- * Normalized take-profit or stop-loss order waiting for its trigger condition.
- *
- * @public
- */
-export interface TriggerOrder {
-  orderId: string
-  market: MarketDisplay
-  type: OrderType
-  /** Triggered quantity in base-asset units. */
-  size: string
-  /** Price at which the trigger activates, in quote-asset units. */
-  triggerPrice: string
-  /** Optional limit price submitted after activation, in quote-asset units. */
-  limitPrice?: string
-  label?: string
-  createdAt: string
-}
-
 /**
  * Paginated open-position response for one provider and account.
  *
@@ -209,15 +224,10 @@ export interface PositionsResponse {
   pagination: Pagination
 }
 
-/**
- * Paginated open-order response containing regular and trigger orders.
- *
- * @public
- */
+/** Paginated order response for the requested lifecycle statuses. */
 export interface OrdersResponse {
-  provider: string
-  openOrders: OpenOrder[]
-  triggerOrders: TriggerOrder[]
+  provider: ProviderId
+  orders: Order[]
   pagination: Pagination
 }
 
@@ -258,7 +268,6 @@ export interface Fill {
   type?: OrderType
   size: string
   price: string
-  status: FillStatus
   liquidity: LiquidityRole
   filledSize?: string
   /** Absent when the venue reports no fee for the fill. */
@@ -334,11 +343,7 @@ export interface BaseActivity {
  */
 export interface DepositActivity extends BaseActivity {
   type: ActivityType.DEPOSIT
-  /**
-   * Display symbol of the deposited asset, resolved by the provider adapter.
-   * Falls back to the venue's own asset id when the registry knows no symbol.
-   */
-  asset: string
+  asset: Asset
   amount: string
   /**
    * Address the deposited funds came from, as the venue reports it. Absent
@@ -357,11 +362,7 @@ export interface DepositActivity extends BaseActivity {
  */
 export interface WithdrawalActivity extends BaseActivity {
   type: ActivityType.WITHDRAWAL
-  /**
-   * Display symbol of the withdrawn asset, resolved by the provider adapter.
-   * Falls back to the venue's own asset id when the registry knows no symbol.
-   */
-  asset: string
+  asset: Asset
   amount: string
   /** Absent when the venue reports no fee for the withdrawal. */
   fee?: Fee
@@ -439,7 +440,7 @@ export interface FundingActivity extends BaseActivity {
 export type TransferActivity = BaseActivity & {
   type: ActivityType.TRANSFER
   direction: 'IN' | 'OUT'
-  asset: string
+  asset: Asset
   amount: string
   /**
    * Every fee the venue charged for the transfer, in the order the venue
@@ -552,7 +553,12 @@ export interface LighterAccountConfig {
    */
   apiKeyIndex?: number
   apiKeyRegistered: boolean
-  /** Lighter `account_type`. Upstream documents no integer for any tier. */
+  /**
+   * Lighter `account_type`: the `SubAccountType` of this account
+   * (`Main` = 0, `Sub` = 1, `Public` = 2, `LighterPublic` = 3,
+   * `Staking` = 4). It is not an account tier — the tier is
+   * {@link LighterAccountConfig.userTierName}.
+   */
   accountType: number
   /**
    * Lighter `user_tier_name` from `/accountLimits`, in the tier vocabulary

package/src/action.ts

@@ -3,14 +3,11 @@ import type {
   ActionType,
   MarginMode,
   OrderSide,
-  OrderStatus,
   OrderType,
   PerpsErrorCode,
   TimeInForce,
-  TriggerCondition,
-  TwapOrderStatus,
 } from './enums.js'
-import type { MarketDisplay, MarketRef } from './market.js'
+import type { MarketRef } from './market.js'
 import type { Address, Hex } from './primitives.js'
 import type { CreateReferralCodeParams, OnboardParams } from './referral.js'
 import type { PerpsTypedData } from './typedData.js'
@@ -296,35 +293,6 @@ export interface ModifyOrderInput {
   limitPrice?: string
 }
 
-/**
- * Normalized order returned by a provider, including lifecycle and trigger
- * metadata. Quantities and prices are decimal strings.
- *
- * @public
- */
-export interface Order {
-  orderId: string
-  market: MarketDisplay
-  side: OrderSide
-  type: OrderType
-  price?: string
-  originalSize: string
-  remainingSize: string
-  filledSize: string
-  timeInForce?: TimeInForce
-  expiresAt?: string
-  reduceOnly?: boolean
-  isTrigger?: boolean
-  triggerPrice?: string
-  triggerCondition?: TriggerCondition
-  status: OrderStatus
-  /** Human-readable reason for a terminal non-FILLED status; undefined when no actionable detail. */
-  statusReason?: string
-  averagePrice?: string
-  createdAt: string
-  updatedAt: string
-}
-
 /**
  * Parameters for placing a regular order on a market.
  *
@@ -403,30 +371,6 @@ export interface CancelTwapOrderParams {
   twapId: string
 }
 
-/**
- * Normalized running-TWAP read model returned by provider TWAP queries.
- * Quantities and prices are decimal strings.
- *
- * @public
- */
-export interface TwapOrder {
-  /** Provider-native TWAP identifier, stringified (see {@link CancelTwapOrderParams.twapId}). */
-  twapId: string
-  market: MarketDisplay
-  side: OrderSide
-  /** Total base-asset size the TWAP was placed for. */
-  totalSize: string
-  /** Base-asset size executed so far. */
-  filledSize: string
-  /** Volume-weighted average fill price; absent until the first child fill. */
-  avgFillPrice?: string
-  /** ISO-8601 timestamp at which the TWAP started executing. */
-  startedAt: string
-  /** Total execution window in seconds. */
-  durationSeconds: number
-  status: TwapOrderStatus
-}
-
 /**
  * Parameters for cancelling one or more venue orders.
  *

package/src/enums.ts

@@ -82,8 +82,7 @@ export enum OrderType {
   STOP_LIMIT = 'STOP_LIMIT',
   TAKE_PROFIT_MARKET = 'TAKE_PROFIT_MARKET',
   TAKE_PROFIT_LIMIT = 'TAKE_PROFIT_LIMIT',
-  TRIGGER_ONLY = 'TRIGGER_ONLY',
-  /** Read-side only: TWAP parents/children surfaced in venue order feeds. Excluded from `PlaceOrderParams.type` — placement goes through `ActionType.PLACE_TWAP_ORDER`. */
+  /** Returned on SDK reads; placement uses `ActionType.PLACE_TWAP_ORDER`. */
   TWAP = 'TWAP',
 }
 
@@ -119,24 +118,24 @@ export enum TimeInForce {
 
 /** Lifecycle status of a provider order. @public */
 export enum OrderStatus {
+  /** A placement TP/SL leg waits for its parent order to fill. */
   PENDING = 'PENDING',
+  /** Live on the book, or an armed trigger waiting for its trigger price. */
   OPEN = 'OPEN',
+  /** Open with a positive filled size. */
   PARTIALLY_FILLED = 'PARTIALLY_FILLED',
+  /** Terminal: the order filled. */
   FILLED = 'FILLED',
+  /** Terminal: the order was cancelled; statusReason carries the venue reason. */
   CANCELLED = 'CANCELLED',
+  /** Terminal: the order was rejected; statusReason carries the venue reason. */
   REJECTED = 'REJECTED',
+  /** Terminal: the order expired. */
   EXPIRED = 'EXPIRED',
+  /** The trigger price was hit and the order went live. */
   TRIGGERED = 'TRIGGERED',
 }
 
-/** Lifecycle status of an execution/fill. @public */
-export enum FillStatus {
-  FILLED = 'FILLED',
-  PARTIALLY_FILLED = 'PARTIALLY_FILLED',
-  CANCELLED = 'CANCELLED',
-  REJECTED = 'REJECTED',
-}
-
 /** Whether a fill supplied maker or taker liquidity. @public */
 export enum LiquidityRole {
   MAKER = 'maker',
@@ -194,26 +193,6 @@ export enum TriggerCondition {
   BELOW = 'BELOW',
 }
 
-/** Take-profit or stop-loss trigger order classification. @public */
-export enum TriggerOrderType {
-  TAKE_PROFIT = 'TAKE_PROFIT',
-  STOP_LOSS = 'STOP_LOSS',
-}
-
-/** Lifecycle status of a trigger order. @public */
-export enum TriggerOrderStatus {
-  WAITING = 'WAITING',
-  TRIGGERED = 'TRIGGERED',
-  CANCELLED = 'CANCELLED',
-}
-
-/** Lifecycle status of a running TWAP order. @public */
-export enum TwapOrderStatus {
-  RUNNING = 'RUNNING',
-  COMPLETED = 'COMPLETED',
-  CANCELLED = 'CANCELLED',
-}
-
 /** Account activity record categories. @public */
 export enum ActivityType {
   DEPOSIT = 'DEPOSIT',

package/src/index.ts

@@ -16,6 +16,7 @@ export * from './errors.js'
 export * from './market.js'
 export * from './meta.js'
 export * from './metaProvider.js'
+export * from './portfolioHistory.js'
 export * from './positionMargin.js'
 export * from './primitives.js'
 export * from './providers.js'

package/src/portfolioHistory.ts

@@ -0,0 +1,27 @@
+/** Lookback window of a portfolio history read. @public */
+export type PortfolioHistoryRange = '24h' | '7d' | '30d' | 'all'
+
+/**
+ * One sample of the account's portfolio over time. All values are decimal
+ * strings in USD.
+ * @public
+ */
+export interface PortfolioHistoryPoint {
+  /** Unix milliseconds. */
+  timestamp: number
+  accountValue: string
+  /** Cumulative PnL from the start of the requested window. */
+  pnl: string
+}
+
+/**
+ * Account portfolio value over the requested window, oldest point first.
+ * `volume` and `totalPnl` are window totals a venue may not report.
+ * @public
+ */
+export interface PortfolioHistoryResponse {
+  range: PortfolioHistoryRange
+  points: PortfolioHistoryPoint[]
+  volume?: string
+  totalPnl?: string
+}

package/src/primitives.ts

@@ -13,3 +13,6 @@ export type Address = `0x${string}`
  * @public
  */
 export type Hex = `0x${string}`
+
+/** Opaque provider key assigned by the provider registry. */
+export type ProviderId = string

package/src/subscriptions.ts

@@ -2,9 +2,8 @@ import type {
   AccountSummary,
   Balance,
   Fill,
-  OpenOrder,
+  Order,
   Position,
-  TriggerOrder,
 } from './account.js'
 import type {
   Candle,
@@ -121,14 +120,8 @@ export type TradesEvent = { channel: 'trades'; data: Trade[] }
 export type OrderUpdatesEvent = {
   channel: 'orderUpdates'
   data: {
-    /** Upserts — active orders, non-trigger. */
-    openOrders: OpenOrder[]
-    /** Upserts — active orders with trigger semantics (TP/SL). */
-    triggerOrders: TriggerOrder[]
-    /**
-     * orderIds whose status just transitioned to terminal (filled, cancelled,
-     * rejected, expired). Consumers should evict these from both buckets.
-     */
+    orders: Order[]
+    /** Terminal order ids to evict from an active-order cache. */
     terminated: string[]
   }
 }