@lifi/perps-types 0.1.1-alpha.9 → 0.2.0-alpha.0

package/src/account.ts

@@ -1,7 +1,11 @@
 import type { Address } from './typedData.js'
+import type { AssetDisplay } from './asset.js'
 import type {
+  ActionType,
   ActivityType,
-  HistoryItemStatus,
+  FillClassification,
+  FillStatus,
+  LiquidityRole,
   MarginMode,
   OrderSide,
   OrderType,
@@ -14,9 +18,7 @@ export interface FeeTier {
 }
 
 export interface Position {
-  symbol: string
-  assetId: number
-  dex: string
+  asset: AssetDisplay
   side: PositionSide
   size: string
   entryPrice: string
@@ -30,15 +32,14 @@ export interface Position {
 
 export interface OpenOrder {
   id: string
-  symbol: string
-  assetId: number
-  dex: string
+  asset: AssetDisplay
   side: OrderSide
   type: OrderType
   size: string
   price: string
   filledSize: string
   reduceOnly: boolean
+  label?: string
   createdAt: string
 }
 
@@ -48,30 +49,61 @@ export interface Balance {
 }
 
 export interface AccountResponse {
-  dex: string
+  provider: string
   address: Address
-  balances: Balance[]
+  balances: Record<string, Balance[]>
   marginUsed: string
   unrealizedPnl: string
   feeTier: FeeTier
+  /**
+   * Per-provider account state, strongly typed and discriminated on
+   * `config.provider`. Consumers narrow with `config.provider === 'hyperliquid'`
+   * etc. to get access to the provider-specific fields. There is no untyped
+   * escape hatch — fields specific to a future provider belong on a new
+   * variant of `AccountConfig`, not on a generic `Record<string, unknown>`.
+   */
+  config: AccountConfig
+}
+
+export interface TriggerOrder {
+  id: string
+  asset: AssetDisplay
+  type: OrderType
+  size: string
+  triggerPrice: string
+  limitPrice?: string
+  label?: string
+  createdAt: string
+}
+
+export interface PositionsResponse {
+  provider: string
   positions: Position[]
+  pagination: Pagination
+}
+
+export interface OrdersResponse {
+  provider: string
   openOrders: OpenOrder[]
-  config: Record<string, unknown>
+  triggerOrders: TriggerOrder[]
+  pagination: Pagination
 }
 
-export interface HistoryItem {
+export interface Fill {
   id: string
-  symbol: string
-  assetId: number
-  dex: string
+  orderId: string
+  asset: AssetDisplay
   side: OrderSide
   type: OrderType
   size: string
   price: string
-  status: HistoryItemStatus
+  status: FillStatus
+  liquidity: LiquidityRole
   filledSize?: string
   fee?: string
   realizedPnl?: string | null
+  startPosition?: string
+  classification: FillClassification
   createdAt: string
 }
 
@@ -82,9 +114,9 @@ export interface Pagination {
   nextUrl?: string
 }
 
-export interface HistoryResponse {
-  dex: string
-  items: HistoryItem[]
+export interface FillsResponse {
+  provider: string
+  items: Fill[]
   pagination: Pagination
 }
 
@@ -94,7 +126,7 @@ export interface HistoryResponse {
 
 export interface BaseActivity {
   id: string
-  dex: string
+  provider: string
   timestamp: string
 }
 
@@ -110,7 +142,7 @@ export interface WithdrawalActivity extends BaseActivity {
 }
 
 export interface LiquidatedPosition {
-  symbol: string
+  asset: AssetDisplay
   size: string
 }
 
@@ -124,20 +156,159 @@ export interface LiquidationActivity extends BaseActivity {
 
 export interface FundingActivity extends BaseActivity {
   type: ActivityType.FUNDING
-  symbol: string
+  asset: AssetDisplay
   amount: string
   positionSize: string
   fundingRate: string
 }
 
+/**
+ * Internal transfer between two accounts on the same provider (e.g. Lighter
+ * `/api/v1/transfer/history`, Hyperliquid `spotTransfer` ledger entry).
+ * Direction is relative to the queried account.
+ *
+ * The counterparty is identified by either an account index (integer L2
+ * account identifier — Lighter) or a wallet address (Hyperliquid, where
+ * accounts ARE addresses). The type is a discriminated union over these two
+ * shapes: at least one of `counterpartyAccountIndex` / `counterpartyAddress`
+ * MUST be present, and either may appear alone or alongside the other.
+ *
+ * Consumers that render counterparties should prefer `counterpartyAccountIndex`
+ * when present (it's the canonical handle on index-based providers) and fall
+ * back to a truncated `counterpartyAddress` otherwise.
+ */
+export type TransferActivity = BaseActivity & {
+  type: ActivityType.TRANSFER
+  direction: 'IN' | 'OUT'
+  asset: string
+  amount: string
+  meta?: Record<string, unknown>
+} & (
+    | { counterpartyAccountIndex: number; counterpartyAddress?: string }
+    | { counterpartyAccountIndex?: number; counterpartyAddress: string }
+  )
+
 export type ActivityItem =
   | DepositActivity
   | WithdrawalActivity
   | LiquidationActivity
   | FundingActivity
+  | TransferActivity
 
 export interface ActivitiesResponse {
-  dex: string
+  provider: string
   items: ActivityItem[]
   pagination: Pagination
 }
+
+// ---------------------------------------------------------------------------
+// Account configuration state — typed `AccountResponse.config`
+// ---------------------------------------------------------------------------
+
+/**
+ * Hyperliquid record describing one authorised agent wallet on the
+ * `userExtraAgents` response. Shape mirrors what the Hyperliquid info API
+ * returns; the backend forwards the entries verbatim. The widget renders the
+ * count / expiry on the `APPROVE_AGENT` setup descriptor.
+ */
+export type HyperliquidAgent = Record<string, unknown>
+
+/**
+ * Hyperliquid builder-fee approval state. Surfaced by the backend after
+ * comparing the user's `maxBuilderFee` against the configured LI.FI builder
+ * fee for this dex. The widget uses `approved: false` to badge
+ * `APPROVE_BUILDER_FEE` as outstanding.
+ */
+export interface HyperliquidBuilderFeeApproval {
+  builderAddress: string
+  /** Maximum fee rate the user must approve, in basis points as a string. */
+  maxFeeRate: string
+  approved: boolean
+}
+
+/**
+ * Hyperliquid-specific account configuration state.
+ *
+ * `abstractionMode: null` means abstraction has never been set; consumers
+ * should fall back to the descriptor's `default` `ParamOption`.
+ *
+ * `builderFeeApproval` is absent when no builder is configured for this
+ * provider; when present, `approved` reports whether the user has signed the
+ * maximum builder fee.
+ */
+export interface HyperliquidAccountConfig {
+  provider: 'hyperliquid'
+  abstractionMode: string | null
+  agents: HyperliquidAgent[]
+  builderFeeApproval?: HyperliquidBuilderFeeApproval
+}
+
+/**
+ * Lighter-specific account configuration state.
+ *
+ * `accountIndex` is the L2 integer account identifier.
+ *
+ * `apiKeyRegistered` reports whether a key is currently live in the
+ * `apiKeyIndex` slot; the `REGISTER_API_KEY` setup descriptor gates trading
+ * on this.
+ *
+ * `accountType` is the raw integer fee/latency tier from Lighter's
+ * `/api/v1/account.account_type` — decoding to a human label is left to the
+ * consumer.
+ *
+ * `readOnlyTokenApproved` mirrors `apiKeyRegistered`'s shape but for the
+ * long-lived read-only token. When `true`, `readOnlyTokenExpiry` and
+ * `readOnlyTokenScope` MUST be present; when `false`, both MUST be absent.
+ * The `APPROVE_READ_ONLY_TOKEN` setup descriptor gates query-only access on
+ * this flag.
+ */
+export interface LighterAccountConfig {
+  provider: 'lighter'
+  accountIndex: number
+  apiKeyIndex: number
+  apiKeyRegistered: boolean
+  accountType: number
+  readOnlyTokenApproved: boolean
+  /** Unix seconds. Present iff `readOnlyTokenApproved === true`. */
+  readOnlyTokenExpiry?: number
+  /** Lighter's documented `single | all` scope. Present iff `readOnlyTokenApproved === true`. */
+  readOnlyTokenScope?: 'single' | 'all'
+}
+
+/**
+ * Discriminated union of per-provider account configuration state.
+ * Narrow with `config.provider === '<key>'` to access provider-specific
+ * fields. Adding a new provider means adding a new variant, NOT widening
+ * to a record-keyed shape.
+ */
+export type AccountConfig = HyperliquidAccountConfig | LighterAccountConfig
+
+/**
+ * The current value of a single descriptor parameter, as projected by the
+ * SDK from the typed `AccountConfig` for widget consumption.
+ *
+ * `name` matches `Param.name` on the descriptor that produced it; `value`
+ * is the current state in the primitive shape the descriptor declared.
+ * `null` indicates "no current value" (the user has not made a selection
+ * yet, or the provider has not surfaced one), and the widget should fall
+ * back to the descriptor's `default` `ParamOption` (when present) or
+ * render the control with no highlight.
+ */
+export interface AccountConfigValue {
+  name: string
+  value: string | number | boolean | null
+}
+
+/**
+ * SDK projection of `AccountConfig` against a single descriptor — one
+ * `AccountConfigSetting` per descriptor on `Provider.setup` /
+ * `Provider.options`. `values` carries the current state for each `Param`
+ * the descriptor declared.
+ *
+ * Consumers must NOT read `AccountConfig` directly — narrow through this
+ * projection so a new provider variant doesn't require widget changes.
+ */
+export interface AccountConfigSetting {
+  type: ActionType
+  values: AccountConfigValue[]
+}

package/src/action.ts

@@ -0,0 +1,324 @@
+import type { MarginMode, OrderType } from './enums.js'
+import {
+  type ActionType,
+  type OrderSide,
+  type OrderStatus,
+  type TimeInForce,
+  type TriggerCondition,
+} from './enums.js'
+import type { Address, Hex, PerpsTypedData } from './typedData.js'
+import type { AssetIdentity, AssetDisplay } from './asset.js'
+
+// ActionStep variants (create → sign → execute). The SDK picks the variant
+// from the provider's `signingMethod` on `/providers`:
+//   Eip712   — EIP-712 typed data + ECDSA signature
+//   WasmBlob — WASM signer output ({txType, txInfo, txHash})
+//   EvmTx    — plain EVM transaction
+export interface Eip712ActionStep {
+  action: ActionType
+  typedData: PerpsTypedData
+}
+
+export interface WasmBlobActionStep {
+  action: ActionType
+  wasmSignParams: Record<string, unknown>
+}
+
+export interface EvmTxActionStep {
+  action: ActionType
+  txParams: Record<string, unknown>
+}
+
+export type ActionStep = Eip712ActionStep | WasmBlobActionStep | EvmTxActionStep
+
+export interface Eip712SignedActionStep {
+  action: ActionType
+  typedData: PerpsTypedData
+  signature: Hex
+}
+
+export interface WasmBlobSignedActionStep {
+  action: ActionType
+  wasmSignParams: Record<string, unknown>
+  signedTx: {
+    txType: number
+    txInfo: string
+    txHash: string
+  }
+}
+
+export interface EvmTxSignedActionStep {
+  action: ActionType
+  txParams: Record<string, unknown>
+  txHash: string
+}
+
+export type SignedActionStep =
+  | Eip712SignedActionStep
+  | WasmBlobSignedActionStep
+  | EvmTxSignedActionStep
+
+export type ActionResult =
+  | {
+      action: ActionType
+      success: true
+      orderId?: string
+    }
+  | {
+      action: ActionType
+      success: false
+      error: string
+    }
+
+// ---------------------------------------------------------------------------
+// Shared data types
+// ---------------------------------------------------------------------------
+
+export interface TriggerOrderInput {
+  triggerPrice: string
+  limitPrice?: string
+}
+
+export interface ModifyOrderInput {
+  id: string
+  price?: string
+  size?: string
+  triggerPrice?: string
+  limitPrice?: string
+}
+
+export interface Order {
+  orderId: string
+  asset: AssetDisplay
+  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 English sentence describing *why* the order ended in a
+   * terminal non-FILLED state (e.g. slippage exceeded, reduce-only would
+   * not reduce, expiry). Populated only when the provider exposes a
+   * specific cancellation/rejection reason; `undefined` for non-terminal
+   * statuses, plain `filled`, and bare cancels/rejects with no actionable
+   * detail.
+   */
+  statusReason?: string
+  averagePrice?: string
+  createdAt: string
+  updatedAt: string
+}
+
+// ---------------------------------------------------------------------------
+// Per-action param types
+// ---------------------------------------------------------------------------
+
+export interface PlaceOrderParams {
+  asset: AssetIdentity
+  side: OrderSide
+  type?: OrderType
+  size: string
+  price?: string
+  leverage?: number
+  /**
+   * Margin mode to use for the position. When omitted, the backend falls back
+   * to the provider's default (currently CROSS for both Hyperliquid and
+   * Lighter). Callers should set this explicitly when they need ISOLATED.
+   */
+  marginMode?: MarginMode
+  reduceOnly?: boolean
+  timeInForce?: TimeInForce
+  expiresAt?: string
+  takeProfit?: TriggerOrderInput
+  stopLoss?: TriggerOrderInput
+}
+
+export interface PlaceTriggerOrderParams {
+  asset: AssetIdentity
+  side: OrderSide
+  takeProfit?: TriggerOrderInput
+  stopLoss?: TriggerOrderInput
+}
+
+export interface CancelOrderParams {
+  ids: string[]
+}
+
+export interface ModifyOrderParams {
+  modifications: ModifyOrderInput[]
+}
+
+export interface UpdateLeverageParams {
+  asset: AssetIdentity
+  leverage: number
+  /**
+   * Margin mode to use for the position. When omitted, the backend falls back
+   * to the provider's default (currently CROSS for both Hyperliquid and
+   * Lighter). Callers should set this explicitly when they need ISOLATED.
+   */
+  marginMode?: MarginMode
+}
+
+export interface UpdatePositionMarginParams {
+  asset: AssetIdentity
+  action: 'add' | 'remove'
+  amount: string
+}
+
+export interface WithdrawalParams {
+  destination: Address
+  amount: string
+}
+
+export interface DepositParams {
+  /** Amount of the token to deposit (human-readable, e.g. "100.5"). */
+  amount: string
+  /** ERC-20 token address on the source chain. */
+  tokenAddress: Address
+  /** Chain ID of the source chain (e.g. 1 for Ethereum, 42161 for Arbitrum). */
+  chainId: number
+}
+
+export interface ApproveAgentParams {
+  agentAddress: string
+  agentTtlMs?: number
+}
+
+/**
+ * Params for `ActionType.ACCOUNT_MODE` — switch the account's operating
+ * mode (e.g. HL abstraction variant, Lighter UTA / Simple). The string
+ * is opaque per-provider; the authoritative enumeration of valid values
+ * lives on the descriptor's `Param.values` array (see
+ * `ProviderActionDescriptor` in `providers.ts`). The SDK and backend are
+ * responsible for validating `mode` against that array — `@lifi/perps-types`
+ * intentionally does not encode the per-provider value list here, so a
+ * provider can add a new mode without a types release.
+ */
+export interface AccountModeParams {
+  mode: string
+}
+
+/**
+ * Params for `ActionType.ACCOUNT_TYPE` — switch the account's fee/latency
+ * tier (e.g. Lighter standard / premium). Providers without tiering omit
+ * the action entirely; the descriptor's `Param.values` array enumerates
+ * the valid tiers for providers that do support it.
+ */
+export interface AccountTypeParams {
+  tier: string
+}
+
+export interface SendAssetParams {
+  collateral: string
+  sourceDex: string
+  destinationDex: string
+  amount: string
+}
+
+// ---------------------------------------------------------------------------
+// ActionParamsMap — compile-time type resolution for SDK
+// ---------------------------------------------------------------------------
+
+export interface CancelAllOrdersParams {
+  /** 0=immediate (cancel GTC), 1=scheduled, 2=abort scheduled */
+  timeInForce: number
+  /** Unix timestamp in milliseconds (required for scheduled cancels) */
+  timestampMs?: number
+}
+
+export interface RegisterApiKeyParams {
+  /** The API key slot index to register (0-255). Reusing a fixed slot overwrites the old key. */
+  apiKeyIndex: number
+}
+
+/**
+ * Params for `ActionType.APPROVE_READ_ONLY_TOKEN` — mint a long-lived
+ * read-only token Lighter recognises for query-only access (positions,
+ * fills, balances). The token format on the wire is
+ * `ro:{accountIndex}:{scope}:{expiry}:{rand}`; this type carries only the
+ * inputs needed to construct that token, not the token itself.
+ *
+ * `expirySeconds` is the absolute unix-seconds expiry. Lighter constrains
+ * the lifetime to a minimum of 1 day and a maximum of 10 years from now;
+ * the SDK and backend are responsible for enforcing those bounds.
+ *
+ * `scope` mirrors Lighter's documented `single | all` literal:
+ * - `'single'` — token authorises read access to one account only.
+ * - `'all'` — token authorises read access to every account owned by the
+ *   signer. Default for the perps stack today.
+ */
+export interface ApproveReadOnlyTokenParams {
+  accountIndex: number
+  expirySeconds: number
+  scope: 'single' | 'all'
+}
+
+export interface ActionParamsMap {
+  [ActionType.APPROVE_AGENT]: ApproveAgentParams
+  [ActionType.APPROVE_BUILDER_FEE]: Record<string, never>
+  [ActionType.ACCOUNT_MODE]: AccountModeParams
+  [ActionType.ACCOUNT_TYPE]: AccountTypeParams
+  [ActionType.SEND_ASSET]: SendAssetParams
+  [ActionType.WITHDRAWAL]: WithdrawalParams
+  [ActionType.TRANSFER]: Record<string, never>
+  [ActionType.PLACE_ORDER]: PlaceOrderParams
+  [ActionType.PLACE_TRIGGER_ORDER]: PlaceTriggerOrderParams
+  [ActionType.CANCEL_ORDER]: CancelOrderParams
+  [ActionType.CANCEL_ALL_ORDERS]: CancelAllOrdersParams
+  [ActionType.MODIFY_ORDER]: ModifyOrderParams
+  [ActionType.UPDATE_LEVERAGE]: UpdateLeverageParams
+  [ActionType.UPDATE_POSITION_MARGIN]: UpdatePositionMarginParams
+  [ActionType.REGISTER_API_KEY]: RegisterApiKeyParams
+  [ActionType.APPROVE_READ_ONLY_TOKEN]: ApproveReadOnlyTokenParams
+  [ActionType.DEPOSIT]: DepositParams
+}
+
+// ---------------------------------------------------------------------------
+// Request / Response types
+// ---------------------------------------------------------------------------
+
+/**
+ * Distributed discriminated request shape: selecting an `action` literal
+ * narrows `params` to exactly the matching entry in `ActionParamsMap`.
+ * Mapped over `ActionType` so a new action automatically yields a new branch.
+ */
+export type CreateActionRequest = {
+  [K in ActionType]: {
+    provider: string
+    address: Address
+    signerAddress?: Address
+    action: K
+    params: ActionParamsMap[K]
+  }
+}[ActionType]
+
+export interface CreateActionResponse {
+  actions: ActionStep[]
+}
+
+/**
+ * Distributed discriminated execute-request shape: narrowing on `action`
+ * pins the action kind to a single `ActionType`; `actions` is the
+ * already-discriminated `SignedActionStep[]` union above.
+ */
+export type ExecuteActionRequest = {
+  [K in ActionType]: {
+    provider: string
+    address: Address
+    signerAddress?: Address
+    action: K
+    actions: SignedActionStep[]
+  }
+}[ActionType]
+
+export interface ExecuteActionResponse {
+  results: ActionResult[]
+}

package/src/asset.ts

@@ -0,0 +1,88 @@
+export interface FundingInfo {
+  rate: string
+  nextFundingTime: number
+}
+
+export interface AssetIdentity {
+  assetId: string // provider's canonical identity: "BTC", "xyz:PURR", "@142"
+  market: string // market category from /providers.markets: "hyperliquid", "xyz", "spot"
+}
+
+export interface Asset extends AssetIdentity {
+  displaySymbol: string // UI base name: "BTC", "PURR"; spot keeps full pair: "PURR/USDC"
+  displayQuote: string | null // quote asset for perps: "USDC", "USDH"; null for spot
+  displayName?: string // future: "Bitcoin", "Ethereum"
+  logoURI: string
+  szDecimals: number
+  maxLeverage: number
+  onlyIsolated: boolean
+  isMarginCollateral?: boolean
+  funding: FundingInfo
+  openInterest?: string
+  volume24h?: string
+  prevDayPrice?: string
+  markPrice: string
+}
+
+export type AssetDisplay = Pick<
+  Asset,
+  'assetId' | 'market' | 'displaySymbol' | 'displayQuote'
+>
+
+export interface AssetPrice {
+  assetId: string
+  price: string
+}
+
+export interface AssetsResponse {
+  assets: Asset[]
+}
+
+export interface PricesResponse {
+  prices: AssetPrice[]
+}
+
+export interface Candle {
+  t: number
+  o: string
+  h: string
+  l: string
+  c: string
+  v: string
+}
+
+export interface OhlcvResponse {
+  provider: string
+  assetId: string
+  interval: string
+  candles: Candle[]
+}
+
+export type OhlcvInterval =
+  | '1m'
+  | '3m'
+  | '5m'
+  | '15m'
+  | '30m'
+  | '1h'
+  | '2h'
+  | '4h'
+  | '8h'
+  | '12h'
+  | '1d'
+  | '3d'
+  | '1w'
+  | '1M'
+
+export interface OrderbookLevel {
+  price: string
+  size: string
+}
+
+export interface OrderbookResponse {
+  provider: string
+  assetId: string
+  bids: OrderbookLevel[]
+  asks: OrderbookLevel[]
+  timestamp: number
+}