@lifi/perps-types 0.0.0-preview-a5f5e3b

package/src/action.ts

@@ -0,0 +1,292 @@
+import type { AcceptTermsParams } from './acceptTerms.js'
+import type {
+  ActionType,
+  MarginMode,
+  OrderSide,
+  OrderStatus,
+  OrderType,
+  TimeInForce,
+  TriggerCondition,
+} from './enums.js'
+import type { MarketDisplay, MarketRef } from './market.js'
+import type { Address, Hex } from './primitives.js'
+import type { PerpsTypedData } from './typedData.js'
+import type { VoteParams } from './vote.js'
+
+/** @public */
+export interface Eip712ActionStep {
+  action: ActionType
+  typedData: PerpsTypedData
+}
+
+/** @public */
+export interface WasmBlobActionStep {
+  action: ActionType
+  wasmSignParams: Record<string, unknown>
+}
+
+/** @public */
+export interface EvmTxActionStep {
+  action: ActionType
+  txParams: Record<string, unknown>
+}
+
+/** @public */
+export type ActionStep = Eip712ActionStep | WasmBlobActionStep | EvmTxActionStep
+
+/** @public */
+export interface Eip712SignedActionStep {
+  action: ActionType
+  typedData: PerpsTypedData
+  signature: Hex
+}
+
+/** @public */
+export interface WasmBlobSignedActionStep {
+  action: ActionType
+  wasmSignParams: Record<string, unknown>
+  signedTx: {
+    txType: number
+    txInfo: string
+    txHash: string
+  }
+}
+
+/** @public */
+export interface EvmTxSignedActionStep {
+  action: ActionType
+  txParams: Record<string, unknown>
+  txHash: string
+}
+
+/** @public */
+export type SignedActionStep =
+  | Eip712SignedActionStep
+  | WasmBlobSignedActionStep
+  | EvmTxSignedActionStep
+
+/** @public */
+export type ActionResult =
+  | {
+      action: ActionType
+      success: true
+      orderId?: string
+    }
+  | {
+      action: ActionType
+      success: false
+      error: string
+    }
+
+/** @public */
+export interface TriggerOrderInput {
+  triggerPrice: string
+  limitPrice?: string
+}
+
+/** @public */
+export interface ModifyOrderInput {
+  id: string
+  price?: string
+  size?: string
+  triggerPrice?: string
+  limitPrice?: string
+}
+
+/** @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
+}
+
+/** @public */
+export interface PlaceOrderParams {
+  market: MarketRef
+  side: OrderSide
+  type?: OrderType
+  size: string
+  price?: string
+  leverage?: number
+  /** Omitted falls back to the provider's default (currently CROSS). */
+  marginMode?: MarginMode
+  reduceOnly?: boolean
+  timeInForce?: TimeInForce
+  expiresAt?: string
+  takeProfit?: TriggerOrderInput
+  stopLoss?: TriggerOrderInput
+}
+
+/** @public */
+export interface PlaceTriggerOrderParams {
+  market: MarketRef
+  side: OrderSide
+  takeProfit?: TriggerOrderInput
+  stopLoss?: TriggerOrderInput
+}
+
+/** @public */
+export interface CancelOrderParams {
+  ids: string[]
+}
+
+/** @public */
+export interface ModifyOrderParams {
+  modifications: ModifyOrderInput[]
+}
+
+/** @public */
+export interface UpdateLeverageParams {
+  market: MarketRef
+  leverage: number
+  /** Omitted falls back to the provider's default (currently CROSS). */
+  marginMode?: MarginMode
+}
+
+/** @public */
+export interface UpdatePositionMarginParams {
+  market: MarketRef
+  action: 'add' | 'remove'
+  amount: string
+}
+
+/** @public */
+export interface WithdrawalParams {
+  destination: Address
+  amount: string
+}
+
+/** @public */
+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
+}
+
+/** @public */
+export interface ApproveAgentParams {
+  agentAddress: string
+  agentTtlMs?: number
+}
+
+/** @public */
+export interface AccountModeParams {
+  mode: string
+}
+
+/** @public */
+export interface AccountTypeParams {
+  tier: string
+}
+
+/** @public */
+export interface SendAssetParams {
+  collateral: string
+  sourceDex: string
+  destinationDex: string
+  amount: string
+}
+
+/** @public */
+export interface CancelAllOrdersParams {
+  /** 0=immediate (cancel GTC), 1=scheduled, 2=abort scheduled */
+  timeInForce: number
+  /** Unix timestamp in milliseconds (required for scheduled cancels) */
+  timestampMs?: number
+}
+
+/** @public */
+export interface RegisterApiKeyParams {
+  /** The API key slot index to register (0-255). Reusing a fixed slot overwrites the old key. */
+  apiKeyIndex: number
+  /**
+   * The SDK's currently-stored Lighter public key for this slot, if any. The
+   * backend returns `[]` (already satisfied) only when this equals the
+   * on-chain pubkey at the slot; otherwise it stages a ChangePubKey blob so
+   * the slot can be (re-)registered. Omit when the SDK has no local key.
+   */
+  knownPublicKey?: string
+}
+
+/** @public */
+export interface ApproveReadOnlyTokenParams {
+  accountIndex: number
+  /** Absolute unix-seconds expiry. Lighter requires lifetime between 1 day and 10 years. */
+  expirySeconds: number
+  scope: 'single' | 'all'
+}
+
+/** @public */
+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
+  [ActionType.META_VOTE]: VoteParams
+  [ActionType.META_ACCEPT_TERMS]: AcceptTermsParams
+}
+
+/** @public */
+export type CreateActionRequest = {
+  [K in ActionType]: {
+    provider: string
+    address: Address
+    signerAddress?: Address
+    action: K
+    params: ActionParamsMap[K]
+  }
+}[ActionType]
+
+/** @public */
+export interface CreateActionResponse {
+  actions: ActionStep[]
+}
+
+/** @public */
+export type ExecuteActionRequest = {
+  [K in ActionType]: {
+    provider: string
+    address: Address
+    signerAddress?: Address
+    action: K
+    actions: SignedActionStep[]
+  }
+}[ActionType]
+
+/** @public */
+export interface ExecuteActionResponse {
+  results: ActionResult[]
+}

package/src/asset.ts

@@ -0,0 +1,25 @@
+/**
+ * Underlying token/registry entry. The base entity of the perps taxonomy:
+ * a tradable unit referenced by markets (as base/quote legs) and held by
+ * accounts (as balances). NOT a market — see {@link BaseMarket}.
+ * @public
+ */
+export interface Asset {
+  providerId: string
+  /**
+   * The asset's own provider-native id. Lighter: numeric `asset_id`, stringified.
+   * Hyperliquid spot: the venue token index (`spotMeta.tokens[].index`, the
+   * value HL carries in a balance's `token` field) — identical to that token's
+   * spot `Market.baseAsset.id`, so a held balance resolves to its market by
+   * identity. NEVER the coin symbol (that is `displaySymbol`).
+   */
+  id: string
+  displaySymbol: string
+  logoURI: string
+  displayName?: string
+}
+
+/** @public */
+export interface AssetsResponse {
+  assets: Asset[]
+}

package/src/enums.ts

@@ -0,0 +1,205 @@
+/** @public */
+export enum PerpsErrorCode {
+  // Base errors (2000-2009)
+  DefaultError = 2000,
+  ServerError = 2001,
+  ValidationError = 2002,
+  TimeoutError = 2003,
+  ThirdPartyError = 2004,
+  SDKError = 2005,
+
+  // Auth errors (2010-2019)
+  SignatureInvalid = 2010,
+  AgentUnauthorized = 2011,
+  TermsNotAccepted = 2012,
+
+  // Trading errors (2020-2039)
+  ExchangeRejected = 2020,
+  InsufficientMargin = 2021,
+  InsufficientBalance = 2022,
+  MarketNotFound = 2023,
+  OrderNotFound = 2024,
+  PositionNotFound = 2025,
+  AccountNotFound = 2026,
+
+  // Nonce errors (2040-2049)
+  InvalidNonce = 2040,
+  NonceAlreadyUsed = 2041,
+  NonceExpired = 2042,
+
+  // Payload errors (2050-2059)
+  PayloadMismatch = 2050,
+
+  // Routing errors (2060-2069)
+  RouteNotFound = 2060,
+}
+
+/** @public */
+export enum OrderSide {
+  BUY = 'BUY',
+  SELL = 'SELL',
+}
+
+/** @public */
+export enum OrderType {
+  MARKET = 'MARKET',
+  LIMIT = 'LIMIT',
+  STOP_MARKET = 'STOP_MARKET',
+  STOP_LIMIT = 'STOP_LIMIT',
+  TAKE_PROFIT_MARKET = 'TAKE_PROFIT_MARKET',
+  TAKE_PROFIT_LIMIT = 'TAKE_PROFIT_LIMIT',
+  TRIGGER_ONLY = 'TRIGGER_ONLY',
+}
+
+/** @public */
+export enum PositionSide {
+  LONG = 'LONG',
+  SHORT = 'SHORT',
+}
+
+/** @public */
+export enum MarginMode {
+  ISOLATED = 'ISOLATED',
+  CROSS = 'CROSS',
+}
+
+/** @public */
+export enum TimeInForce {
+  GTC = 'GTC',
+  IOC = 'IOC',
+  POST_ONLY = 'POST_ONLY',
+  GTT = 'GTT',
+}
+
+/** @public */
+export enum OrderStatus {
+  PENDING = 'PENDING',
+  OPEN = 'OPEN',
+  PARTIALLY_FILLED = 'PARTIALLY_FILLED',
+  FILLED = 'FILLED',
+  CANCELLED = 'CANCELLED',
+  REJECTED = 'REJECTED',
+  EXPIRED = 'EXPIRED',
+  TRIGGERED = 'TRIGGERED',
+}
+
+/** @public */
+export enum FillStatus {
+  FILLED = 'FILLED',
+  PARTIALLY_FILLED = 'PARTIALLY_FILLED',
+  CANCELLED = 'CANCELLED',
+  REJECTED = 'REJECTED',
+}
+
+/** @public */
+export enum LiquidityRole {
+  MAKER = 'maker',
+  TAKER = 'taker',
+}
+
+/** @public */
+export enum ActionType {
+  APPROVE_AGENT = 'approveAgent',
+  APPROVE_BUILDER_FEE = 'approveBuilderFee',
+  ACCOUNT_MODE = 'accountMode',
+  ACCOUNT_TYPE = 'accountType',
+  SEND_ASSET = 'sendAsset',
+  WITHDRAWAL = 'withdrawal',
+  TRANSFER = 'transfer',
+  PLACE_ORDER = 'placeOrder',
+  PLACE_TRIGGER_ORDER = 'placeTriggerOrder',
+  CANCEL_ORDER = 'cancelOrder',
+  CANCEL_ALL_ORDERS = 'cancelAllOrders',
+  MODIFY_ORDER = 'modifyOrder',
+  UPDATE_LEVERAGE = 'updateLeverage',
+  UPDATE_POSITION_MARGIN = 'updatePositionMargin',
+  REGISTER_API_KEY = 'registerApiKey',
+  APPROVE_READ_ONLY_TOKEN = 'approveReadOnlyToken',
+  DEPOSIT = 'deposit',
+  /** Provider-independent: sent with the `META_PROVIDER` sentinel, not a real provider key. */
+  META_VOTE = 'metaVote',
+  /** Provider-independent: sent with the `META_PROVIDER` sentinel, not a real provider key. */
+  META_ACCEPT_TERMS = 'metaAcceptTerms',
+}
+
+/** @public */
+export enum TriggerCondition {
+  ABOVE = 'ABOVE',
+  BELOW = 'BELOW',
+}
+
+/** @public */
+export enum TriggerOrderType {
+  TAKE_PROFIT = 'TAKE_PROFIT',
+  STOP_LOSS = 'STOP_LOSS',
+}
+
+/** @public */
+export enum TriggerOrderStatus {
+  WAITING = 'WAITING',
+  TRIGGERED = 'TRIGGERED',
+  CANCELLED = 'CANCELLED',
+}
+
+/** @public */
+export enum ActivityType {
+  DEPOSIT = 'DEPOSIT',
+  WITHDRAWAL = 'WITHDRAWAL',
+  LIQUIDATION = 'LIQUIDATION',
+  FUNDING = 'FUNDING',
+  TRANSFER = 'TRANSFER',
+}
+
+/** @public */
+export enum FillClassification {
+  OPENED_LONG = 'Opened Long',
+  OPENED_SHORT = 'Opened Short',
+  INCREASED_LONG = 'Increased Long',
+  INCREASED_SHORT = 'Increased Short',
+  REDUCED_LONG = 'Reduced Long',
+  REDUCED_SHORT = 'Reduced Short',
+  CLOSED_LONG = 'Closed Long',
+  CLOSED_SHORT = 'Closed Short',
+  SWITCHED_LONG = 'Switched Long',
+  SWITCHED_SHORT = 'Switched Short',
+  SPOT_BUY = 'Spot Buy',
+  SPOT_SELL = 'Spot Sell',
+}
+
+/** @public */
+export enum LiquidationClassification {
+  LIQUIDATED = 'Liquidated',
+}
+
+/** @public */
+export enum FundingClassification {
+  FUNDING = 'Funding',
+}
+
+/** @public */
+export enum TransferClassification {
+  DEPOSIT = 'Deposit',
+  WITHDRAWAL = 'Withdrawal',
+  TRANSFER = 'Transfer',
+}
+
+/** @public */
+export type ActivityClassification =
+  | FillClassification
+  | LiquidationClassification
+  | FundingClassification
+  | TransferClassification
+
+/** @public */
+export enum PerpsSigner {
+  USER = 'USER',
+  AGENT = 'AGENT',
+  API_KEY = 'API_KEY',
+}
+
+/** @public */
+export enum SigningMethod {
+  EIP712 = 'eip712',
+  WASM_BLOB = 'wasmBlob',
+  EVM_TX = 'evmTx',
+}

package/src/errors.ts

@@ -0,0 +1,8 @@
+import type { PerpsErrorCode } from './enums.js'
+
+/** @public */
+export interface PerpsErrorBody {
+  code: PerpsErrorCode
+  tool?: string
+  message: string
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `@lifi/perps-types` — shared cross-provider type surface for the perps SDK:
+ * account/order/market shapes, action params, enums, error codes, provider
+ * descriptors, subscriptions, and EIP-712 typed-data structures.
+ *
+ * @packageDocumentation
+ * @public
+ */
+
+export * from './acceptTerms.js'
+export * from './account.js'
+export * from './action.js'
+export * from './asset.js'
+export * from './enums.js'
+export * from './errors.js'
+export * from './market.js'
+export * from './meta.js'
+export * from './primitives.js'
+export * from './providers.js'
+export * from './quote.js'
+export * from './subscriptions.js'
+export * from './typedData.js'
+export * from './vote.js'

package/src/market.ts

@@ -0,0 +1,132 @@
+import type { Asset } from './asset.js'
+
+/** @public */
+export interface FundingInfo {
+  rate: string
+  nextFundingTime: number
+}
+
+/** @public */
+export interface BaseMarket {
+  providerId: string
+  /** Opaque provider market id; referenced elsewhere as `marketId`. */
+  id: string
+  /** References a {@link ProviderCategory} by id. */
+  categoryId: string
+  baseAsset: Asset
+  quoteAsset: Asset
+  szDecimals: number
+  /**
+   * Maximum decimal places the venue accepts for order prices on this market.
+   * Some venues impose further constraints on top of this budget (e.g. a
+   * significant-figure cap), so always format prices through the provider's
+   * `formatOrderPrice` rather than applying this field directly.
+   */
+  priceDecimals?: number
+  markPrice: string
+  volume24h?: string
+  prevDayPrice?: string
+}
+
+/** @public */
+export interface PerpsMarket extends BaseMarket {
+  maxLeverage: number
+  onlyIsolated: boolean
+  funding: FundingInfo
+  openInterest?: string
+  /**
+   * Venue maintenance margin rate for this market as a fraction (e.g. `0.012`
+   * = 1.2%). Feeds client-side liquidation-price estimates via the provider's
+   * `estimateLiquidationPrice`.
+   */
+  maintenanceMarginRate?: number
+}
+
+/** @public */
+export interface SpotMarket extends BaseMarket {}
+
+/** @public */
+export type Market = PerpsMarket | SpotMarket
+
+/** @public */
+export type MarketDisplay = Pick<
+  BaseMarket,
+  'providerId' | 'id' | 'categoryId' | 'baseAsset' | 'quoteAsset'
+>
+
+/**
+ * Minimal market reference for write-action params: identifies a market by
+ * its opaque `marketId` within a `categoryId`. Embeds no Assets — write
+ * params reference by id, not value.
+ * @public
+ */
+export interface MarketRef {
+  marketId: string
+  categoryId: string
+}
+
+/** @public */
+export interface MarketsResponse {
+  markets: Market[]
+}
+
+/** @public */
+export interface MarketPrice {
+  marketId: string
+  price: string
+}
+
+/** @public */
+export interface PricesResponse {
+  prices: MarketPrice[]
+}
+
+/** @public */
+export interface Candle {
+  t: number
+  o: string
+  h: string
+  l: string
+  c: string
+  v: string
+}
+
+/** @public */
+export interface OhlcvResponse {
+  provider: string
+  marketId: string
+  interval: string
+  candles: Candle[]
+}
+
+/** @public */
+export type OhlcvInterval =
+  | '1m'
+  | '3m'
+  | '5m'
+  | '15m'
+  | '30m'
+  | '1h'
+  | '2h'
+  | '4h'
+  | '8h'
+  | '12h'
+  | '1d'
+  | '3d'
+  | '1w'
+  | '1M'
+
+/** @public */
+export interface OrderbookLevel {
+  price: string
+  size: string
+}
+
+/** @public */
+export interface OrderbookResponse {
+  provider: string
+  marketId: string
+  bids: OrderbookLevel[]
+  asks: OrderbookLevel[]
+  timestamp: number
+}