@lifi/perps-types 0.1.1-alpha.0 → 0.1.1-alpha.10

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

@@ -0,0 +1,88 @@
+import {
+  OrderSide,
+  OrderStatus,
+  OrderType,
+  TimeInForce,
+} from '../../../enums.js'
+import type { OpenOrder } from '../../../account.js'
+import type { Order } from '../../../trading.js'
+import type { HlFrontendOpenOrder, HlOrderDetail } from '../types.js'
+
+import { resolveAssetIdFromLookup } from './shared.js'
+
+export const mapOpenOrder = (
+  o: HlFrontendOpenOrder,
+  dexKey: string,
+  assetIdLookup: Map<string, number>
+): OpenOrder => ({
+  id: String(o.oid),
+  symbol: o.coin,
+  assetId: resolveAssetIdFromLookup(assetIdLookup, o.coin),
+  dex: dexKey,
+  side: o.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
+  type: o.orderType === 'Limit' ? OrderType.LIMIT : OrderType.MARKET,
+  size: o.sz,
+  price: o.limitPx,
+  filledSize: o.origSz
+    ? (parseFloat(o.origSz) - parseFloat(o.sz)).toString()
+    : '0',
+  reduceOnly: o.reduceOnly ?? false,
+  createdAt: new Date(o.timestamp).toISOString(),
+})
+
+const mapOrderStatus = (status: string): OrderStatus => {
+  switch (status) {
+    case 'open':
+    case 'resting':
+      return OrderStatus.OPEN
+    case 'filled':
+      return OrderStatus.FILLED
+    case 'canceled':
+    case 'cancelled':
+      return OrderStatus.CANCELLED
+    case 'rejected':
+      return OrderStatus.REJECTED
+    case 'triggered':
+      return OrderStatus.TRIGGERED
+    case 'marginCanceled':
+      return OrderStatus.CANCELLED
+    default:
+      return OrderStatus.PENDING
+  }
+}
+
+const mapTimeInForce = (tif: string | undefined): TimeInForce | undefined => {
+  switch (tif) {
+    case 'Gtc':
+      return TimeInForce.GTC
+    case 'Ioc':
+      return TimeInForce.IOC
+    case 'Alo':
+      return TimeInForce.POST_ONLY
+    default:
+      return undefined
+  }
+}
+
+export const mapOrder = (detail: HlOrderDetail): Order => {
+  const o = detail.order
+  const filled = parseFloat(o.origSz) - parseFloat(o.sz)
+
+  return {
+    orderId: String(o.oid),
+    symbol: o.coin,
+    side: o.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
+    type: o.orderType === 'Limit' ? OrderType.LIMIT : OrderType.MARKET,
+    price: o.limitPx,
+    originalSize: o.origSz,
+    remainingSize: o.sz,
+    filledSize: filled.toString(),
+    timeInForce: mapTimeInForce(o.tif ?? undefined),
+    reduceOnly: o.reduceOnly ?? undefined,
+    isTrigger: o.triggerCondition !== undefined && o.triggerCondition !== 'N/A',
+    triggerPrice: o.triggerPx ?? undefined,
+    status: mapOrderStatus(detail.status),
+    createdAt: new Date(o.timestamp).toISOString(),
+    updatedAt: new Date(detail.statusTimestamp).toISOString(),
+  }
+}

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

@@ -0,0 +1,35 @@
+import { MarginMode, PositionSide } from '../../../enums.js'
+import type { Position } from '../../../account.js'
+import type { HlAssetPosition } from '../types.js'
+
+import { resolveAssetIdFromLookup } from './shared.js'
+
+export const mapPosition = (
+  ap: HlAssetPosition,
+  dexKey: string,
+  assetIdLookup: Map<string, number>
+): Position => {
+  const pos = ap.position
+  const szi = parseFloat(pos.szi)
+
+  return {
+    symbol: pos.coin,
+    assetId: resolveAssetIdFromLookup(assetIdLookup, pos.coin),
+    dex: dexKey,
+    side: szi >= 0 ? PositionSide.LONG : PositionSide.SHORT,
+    size: Math.abs(szi).toString(),
+    entryPrice: pos.entryPx ?? '0',
+    markPrice:
+      pos.positionValue && szi !== 0
+        ? (parseFloat(pos.positionValue) / Math.abs(szi)).toString()
+        : '0',
+    liquidationPrice: pos.liquidationPx ?? '0',
+    unrealizedPnl: pos.unrealizedPnl,
+    leverage: ap.position.leverage.value,
+    marginUsed: pos.marginUsed,
+    marginMode:
+      ap.position.leverage.type === 'cross'
+        ? MarginMode.CROSS
+        : MarginMode.ISOLATED,
+  }
+}

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

@@ -0,0 +1,15 @@
+/**
+ * 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

@@ -0,0 +1,255 @@
+// ---------------------------------------------------------------------------
+// Hyperliquid /info response types
+// ---------------------------------------------------------------------------
+
+// -- metaAndAssetCtxs -------------------------------------------------------
+
+export type HlUniverseItem = {
+  name: string
+  szDecimals: number
+  maxLeverage: number
+  onlyIsolated?: boolean
+  isDelisted?: boolean
+}
+
+export type HlMeta = {
+  universe: HlUniverseItem[]
+}
+
+export type HlAssetCtx = {
+  funding: string
+  openInterest: string
+  dayNtlVlm: string
+  markPx: string
+}
+
+export type HlMetaAndAssetCtxs = [HlMeta, HlAssetCtx[]]
+
+export type HlUniverse = HlMeta['universe']
+
+// -- allMids ----------------------------------------------------------------
+
+export type HlAllMids = Record<string, string>
+
+// -- candleSnapshot ---------------------------------------------------------
+
+export type HlCandle = {
+  t: number
+  o: string
+  h: string
+  l: string
+  c: string
+  v: string
+}
+
+export type HlCandleSnapshot = HlCandle[]
+
+// -- l2Book -----------------------------------------------------------------
+
+export type HlLevel = {
+  px: string
+  sz: string
+  n: number
+}
+
+export type HlL2Book = {
+  levels: [HlLevel[], HlLevel[]]
+  time: number
+}
+
+// -- clearinghouseState -----------------------------------------------------
+
+export type HlPosition = {
+  coin: string
+  szi: string
+  entryPx: string
+  positionValue: string
+  liquidationPx: string
+  unrealizedPnl: string
+  marginUsed: string
+  leverage: {
+    type: string
+    value: number
+  }
+}
+
+export type HlAssetPosition = {
+  position: HlPosition
+}
+
+export type HlClearinghouseState = {
+  assetPositions: HlAssetPosition[]
+  marginSummary: {
+    accountValue: string
+    totalMarginUsed: string
+  }
+  crossMarginSummary: {
+    accountValue: string
+    totalMarginUsed: string
+  }
+}
+
+// -- spotClearinghouseState -------------------------------------------------
+
+export type HlSpotBalance = {
+  coin: string
+  token: number
+  total: string
+  hold: string
+  entryNtl: string
+}
+
+export type HlSpotClearinghouseState = {
+  balances: HlSpotBalance[]
+}
+
+// -- userFees ---------------------------------------------------------------
+
+export type HlUserFees = {
+  userAddRate: string
+  userCrossRate: string
+  activeReferralDiscount: string
+}
+
+// -- frontendOpenOrders -----------------------------------------------------
+
+export type HlFrontendOpenOrder = {
+  oid: number
+  coin: string
+  side: string
+  sz: string
+  limitPx: string
+  orderType: string
+  origSz: string
+  reduceOnly: boolean
+  timestamp: number
+}
+
+export type HlFrontendOpenOrders = HlFrontendOpenOrder[]
+
+// -- extraAgents ------------------------------------------------------------
+
+export type HlExtraAgents = Record<string, unknown>[]
+
+// -- userFills / userFillsByTime --------------------------------------------
+
+export type HlUserFill = {
+  tid: number
+  coin: string
+  side: string
+  sz: string
+  px: string
+  dir: string
+  fee: string
+  closedPnl: string
+  time: number
+}
+
+export type HlUserFills = HlUserFill[]
+
+export type HlUserFillsByTime = HlUserFill[]
+
+// -- orderStatus ------------------------------------------------------------
+
+export type HlOrderDetail = {
+  order: {
+    oid: number
+    coin: string
+    side: string
+    sz: string
+    limitPx: string
+    orderType: string
+    origSz: string
+    reduceOnly: boolean
+    timestamp: number
+    tif: string | null
+    cloid: string | null
+    triggerCondition: string
+    triggerPx: string | null
+  }
+  status: string
+  statusTimestamp: number
+}
+
+export type HlOrderStatusFound = {
+  status: 'order'
+  order: HlOrderDetail
+}
+
+export type HlOrderStatusResponse =
+  | HlOrderStatusFound
+  | { status: 'unknownOid' }
+
+// -- userNonFundingLedgerUpdates --------------------------------------------
+
+export type HlLedgerDelta = {
+  type: string
+  usdc?: string
+  [key: string]: unknown
+}
+
+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[]
+
+// -- perpDexs ---------------------------------------------------------------
+
+export type HlPerpDexs = (null | { name: string })[]
+
+// ---------------------------------------------------------------------------
+// Exchange request / response types
+// ---------------------------------------------------------------------------
+
+export type HlExchangeRequest = {
+  action: Record<string, unknown>
+  signature: {
+    r: string
+    s: string
+    v: number
+  }
+  nonce: number
+  vaultAddress?: string | null
+}
+
+export type HlExchangeResponse = {
+  status: string
+  response?:
+    | string
+    | {
+        type: string
+        data?: {
+          statuses?: (
+            | string
+            | { filled: { totalSz: string; avgPx: string; oid: number } }
+            | { resting: { oid: number } }
+            | { waitingForFill: { oid: number } }
+            | { waitingForTrigger: { oid: number } }
+            | { success: true }
+            | { error: string }
+          )[]
+          status?: unknown
+        }
+      }
+}

package/src/subscriptions.ts

@@ -0,0 +1,73 @@
+import type { Address } from './typedData.js'
+import type {
+  Candle,
+  OhlcvInterval,
+  OrderbookResponse,
+  PricesResponse,
+} from './market.js'
+import type { HistoryItem, Position } from './account.js'
+import type { Order } from './trading.js'
+
+// --- Channels the user can subscribe to ---
+
+export type PricesSubscription = { channel: 'prices'; dex: string }
+export type OrderbookSubscription = {
+  channel: 'orderbook'
+  dex: string
+  symbol: string
+  depth?: number
+}
+export type TradesSubscription = {
+  channel: 'trades'
+  dex: string
+  symbol: string
+}
+export type CandleSubscription = {
+  channel: 'candle'
+  dex: string
+  symbol: string
+  interval: OhlcvInterval
+}
+export type OrderUpdatesSubscription = {
+  channel: 'orderUpdates'
+  dex: string
+  address: Address
+}
+export type FillsSubscription = {
+  channel: 'fills'
+  dex: string
+  address: Address
+}
+export type PositionsSubscription = {
+  channel: 'positions'
+  dex: string
+  address: Address
+}
+
+export type Subscription =
+  | PricesSubscription
+  | OrderbookSubscription
+  | TradesSubscription
+  | CandleSubscription
+  | OrderUpdatesSubscription
+  | FillsSubscription
+  | PositionsSubscription
+
+// --- Events emitted to listeners ---
+
+export type PricesEvent = { channel: 'prices'; data: PricesResponse }
+export type OrderbookEvent = { channel: 'orderbook'; data: OrderbookResponse }
+export type TradesEvent = { channel: 'trades'; data: HistoryItem[] }
+export type CandleEvent = { channel: 'candle'; data: Candle }
+export type OrderUpdatesEvent = { channel: 'orderUpdates'; data: Order[] }
+export type FillsEvent = { channel: 'fills'; data: HistoryItem[] }
+export type PositionsEvent = { channel: 'positions'; data: Position[] }
+
+export type SubscriptionEvent =
+  | PricesEvent
+  | OrderbookEvent
+  | TradesEvent
+  | CandleEvent
+  | OrderUpdatesEvent
+  | FillsEvent
+  | PositionsEvent

package/src/trading.ts

@@ -17,7 +17,6 @@ export interface CreateOrderRequest {
   dex: string
   address: Address
   signerAddress?: Address
-  clientOrderId?: string
   symbol: string
   side: OrderSide
   type: OrderType
@@ -78,7 +77,6 @@ export interface SubmitOrderResponse {
 
 export interface Order {
   orderId: string
-  clientOrderId?: string
   symbol: string
   side: OrderSide
   type: OrderType

package/src/typedData.ts

@@ -1,18 +1,12 @@
 import type { TypedData, SignedTypedData } from '@lifi/types'
 import type { Address, Hex, TypedDataDomain, TypedDataParameter } from 'viem'
 
-export type PerpsTypedDataPrimaryType =
-  | 'HyperliquidTransaction:ApproveAgent'
-  | 'HyperliquidTransaction:ApproveBuilderFee'
-  | 'HyperliquidTransaction:UserSetAbstraction'
-  | 'Agent'
-
 export type PerpsTypedData = Omit<TypedData, 'primaryType'> & {
-  primaryType: PerpsTypedDataPrimaryType
+  primaryType: string
 }
 
 export type PerpsSignedTypedData = Omit<SignedTypedData, 'primaryType'> & {
-  primaryType: PerpsTypedDataPrimaryType
+  primaryType: string
 }
 
 // Re-export viem primitives used across perps types

package/src/withdrawal.ts

@@ -0,0 +1,44 @@
+import type { Address, Hex, PerpsTypedData } from './typedData.js'
+
+export interface WithdrawalInput {
+  destination: Address
+  amount: string // e.g., "100.5" — units are $1 USDC
+}
+
+export interface CreateWithdrawalRequest {
+  dex: string
+  address: Address
+  withdrawal: WithdrawalInput
+}
+
+export interface WithdrawalAction {
+  action: string // "Withdraw"
+  description?: string
+  typedData: PerpsTypedData
+}
+
+export interface CreateWithdrawalResponse {
+  action: WithdrawalAction
+}
+
+export interface SignedWithdrawal {
+  action: string
+  typedData: PerpsTypedData
+  signature: Hex
+}
+
+export interface SubmitWithdrawalRequest {
+  dex: string
+  address: Address
+  action: SignedWithdrawal
+}
+
+export interface WithdrawalResult {
+  action: string
+  success: boolean
+  error?: string
+}
+
+export interface SubmitWithdrawalResponse {
+  result: WithdrawalResult
+}