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

package/src/providers/hyperliquid/mappers/order.ts

@@ -4,32 +4,76 @@ import {
   OrderType,
   TimeInForce,
 } from '../../../enums.js'
-import type { OpenOrder } from '../../../account.js'
-import type { Order } from '../../../trading.js'
+import type { OpenOrder, TriggerOrder } from '../../../account.js'
+import type { Order } from '../../../action.js'
 import type { HlFrontendOpenOrder, HlOrderDetail } from '../types.js'
+import { deriveMarket } from './_market.js'
 
-import { resolveAssetIdFromLookup } from './shared.js'
+/** Map a Hyperliquid orderType string to the OrderType enum. */
+export const mapOrderType = (orderType: string): OrderType => {
+  switch (orderType) {
+    case 'Take Profit Market':
+      return OrderType.TAKE_PROFIT_MARKET
+    case 'Take Profit Limit':
+      return OrderType.TAKE_PROFIT_LIMIT
+    case 'Stop Market':
+      return OrderType.STOP_MARKET
+    case 'Stop Limit':
+      return OrderType.STOP_LIMIT
+    case 'Market':
+      return OrderType.MARKET
+    default:
+      return OrderType.LIMIT
+  }
+}
+
+export const isTriggerType = (type: OrderType): boolean =>
+  type === OrderType.TAKE_PROFIT_MARKET ||
+  type === OrderType.TAKE_PROFIT_LIMIT ||
+  type === OrderType.STOP_MARKET ||
+  type === OrderType.STOP_LIMIT
 
-export const mapOpenOrder = (
-  o: HlFrontendOpenOrder,
-  dexKey: string,
-  assetIdLookup: Map<string, number>
-): OpenOrder => ({
+export const mapOpenOrder = (o: HlFrontendOpenOrder): OpenOrder => ({
   id: String(o.oid),
-  symbol: o.coin,
-  assetId: resolveAssetIdFromLookup(assetIdLookup, o.coin),
-  dex: dexKey,
+  asset: {
+    assetId: o.coin,
+    market: deriveMarket(o.coin),
+    displaySymbol: o.coin,
+    displayQuote: null,
+  },
   side: o.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
-  type: o.orderType === 'Limit' ? OrderType.LIMIT : OrderType.MARKET,
+  type: mapOrderType(o.orderType),
   size: o.sz,
   price: o.limitPx,
   filledSize: o.origSz
     ? (parseFloat(o.origSz) - parseFloat(o.sz)).toString()
     : '0',
   reduceOnly: o.reduceOnly ?? false,
+  label: o.isTrigger ? o.triggerCondition : undefined,
   createdAt: new Date(o.timestamp).toISOString(),
 })
 
+export const mapTriggerOrder = (o: HlFrontendOpenOrder): TriggerOrder => {
+  const type = mapOrderType(o.orderType)
+  const isLimit =
+    type === OrderType.TAKE_PROFIT_LIMIT || type === OrderType.STOP_LIMIT
+  return {
+    id: String(o.oid),
+    asset: {
+      assetId: o.coin,
+      market: deriveMarket(o.coin),
+      displaySymbol: o.coin,
+      displayQuote: null,
+    },
+    type,
+    size: o.sz,
+    triggerPrice: o.triggerPx,
+    ...(isLimit ? { limitPrice: o.limitPx } : {}),
+    label: o.triggerCondition,
+    createdAt: new Date(o.timestamp).toISOString(),
+  }
+}
+
 const mapOrderStatus = (status: string): OrderStatus => {
   switch (status) {
     case 'open':
@@ -51,6 +95,37 @@ const mapOrderStatus = (status: string): OrderStatus => {
   }
 }
 
+/**
+ * Map a raw Hyperliquid order status to a short English sentence
+ * describing *why* the order ended in a terminal non-FILLED state. Bare
+ * `canceled`/`cancelled`/`rejected` carry no actionable detail and
+ * return `undefined`; so do non-terminal and unknown values.
+ */
+export const mapStatusReason = (status: string): string | undefined => {
+  switch (status) {
+    case 'iocCanceled':
+      return 'Order cancelled: not enough liquidity to fill immediately.'
+    case 'reduceOnlyCanceled':
+      return 'Order cancelled: would not reduce your position.'
+    case 'marginCanceled':
+      return 'Order cancelled: insufficient margin.'
+    case 'liquidatedCanceled':
+      return 'Order cancelled: account was liquidated.'
+    case 'siblingFilledCanceled':
+      return 'Order cancelled: sibling OCO order filled first.'
+    case 'selfTradeCanceled':
+      return 'Order cancelled: would self-trade against your own resting order.'
+    case 'tickRejected':
+      return 'Order rejected: price did not match the tick size.'
+    case 'minTradeNtlRejected':
+      return 'Order rejected: notional value below the minimum trade size.'
+    case 'delistedRejected':
+      return 'Order rejected: market has been delisted.'
+    default:
+      return undefined
+  }
+}
+
 const mapTimeInForce = (tif: string | undefined): TimeInForce | undefined => {
   switch (tif) {
     case 'Gtc':
@@ -70,9 +145,14 @@ export const mapOrder = (detail: HlOrderDetail): Order => {
 
   return {
     orderId: String(o.oid),
-    symbol: o.coin,
+    asset: {
+      assetId: o.coin,
+      market: deriveMarket(o.coin),
+      displaySymbol: o.coin,
+      displayQuote: null,
+    },
     side: o.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
-    type: o.orderType === 'Limit' ? OrderType.LIMIT : OrderType.MARKET,
+    type: mapOrderType(o.orderType),
     price: o.limitPx,
     originalSize: o.origSz,
     remainingSize: o.sz,
@@ -82,6 +162,7 @@ export const mapOrder = (detail: HlOrderDetail): Order => {
     isTrigger: o.triggerCondition !== undefined && o.triggerCondition !== 'N/A',
     triggerPrice: o.triggerPx ?? undefined,
     status: mapOrderStatus(detail.status),
+    statusReason: mapStatusReason(detail.status),
     createdAt: new Date(o.timestamp).toISOString(),
     updatedAt: new Date(detail.statusTimestamp).toISOString(),
   }

package/src/providers/hyperliquid/mappers/position.ts

@@ -1,21 +1,19 @@
 import { MarginMode, PositionSide } from '../../../enums.js'
 import type { Position } from '../../../account.js'
 import type { HlAssetPosition } from '../types.js'
+import { deriveMarket } from './_market.js'
 
-import { resolveAssetIdFromLookup } from './shared.js'
-
-export const mapPosition = (
-  ap: HlAssetPosition,
-  dexKey: string,
-  assetIdLookup: Map<string, number>
-): Position => {
+export const mapPosition = (ap: HlAssetPosition): Position => {
   const pos = ap.position
   const szi = parseFloat(pos.szi)
 
   return {
-    symbol: pos.coin,
-    assetId: resolveAssetIdFromLookup(assetIdLookup, pos.coin),
-    dex: dexKey,
+    asset: {
+      assetId: pos.coin,
+      market: deriveMarket(pos.coin),
+      displaySymbol: pos.coin,
+      displayQuote: null,
+    },
     side: szi >= 0 ? PositionSide.LONG : PositionSide.SHORT,
     size: Math.abs(szi).toString(),
     entryPrice: pos.entryPx ?? '0',

package/src/providers/hyperliquid/mappers/shared.ts

@@ -1,15 +0,0 @@
-/**
- * Look up an asset ID by symbol, throwing if the symbol is unknown.
- * Asset ID 0 is a valid Hyperliquid asset (BTC-PERP), so a fallback
- * to 0 would silently corrupt data.
- */
-export const resolveAssetIdFromLookup = (
-  lookup: Map<string, number>,
-  symbol: string
-): number => {
-  const id = lookup.get(symbol)
-  if (id === undefined) {
-    throw new Error(`Unknown asset symbol: ${symbol}`)
-  }
-  return id
-}

package/src/providers/hyperliquid/types.ts

@@ -1,3 +1,5 @@
+import type { Address } from 'viem'
+
 // ---------------------------------------------------------------------------
 // Hyperliquid /info response types
 // ---------------------------------------------------------------------------
@@ -20,6 +22,7 @@ export type HlAssetCtx = {
   funding: string
   openInterest: string
   dayNtlVlm: string
+  prevDayPx: string
   markPx: string
 }
 
@@ -123,6 +126,13 @@ export type HlFrontendOpenOrder = {
   origSz: string
   reduceOnly: boolean
   timestamp: number
+  isTrigger: boolean
+  isPositionTpsl: boolean
+  triggerCondition: string
+  triggerPx: string
+  children: HlFrontendOpenOrder[]
+  tif: string | null
+  cloid: string | null
 }
 
 export type HlFrontendOpenOrders = HlFrontendOpenOrder[]
@@ -135,6 +145,7 @@ export type HlExtraAgents = Record<string, unknown>[]
 
 export type HlUserFill = {
   tid: number
+  oid: number
   coin: string
   side: string
   sz: string
@@ -142,7 +153,9 @@ export type HlUserFill = {
   dir: string
   fee: string
   closedPnl: string
+  crossed: boolean
   time: number
+  startPosition: string
 }
 
 export type HlUserFills = HlUserFill[]
@@ -180,6 +193,124 @@ export type HlOrderStatusResponse =
   | HlOrderStatusFound
   | { status: 'unknownOid' }
 
+// -- userNonFundingLedgerUpdates --------------------------------------------
+
+/**
+ * Hyperliquid `spotTransfer` ledger delta. Emitted for transfers of spot
+ * tokens between Hyperliquid accounts. `user` is the sender, `destination`
+ * the recipient; direction is derived at the call site from the queried
+ * address.
+ */
+export type HlSpotTransferDelta = {
+  type: 'spotTransfer'
+  token: string
+  amount: string
+  usdcValue: string
+  user: Address
+  destination: Address
+  fee?: string
+  nativeTokenFee?: string
+  nonce?: number
+}
+
+/**
+ * Hyperliquid ledger delta emitted for the `sendAsset` exchange action. The
+ * wire `type` literal is `'send'` (NOT `'sendAsset'`); the TS name retains
+ * the `SendAsset` prefix to match `HL_PRIMARY_TYPE_SEND_ASSET`.
+ *
+ * - `user` is the sender, `destination` the recipient. For same-user dex
+ *   moves both equal the queried address.
+ * - `sourceDex` / `destinationDex` use `""` for the main USDC perp DEX,
+ *   `"spot"` for spot, or the perp DEX name otherwise.
+ * - `token` is a wire token identifier (e.g. `"USDC"` or `"TOKEN:0x..."`).
+ * - `nonce` is the wire nonce (ms timestamp); always present on `send`
+ *   deltas, unlike `spotTransfer` where it may be null.
+ */
+export type HlSendAssetDelta = {
+  type: 'send'
+  user: Address
+  destination: Address
+  sourceDex: string
+  destinationDex: string
+  token: string
+  amount: string
+  usdcValue: string
+  fee: string
+  nativeTokenFee: string
+  nonce: number
+  feeToken: string
+}
+
+export type HlLedgerDelta =
+  | HlSpotTransferDelta
+  | HlSendAssetDelta
+  | {
+      type: string
+      usdc?: string
+      [key: string]: unknown
+    }
+
+/**
+ * Type guard for `HlSpotTransferDelta` — TypeScript cannot narrow off the
+ * `type` discriminant alone because the catch-all arm of `HlLedgerDelta` has
+ * `type: string` (a supertype of the literal `'spotTransfer'`). Use this at
+ * call sites that need the strongly-typed shape.
+ */
+export const isSpotTransferDelta = (
+  delta: HlLedgerDelta
+): delta is HlSpotTransferDelta => delta.type === 'spotTransfer'
+
+/**
+ * Type guard for `HlSendAssetDelta`. The wire `type` literal is `'send'`;
+ * see `HlSendAssetDelta` for the naming-vs-wire-format rationale. Same
+ * catch-all-arm caveat as `isSpotTransferDelta`.
+ */
+export const isSendAssetDelta = (
+  delta: HlLedgerDelta
+): delta is HlSendAssetDelta => delta.type === 'send'
+
+export type HlLedgerUpdate = {
+  time: number
+  hash: string
+  delta: HlLedgerDelta
+}
+
+export type HlUserNonFundingLedgerUpdates = HlLedgerUpdate[]
+
+// -- userFunding ------------------------------------------------------------
+
+export type HlFundingDelta = {
+  type: 'funding'
+  coin: string
+  usdc: string
+  szi: string
+  fundingRate: string
+}
+
+export type HlFundingUpdate = {
+  time: number
+  hash: string
+  delta: HlFundingDelta
+}
+
+export type HlUserFunding = HlFundingUpdate[]
+
+// -- abstraction mode -------------------------------------------------------
+
+/**
+ * Possible values returned by the `userAbstraction` info endpoint.
+ * `null` means abstraction has never been set (standard mode).
+ */
+export const HlAbstractionMode = {
+  DISABLED: 'disabled',
+  UNIFIED_ACCOUNT: 'unifiedAccount',
+  PORTFOLIO_MARGIN: 'portfolioMargin',
+  DEX_ABSTRACTION: 'dexAbstraction',
+} as const
+
+export type HlAbstractionMode =
+  (typeof HlAbstractionMode)[keyof typeof HlAbstractionMode]
+
 // -- perpDexs ---------------------------------------------------------------
 
 export type HlPerpDexs = (null | { name: string })[]
@@ -219,3 +350,30 @@ export type HlExchangeResponse = {
         }
       }
 }
+
+// ---------------------------------------------------------------------------
+// Hyperliquid EIP-712 primary type constants
+// ---------------------------------------------------------------------------
+
+export const HL_PRIMARY_TYPE_APPROVE_AGENT =
+  'HyperliquidTransaction:ApproveAgent' as const
+export const HL_PRIMARY_TYPE_APPROVE_BUILDER_FEE =
+  'HyperliquidTransaction:ApproveBuilderFee' as const
+export const HL_PRIMARY_TYPE_USER_SET_ABSTRACTION =
+  'HyperliquidTransaction:UserSetAbstraction' as const
+export const HL_PRIMARY_TYPE_AGENT_SET_ABSTRACTION =
+  'HyperliquidTransaction:AgentSetAbstraction' as const
+export const HL_PRIMARY_TYPE_WITHDRAW =
+  'HyperliquidTransaction:Withdraw' as const
+export const HL_PRIMARY_TYPE_SEND_ASSET =
+  'HyperliquidTransaction:SendAsset' as const
+export const HL_PRIMARY_TYPE_AGENT = 'Agent' as const
+
+export type HlPrimaryType =
+  | typeof HL_PRIMARY_TYPE_APPROVE_AGENT
+  | typeof HL_PRIMARY_TYPE_APPROVE_BUILDER_FEE
+  | typeof HL_PRIMARY_TYPE_USER_SET_ABSTRACTION
+  | typeof HL_PRIMARY_TYPE_AGENT_SET_ABSTRACTION
+  | typeof HL_PRIMARY_TYPE_WITHDRAW
+  | typeof HL_PRIMARY_TYPE_SEND_ASSET
+  | typeof HL_PRIMARY_TYPE_AGENT

package/src/providers/lighter/apiTypes.ts

@@ -0,0 +1,87 @@
+// ---------------------------------------------------------------------------
+// Lighter raw API response types — shared between backend (REST) and SDK (WS)
+// ---------------------------------------------------------------------------
+
+export type LtAccountPosition = {
+  market_id: number
+  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
+}
+
+export type LtAccountAsset = {
+  symbol: string
+  asset_id: number
+  balance: string
+  locked_balance: string
+}
+
+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
+}
+
+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
+  block_height: number
+  timestamp: number
+  created_at: number
+  updated_at: number
+  transaction_time: number
+}

package/src/providers/lighter/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js'
+export * from './apiTypes.js'
+export * from './mappers/index.js'

package/src/providers/lighter/mappers/fill.ts

@@ -0,0 +1,57 @@
+import {
+  FillStatus,
+  LiquidityRole,
+  OrderSide,
+  OrderType,
+} from '../../../enums.js'
+import type { Fill } from '../../../account.js'
+import type { LtTrade } from '../apiTypes.js'
+import { classifyFillFromPosition } from '../../_shared/fillClassification.js'
+
+/**
+ * Map a raw Lighter trade to the generic Fill type.
+ * @param accountIndex - The viewer's Lighter account index (selects buy/sell side and maker/taker role).
+ * @param symbol - Resolved symbol (market_id → symbol lookup).
+ */
+export const mapFill = (
+  trade: LtTrade,
+  accountIndex: number,
+  symbol: string
+): Fill => {
+  const isBuyer = trade.bid_account_id === accountIndex
+  const isMaker =
+    (trade.is_maker_ask && !isBuyer) || (!trade.is_maker_ask && isBuyer)
+
+  // Lighter publishes both counterparties' position-before snapshots on every
+  // trade row; reading the wrong one mis-classifies when they differ.
+  const startPosition = isMaker
+    ? trade.maker_position_size_before
+    : trade.taker_position_size_before
+
+  return {
+    id: trade.trade_id.toString(),
+    orderId: String(isBuyer ? trade.bid_id : trade.ask_id),
+    asset: {
+      assetId: symbol,
+      market: 'lighter',
+      displaySymbol: symbol,
+      displayQuote: 'USDC',
+    },
+    side: isBuyer ? OrderSide.BUY : OrderSide.SELL,
+    type: OrderType.LIMIT,
+    size: trade.size,
+    price: trade.price,
+    status: FillStatus.FILLED,
+    liquidity: isMaker ? LiquidityRole.MAKER : LiquidityRole.TAKER,
+    fee: isMaker ? trade.maker_fee?.toString() : trade.taker_fee?.toString(),
+    startPosition,
+    // `classifyFillFromPosition` takes an HL-encoded side: `'B'` for buy,
+    // anything else for sell.
+    classification: classifyFillFromPosition(
+      startPosition,
+      isBuyer ? 'B' : 'A',
+      trade.size
+    ),
+    createdAt: new Date(trade.timestamp).toISOString(),
+  }
+}

package/src/providers/lighter/mappers/index.ts

@@ -0,0 +1,8 @@
+export { mapPosition } from './position.js'
+export { mapFill } from './fill.js'
+export {
+  isTriggerType,
+  mapOrder,
+  mapOrderDetail,
+  mapTriggerOrder,
+} from './order.js'