@lifi/perps-sdk-provider-lighter 0.2.0-alpha.0

package/src/types/account.ts

@@ -0,0 +1,123 @@
+// Account / balance shapes returned by Lighter's `/api/v1/account` and
+// `/api/v1/accountLimits` endpoints.
+
+/** @public */
+export type LtAccountPosition = {
+  market_id: number
+  /** Present on REST `/api/v1/account` rows; WS position frames may omit it. */
+  symbol?: string
+  initial_margin_fraction: string
+  open_order_count: number
+  pending_order_count: number
+  position_tied_order_count: number
+  sign: number
+  position: string
+  avg_entry_price: string
+  position_value: string
+  unrealized_pnl: string
+  realized_pnl: string
+  liquidation_price: string
+  total_funding_paid_out: string
+  margin_mode: number
+  allocated_margin: string
+  total_discount: string
+}
+
+/** @public */
+export type LtAccountAsset = {
+  symbol: string
+  asset_id: number
+  balance: string
+  locked_balance: string
+}
+
+/**
+ * Account-position row from `/api/v1/account`. Identical shape to
+ * `LtAccountPosition` — alias kept for read-side clarity at call sites that
+ * fan out off per-market order counts (`open_order_count`,
+ * `pending_order_count`, `position_tied_order_count`).
+ * @public
+ */
+export type LtDetailedAccountPosition = LtAccountPosition
+
+/** @public */
+export interface LtApprovedIntegrator {
+  account_index: number
+  name: string
+  max_perps_taker_fee: number
+  max_perps_maker_fee: number
+  max_spot_taker_fee: number
+  max_spot_maker_fee: number
+  approval_expiry: number
+}
+
+/** @public */
+export interface LtDetailedAccount {
+  code: number
+  account_type: number
+  index: number
+  l1_address: string
+  cancel_all_time: number
+  total_order_count: number
+  total_isolated_order_count: number
+  pending_order_count: number
+  available_balance: string
+  status: number
+  collateral: string
+  transaction_time: number
+  account_trading_mode: number
+  account_index: number
+  name: string
+  description: string
+  positions: LtDetailedAccountPosition[]
+  assets: LtAccountAsset[]
+  total_asset_value: string
+  cross_asset_value: string
+  approved_integrators?: LtApprovedIntegrator[]
+}
+
+/** @public */
+export interface LtDetailedAccountsResponse {
+  code: number
+  total: number
+  accounts: LtDetailedAccount[]
+}
+
+/** @public */
+export interface LtAccountLimits {
+  code: number
+  message?: string
+  max_llp_percentage: number
+  max_llp_amount: string
+  user_tier: string
+  user_tier_name?: string
+  can_create_public_pool: boolean
+  current_maker_fee_tick: number
+  current_taker_fee_tick: number
+  leased_lit: string
+  effective_lit_stakes: string
+}
+
+/** @public */
+export interface LtSubAccount {
+  code: number
+  account_type: number
+  index: number
+  l1_address: string
+  cancel_all_time: number
+  total_order_count: number
+  total_isolated_order_count: number
+  pending_order_count: number
+  available_balance: string
+  status: number
+  collateral: string
+  transaction_time: number
+  account_trading_mode: number
+}
+
+/** @public */
+export interface LtAccountsByL1AddressResponse {
+  code: number
+  l1_address: string
+  sub_accounts: LtSubAccount[]
+}

package/src/types/action.ts

@@ -0,0 +1,163 @@
+// Shapes of `wasmSignParams` per action. The backend populates these and the
+// SDK passes them to the WASM signer alongside SDK-managed fields (nonce,
+// account_index, api_key_index).
+
+/**
+ * Backend-provided params for SignCreateOrder.
+ *
+ * @public
+ */
+export type LtCreateOrderWasmParams = {
+  market_index: number
+  client_order_index: number
+  base_amount: number
+  price: number
+  is_ask: number
+  order_type: number
+  time_in_force: number
+  reduce_only: boolean
+  trigger_price: number
+  order_expiry: number
+  integrator_account_index: number
+  integrator_taker_fee: number
+  integrator_maker_fee: number
+}
+
+/**
+ * Backend-provided params for SignCancelOrder.
+ *
+ * @public
+ */
+export type LtCancelOrderWasmParams = {
+  market_index: number
+  order_index: number
+}
+
+/**
+ * Backend-provided params for SignModifyOrder.
+ *
+ * @public
+ */
+export type LtModifyOrderWasmParams = {
+  market_index: number
+  order_index: number
+  base_amount: number
+  price: number
+  trigger_price: number
+  integrator_account_index: number
+  integrator_taker_fee: number
+  integrator_maker_fee: number
+}
+
+/**
+ * Backend-provided params for SignUpdateLeverage.
+ *
+ * @public
+ */
+export type LtUpdateLeverageWasmParams = {
+  market_index: number
+  fraction: number
+  margin_mode: number
+}
+
+/**
+ * Backend-provided params for SignUpdateMargin.
+ *
+ * @public
+ */
+export type LtUpdateMarginWasmParams = {
+  market_index: number
+  usdc_amount: number
+  direction: number
+}
+
+/**
+ * Backend-provided params for SignWithdraw.
+ *
+ * @public
+ */
+export type LtWithdrawWasmParams = {
+  asset_index: number
+  route_type: number
+  amount: number
+}
+
+/**
+ * Backend-provided params for SignCancelAllOrders.
+ *
+ * @public
+ */
+export type LtCancelAllOrdersWasmParams = {
+  /** 0=immediate (cancel GTC), 1=scheduled, 2=abort scheduled */
+  time_in_force: number
+  /** Unix timestamp in milliseconds. Use Date.now() for immediate cancels. */
+  timestamp_ms: number
+}
+
+/**
+ * Backend-provided params for SignChangePubKey (REGISTER_API_KEY).
+ *
+ * Hybrid signing: this action requires both a WASM blob and an L1 Ethereum
+ * signature (the user's wallet signs the ChangePubKey message). The SDK
+ * generates the keypair via the WASM signer and fills in `new_public_key`
+ * before invoking SignChangePubKey.
+ * @public
+ */
+export type LtChangePubKeyWasmParams = {
+  /** API key slot index to register (0-255). SDK fills in the generated public key. */
+  api_key_index: number
+  nonce: number
+}
+
+/** @public */
+export const LT_ORDER_TYPE_LIMIT = 0
+/** @public */
+export const LT_ORDER_TYPE_MARKET = 1
+/** @public */
+export const LT_ORDER_TYPE_STOP_LOSS = 2
+/** @public */
+export const LT_ORDER_TYPE_STOP_LOSS_LIMIT = 3
+/** @public */
+export const LT_ORDER_TYPE_TAKE_PROFIT = 4
+/** @public */
+export const LT_ORDER_TYPE_TAKE_PROFIT_LIMIT = 5
+/** @public */
+export const LT_ORDER_TYPE_TWAP = 6
+
+/** @public */
+export const LT_TIME_IN_FORCE_IOC = 0
+/** @public */
+export const LT_TIME_IN_FORCE_GTC = 1
+/** @public */
+export const LT_TIME_IN_FORCE_POST_ONLY = 2
+
+/** @public */
+export const LT_MARGIN_MODE_CROSS = 0
+/** @public */
+export const LT_MARGIN_MODE_ISOLATED = 1
+
+/** @public */
+export const LT_MARGIN_DIRECTION_REMOVE = 0
+/** @public */
+export const LT_MARGIN_DIRECTION_ADD = 1
+
+/** @public */
+export const LT_ROUTE_PERP = 0
+/** @public */
+export const LT_ROUTE_SPOT = 1
+
+/** @public */
+export const LT_ASSET_ID_USDC = 3
+
+/** @public */
+export const LT_NIL_TRIGGER_PRICE = 0
+/**
+ * Sentinel the lighter-go WASM signer translates to "default 28-day expiry
+ * from now" at sign time (`wasm/main.go:325`, `wasm/main.go:898`). On the
+ * wire, `OrderExpiry` is an *absolute* Unix-ms timestamp, not a duration;
+ * `-1` lets the signer fill in the default, any positive int64 sets an
+ * explicit absolute expiry. Matches lighter-python's
+ * `DEFAULT_28_DAY_ORDER_EXPIRY`.
+ * @public
+ */
+export const LT_DEFAULT_ORDER_EXPIRY = -1

package/src/types/activity.ts

@@ -0,0 +1,94 @@
+// Activity history shapes returned by Lighter's REST API
+// (deposits, withdrawals, funding payments, liquidations, transfers).
+
+/** @public */
+export interface LtDepositHistoryItem {
+  id: string
+  asset_id: number
+  amount: string
+  timestamp: number
+  status: string
+  l1_tx_hash: string
+}
+
+/** @public */
+export interface LtDepositHistoryResponse {
+  code: number
+  deposits: LtDepositHistoryItem[]
+  cursor?: string
+}
+
+/** @public */
+export interface LtWithdrawHistoryItem {
+  id: string
+  asset_id: number
+  amount: string
+  timestamp: number
+  status: string
+  type: string
+  l1_tx_hash: string
+}
+
+/** @public */
+export interface LtWithdrawHistoryResponse {
+  code: number
+  withdraws: LtWithdrawHistoryItem[]
+  cursor?: string
+}
+
+/** @public */
+export interface LtPositionFunding {
+  timestamp: number
+  market_id: number
+  funding_id: number
+  change: string
+  rate: string
+  position_size: string
+  position_side: string
+}
+
+/** @public */
+export interface LtPositionFundingsResponse {
+  code: number
+  position_fundings: LtPositionFunding[]
+  next_cursor?: string
+}
+
+/** @public */
+export interface LtLiquidation {
+  id: number
+  market_id: number
+  type: string
+  executed_at: number
+}
+
+/** @public */
+export interface LtLiquidationsResponse {
+  code: number
+  liquidations: LtLiquidation[]
+  next_cursor?: string
+}
+
+/** @public */
+export interface LtTransfer {
+  id: string
+  asset_id: number
+  amount: string
+  fee: string
+  timestamp: number
+  type: string
+  from_l1_address: string
+  to_l1_address: string
+  from_account_index: number
+  to_account_index: number
+  from_route: 'spot' | 'perps'
+  to_route: 'spot' | 'perps'
+  tx_hash: string
+}
+
+/** @public */
+export interface LtTransferHistoryResponse {
+  code: number
+  transfers: LtTransfer[]
+  cursor?: string
+}

package/src/types/asset.ts

@@ -0,0 +1,146 @@
+// Market / asset / orderbook metadata returned by Lighter's REST API.
+
+/** @public */
+export interface LtMarketConfig {
+  market_margin_mode: number
+  insurance_fund_account_index: number
+  liquidation_mode: number
+  force_reduce_only: boolean
+  trading_hours: string
+  funding_fee_discounts_enabled: boolean
+  hidden: boolean
+}
+
+/** @public */
+export interface LtPerpsOrderBookDetail {
+  symbol: string
+  market_id: number
+  market_type: string
+  base_asset_id: number
+  quote_asset_id: number
+  status: string
+  taker_fee: string
+  maker_fee: string
+  liquidation_fee: string
+  min_base_amount: string
+  min_quote_amount: string
+  order_quote_limit: string
+  supported_size_decimals: number
+  supported_price_decimals: number
+  supported_quote_decimals: number
+  size_decimals: number
+  price_decimals: number
+  quote_multiplier: number
+  default_initial_margin_fraction: number
+  min_initial_margin_fraction: number
+  maintenance_margin_fraction: number
+  closeout_margin_fraction: number
+  last_trade_price: number
+  daily_trades_count: number
+  daily_base_token_volume: number
+  daily_quote_token_volume: number
+  daily_price_low: number
+  daily_price_high: number
+  daily_price_change: number
+  daily_chart: Record<string, unknown>
+  open_interest: number
+  market_config: LtMarketConfig
+  strategy_index: number
+}
+
+/** @public */
+export interface LtSpotOrderBookDetail {
+  symbol: string
+  market_id: number
+  market_type: string
+  base_asset_id: number
+  quote_asset_id: number
+  status: string
+  taker_fee: string
+  maker_fee: string
+  liquidation_fee: string
+  min_base_amount: string
+  min_quote_amount: string
+  order_quote_limit: string
+  supported_size_decimals: number
+  supported_price_decimals: number
+  supported_quote_decimals: number
+  size_decimals: number
+  price_decimals: number
+  last_trade_price: number
+  daily_trades_count: number
+  daily_base_token_volume: number
+  daily_quote_token_volume: number
+  daily_price_low: number
+  daily_price_high: number
+  daily_price_change: number
+  daily_chart: Record<string, unknown>
+}
+
+/** @public */
+export interface LtOrderBookDetailsResponse {
+  code: number
+  order_book_details: LtPerpsOrderBookDetail[]
+  spot_order_book_details: LtSpotOrderBookDetail[]
+}
+
+/** @public */
+export interface LtToken {
+  symbol: string
+  name: string
+  logo: string
+  logo_extension: string
+  market: 'PERPS' | 'SPOT'
+}
+
+/** @public */
+export interface LtTokenListResponse {
+  code: number
+  tokens: LtToken[]
+}
+
+/** @public */
+export interface LtAssetDetail {
+  asset_id: number
+  symbol: string
+  l1_decimals: number
+  decimals: number
+  l1_address: string
+}
+
+/** @public */
+export interface LtAssetDetailsResponse {
+  code: number
+  asset_details: LtAssetDetail[]
+}
+
+/** @public */
+export interface LtCandle {
+  t: number
+  o: number
+  h: number
+  l: number
+  c: number
+  v: number
+}
+
+/** @public */
+export interface LtCandlesResponse {
+  code: number
+  r: string
+  c: LtCandle[]
+}
+
+/** @public */
+export interface LtFundingRate {
+  market_id: number
+  exchange: string
+  symbol: string
+  rate: number
+}
+
+/** @public */
+export interface LtFundingRatesResponse {
+  code: number
+  funding_rates: LtFundingRate[]
+}

package/src/types/fill.ts

@@ -0,0 +1,42 @@
+// Trade (fill) shapes returned by Lighter's `/api/v1/trades` endpoint.
+
+/** @public */
+export type LtTrade = {
+  trade_id: number
+  tx_hash: string
+  type: string
+  market_id: number
+  size: string
+  price: string
+  usd_amount: string
+  ask_id: number
+  bid_id: number
+  ask_account_id: number
+  bid_account_id: number
+  is_maker_ask: boolean
+  block_height: number
+  timestamp: number
+  // Lighter's OpenAPI spec marks these as required `StrictInt`, but the live
+  // /api/v1/trades endpoint omits them on some `type: "trade"` rows (observed
+  // on older trades) — keep optional and let the mapper emit `undefined`.
+  taker_fee?: number
+  maker_fee?: number
+  transaction_time: number
+  // Per-counterparty position snapshot BEFORE the trade is applied. Signed
+  // strings: positive = long, negative = short, "0" / "0.00000" = flat.
+  taker_position_size_before: string
+  maker_position_size_before: string
+  // Per-counterparty entry-quote (notional cost basis) snapshot BEFORE the
+  // trade. Paired with `*_position_size_before`, avg entry =
+  // entry_quote_before / |position_size_before|. Optional: absent on older
+  // trade rows that predate the field.
+  taker_entry_quote_before?: string
+  maker_entry_quote_before?: string
+}
+
+/** @public */
+export interface LtTradesResponse {
+  code: number
+  next_cursor: string
+  trades: LtTrade[]
+}

package/src/types/index.ts

@@ -0,0 +1,12 @@
+// biome-ignore-all lint/performance/noBarrelFile lint/performance/noReExportAll: single re-export entry point
+// for every Lighter wire type. Internal modules import per-file paths (e.g.
+// `../types/account.js`) to avoid pulling unrelated types into bundles.
+
+export * from './account.js'
+export * from './action.js'
+export * from './activity.js'
+export * from './asset.js'
+export * from './fill.js'
+export * from './order.js'
+export * from './submit.js'
+export * from './ws.js'

package/src/types/order.ts

@@ -0,0 +1,65 @@
+// Order shapes returned by Lighter's REST API.
+
+/** @public */
+export type LtOrder = {
+  order_index: number
+  client_order_index: number
+  order_id: string
+  client_order_id: string
+  market_index: number
+  owner_account_index: number
+  initial_base_amount: string
+  price: string
+  nonce: number
+  remaining_base_amount: string
+  is_ask: boolean
+  filled_base_amount: string
+  filled_quote_amount: string
+  side: string
+  type: string
+  time_in_force: string
+  reduce_only: boolean
+  trigger_price: string
+  order_expiry: number
+  status: string
+  trigger_status: string
+  trigger_time: number
+  parent_order_index: number
+  parent_order_id: string
+  to_trigger_order_id_0: string
+  to_trigger_order_id_1: string
+  to_cancel_order_id_0: string
+  block_height: number
+  timestamp: number
+  created_at: number
+  updated_at: number
+  transaction_time: number
+}
+
+/** @public */
+export interface LtOrdersResponse {
+  code: number
+  next_cursor: string
+  orders: LtOrder[]
+}
+
+/** @public */
+export interface LtOrderBookOrder {
+  order_index: number
+  order_id: string
+  owner_account_index: number
+  initial_base_amount: string
+  remaining_base_amount: string
+  price: string
+  order_expiry: number
+  transaction_time: number
+}
+
+/** @public */
+export interface LtOrderBookOrdersResponse {
+  code: number
+  total_asks: number
+  asks: LtOrderBookOrder[]
+  total_bids: number
+  bids: LtOrderBookOrder[]
+}