@lifi/perps-types 0.1.1-alpha.9 → 1.0.0

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

@@ -1,3 +1,4 @@
+/** @public */
 export enum PerpsErrorCode {
   // Base errors (2000-2009)
   DefaultError = 2000,
@@ -5,10 +6,12 @@ export enum PerpsErrorCode {
   ValidationError = 2002,
   TimeoutError = 2003,
   ThirdPartyError = 2004,
+  SDKError = 2005,
 
   // Auth errors (2010-2019)
   SignatureInvalid = 2010,
   AgentUnauthorized = 2011,
+  TermsNotAccepted = 2012,
 
   // Trading errors (2020-2039)
   ExchangeRejected = 2020,
@@ -17,6 +20,7 @@ export enum PerpsErrorCode {
   MarketNotFound = 2023,
   OrderNotFound = 2024,
   PositionNotFound = 2025,
+  AccountNotFound = 2026,
 
   // Nonce errors (2040-2049)
   InvalidNonce = 2040,
@@ -30,26 +34,36 @@ export enum PerpsErrorCode {
   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',
@@ -57,6 +71,7 @@ export enum TimeInForce {
   GTT = 'GTT',
 }
 
+/** @public */
 export enum OrderStatus {
   PENDING = 'PENDING',
   OPEN = 'OPEN',
@@ -68,39 +83,123 @@ export enum OrderStatus {
   TRIGGERED = 'TRIGGERED',
 }
 
-export enum HistoryItemStatus {
+/** @public */
+export enum FillStatus {
   FILLED = 'FILLED',
   PARTIALLY_FILLED = 'PARTIALLY_FILLED',
   CANCELLED = 'CANCELLED',
   REJECTED = 'REJECTED',
 }
 
-export enum OrderActionType {
-  UPDATE_LEVERAGE = 'updateLeverage',
+/** @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

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

package/src/index.ts

@@ -1,9 +1,23 @@
-export * from './typedData.js'
-export * from './enums.js'
-export * from './market.js'
-export * from './authorization.js'
+/**
+ * `@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 './trading.js'
-export * from './withdrawal.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

@@ -1,56 +1,92 @@
-export interface AuthorizationParam {
-  name: string
-  type: 'string' | 'number' | 'boolean'
-  required: boolean
-}
-
-export interface Authorization {
-  key: string
-  name: string
-  params?: AuthorizationParam[]
-}
-
-export interface Dex {
-  key: string
-  name: string
-  logoURI: string
-  authorizations: Authorization[]
-  extraData?: Record<string, unknown>
-  wsUrl?: string
-}
-
-export interface DexesResponse {
-  dexes: Dex[]
-}
+import type { Asset } from './asset.js'
 
+/** @public */
 export interface FundingInfo {
   rate: string
   nextFundingTime: number
 }
 
-export interface Market {
-  symbol: string
-  name: string
-  logoURI: string
-  assetId: number
-  dex: string
+/** @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
+}
+
+/** @public */
+export interface PerpsMarket extends BaseMarket {
   maxLeverage: number
   onlyIsolated: boolean
-  funding: FundingInfo
-  openInterest?: string
-  volume24h?: string
-  markPrice: 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[]
 }
 
+/**
+ * Live per-market data for the `/prices` endpoint. `price` is the mid;
+ * `markPrice`, `prevDayPrice` and `volume24h` apply to every market type,
+ * while `openInterest` and `funding` are perp-only and absent for spot.
+ * @public
+ */
+export interface MarketPrice {
+  marketId: string
+  price: string
+  markPrice: string
+  prevDayPrice?: string
+  volume24h?: string
+  openInterest?: string
+  funding?: FundingInfo
+}
+
+/** @public */
 export interface PricesResponse {
-  prices: Record<string, string>
+  prices: MarketPrice[]
 }
 
+/** @public */
 export interface Candle {
   t: number
   o: string
@@ -60,13 +96,15 @@ export interface Candle {
   v: string
 }
 
+/** @public */
 export interface OhlcvResponse {
-  dex: string
-  symbol: string
+  provider: string
+  marketId: string
   interval: string
   candles: Candle[]
 }
 
+/** @public */
 export type OhlcvInterval =
   | '1m'
   | '3m'
@@ -83,14 +121,16 @@ export type OhlcvInterval =
   | '1w'
   | '1M'
 
+/** @public */
 export interface OrderbookLevel {
   price: string
   size: string
 }
 
+/** @public */
 export interface OrderbookResponse {
-  dex: string
-  symbol: string
+  provider: string
+  marketId: string
   bids: OrderbookLevel[]
   asks: OrderbookLevel[]
   timestamp: number