@lifi/perps-types 0.1.1-alpha.2 → 0.1.1-alpha.21

package/src/asset.ts

@@ -0,0 +1,88 @@
+export interface FundingInfo {
+  rate: string
+  nextFundingTime: number
+}
+
+export interface AssetIdentity {
+  assetId: string // provider's canonical identity: "BTC", "xyz:PURR", "@142"
+  market: string // market category from /providers.markets: "hyperliquid", "xyz", "spot"
+}
+
+export interface Asset extends AssetIdentity {
+  displaySymbol: string // UI base name: "BTC", "PURR"; spot keeps full pair: "PURR/USDC"
+  displayQuote: string | null // quote asset for perps: "USDC", "USDH"; null for spot
+  displayName?: string // future: "Bitcoin", "Ethereum"
+  logoURI: string
+  szDecimals: number
+  maxLeverage: number
+  onlyIsolated: boolean
+  isMarginCollateral?: boolean
+  funding: FundingInfo
+  openInterest?: string
+  volume24h?: string
+  prevDayPrice?: string
+  markPrice: string
+}
+
+export type AssetDisplay = Pick<
+  Asset,
+  'assetId' | 'market' | 'displaySymbol' | 'displayQuote'
+>
+
+export interface AssetPrice {
+  assetId: string
+  price: string
+}
+
+export interface AssetsResponse {
+  assets: Asset[]
+}
+
+export interface PricesResponse {
+  prices: AssetPrice[]
+}
+
+export interface Candle {
+  t: number
+  o: string
+  h: string
+  l: string
+  c: string
+  v: string
+}
+
+export interface OhlcvResponse {
+  provider: string
+  assetId: string
+  interval: string
+  candles: Candle[]
+}
+
+export type OhlcvInterval =
+  | '1m'
+  | '3m'
+  | '5m'
+  | '15m'
+  | '30m'
+  | '1h'
+  | '2h'
+  | '4h'
+  | '8h'
+  | '12h'
+  | '1d'
+  | '3d'
+  | '1w'
+  | '1M'
+
+export interface OrderbookLevel {
+  price: string
+  size: string
+}
+
+export interface OrderbookResponse {
+  provider: string
+  assetId: string
+  bids: OrderbookLevel[]
+  asks: OrderbookLevel[]
+  timestamp: number
+}

package/src/enums.ts

@@ -5,6 +5,7 @@ export enum PerpsErrorCode {
   ValidationError = 2002,
   TimeoutError = 2003,
   ThirdPartyError = 2004,
+  SDKError = 2005,
 
   // Auth errors (2010-2019)
   SignatureInvalid = 2010,
@@ -38,6 +39,11 @@ export enum OrderSide {
 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',
 }
 
 export enum PositionSide {
@@ -68,18 +74,26 @@ export enum OrderStatus {
   TRIGGERED = 'TRIGGERED',
 }
 
-export enum HistoryItemStatus {
+export enum FillStatus {
   FILLED = 'FILLED',
   PARTIALLY_FILLED = 'PARTIALLY_FILLED',
   CANCELLED = 'CANCELLED',
   REJECTED = 'REJECTED',
 }
 
-export enum OrderActionType {
-  UPDATE_LEVERAGE = 'updateLeverage',
+export enum ActionType {
+  APPROVE_AGENT = 'approveAgent',
+  APPROVE_BUILDER_FEE = 'approveBuilderFee',
+  USER_SET_ABSTRACTION = 'userSetAbstraction',
+  AGENT_SET_ABSTRACTION = 'agentSetAbstraction',
+  SEND_ASSET = 'sendAsset',
+  WITHDRAWAL = 'withdrawal',
   PLACE_ORDER = 'placeOrder',
   PLACE_TRIGGER_ORDER = 'placeTriggerOrder',
   CANCEL_ORDER = 'cancelOrder',
+  MODIFY_ORDER = 'modifyOrder',
+  UPDATE_LEVERAGE = 'updateLeverage',
+  UPDATE_POSITION_MARGIN = 'updatePositionMargin',
 }
 
 export enum TriggerCondition {
@@ -97,3 +111,49 @@ export enum TriggerOrderStatus {
   TRIGGERED = 'TRIGGERED',
   CANCELLED = 'CANCELLED',
 }
+
+export enum ActivityType {
+  DEPOSIT = 'DEPOSIT',
+  WITHDRAWAL = 'WITHDRAWAL',
+  LIQUIDATION = 'LIQUIDATION',
+  FUNDING = 'FUNDING',
+}
+
+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',
+}
+
+export enum LiquidationClassification {
+  LIQUIDATED = 'Liquidated',
+}
+
+export enum FundingClassification {
+  FUNDING = 'Funding',
+}
+
+export enum TransferClassification {
+  DEPOSIT = 'Deposit',
+  WITHDRAWAL = 'Withdrawal',
+}
+
+export type ActivityClassification =
+  | FillClassification
+  | LiquidationClassification
+  | FundingClassification
+  | TransferClassification
+
+export enum PerpsSigner {
+  USER = 'USER',
+  AGENT = 'AGENT',
+}

package/src/index.ts

@@ -1,9 +1,8 @@
 export * from './typedData.js'
 export * from './enums.js'
-export * from './market.js'
-export * from './authorization.js'
+export * from './providers.js'
+export * from './asset.js'
+export * from './action.js'
 export * from './account.js'
-export * from './trading.js'
-export * from './withdrawal.js'
 export * from './errors.js'
 export * from './subscriptions.js'

package/src/providers/hyperliquid/assetId.ts

@@ -1,26 +1,32 @@
+/** Spot asset IDs use the @pairIndex format (e.g. "@230"). */
+export const assetIsSpot = (assetId: string): boolean => assetId.startsWith('@')
+
 /**
- * Calculate the asset ID for a given DEX index and asset index.
+ * Calculate the asset ID for a given provider index and asset index.
  *
- * Main DEX (dex = ''): assetId = indexInDex
- * HIP-3 DEXes (dex = 'xyz'): assetId = 100_000 + perpDexIndex * 10_000 + indexInDex
+ * Main provider (provider = ''): assetId = indexInProvider
+ * HIP-3 providers (provider = 'xyz'): assetId = 100_000 + perpDexIndex * 10_000 + indexInProvider
  */
 export const calculateAssetId = (
-  dexIndex: number,
-  indexInDex: number
+  providerIndex: number,
+  indexInProvider: number
 ): number => {
-  if (dexIndex === 0) {
-    return indexInDex
+  if (providerIndex === 0) {
+    return indexInProvider
   }
-  return 100_000 + dexIndex * 10_000 + indexInDex
+  return 100_000 + providerIndex * 10_000 + indexInProvider
 }
 
 /**
- * Get the DEX index from the given list of dex names.
+ * Get the provider index from the given list of provider names.
  */
-export const getDexIndex = (dex: string, dexNames: string[]): number => {
-  const index = dexNames.indexOf(dex)
+export const getProviderIndex = (
+  provider: string,
+  providerNames: string[]
+): number => {
+  const index = providerNames.indexOf(provider)
   if (index === -1) {
-    throw new Error(`Unknown sub-dex: ${dex}`)
+    throw new Error(`Unknown sub-provider: ${provider}`)
   }
   return index
 }

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

@@ -0,0 +1,94 @@
+import { ActivityType } from '../../../enums.js'
+import type {
+  ActivityItem,
+  DepositActivity,
+  WithdrawalActivity,
+  LiquidationActivity,
+  FundingActivity,
+} from '../../../account.js'
+import type { HlLedgerUpdate, HlFundingUpdate } from '../types.js'
+
+/**
+ * Map a Hyperliquid non-funding ledger entry to an ActivityItem.
+ * Returns null for unsupported delta types (accountClassTransfer,
+ * internalTransfer, subAccountTransfer, spotTransfer).
+ */
+export const mapLedgerEntry = (
+  entry: HlLedgerUpdate,
+  providerKey: string
+): ActivityItem | null => {
+  const { delta } = entry
+  const base = {
+    id: entry.hash,
+    provider: providerKey,
+    timestamp: new Date(entry.time).toISOString(),
+  }
+
+  switch (delta.type) {
+    case 'deposit':
+      return {
+        ...base,
+        type: ActivityType.DEPOSIT,
+        amount: delta.usdc ?? '0',
+      } satisfies DepositActivity
+
+    case 'withdraw':
+      return {
+        ...base,
+        type: ActivityType.WITHDRAWAL,
+        amount: delta.usdc ?? '0',
+        fee: (delta as { fee?: string }).fee ?? '0',
+      } satisfies WithdrawalActivity
+
+    case 'liquidation': {
+      const d = delta as unknown as {
+        type: string
+        liquidatedNtlPos: string
+        accountValue: string
+        leverageType: string
+        liquidatedPositions?: { coin: string; szi: string }[]
+      }
+      return {
+        ...base,
+        type: ActivityType.LIQUIDATION,
+        liquidatedNotionalPosition: d.liquidatedNtlPos,
+        accountValue: d.accountValue,
+        leverageType: d.leverageType,
+        liquidatedPositions: (d.liquidatedPositions ?? []).map((p) => ({
+          asset: {
+            assetId: p.coin,
+            market: '',
+            displaySymbol: p.coin,
+            displayQuote: null,
+          },
+          size: p.szi,
+        })),
+      } satisfies LiquidationActivity
+    }
+
+    default:
+      return null
+  }
+}
+
+/**
+ * Map a Hyperliquid funding entry to a FundingActivity.
+ */
+export const mapFundingActivity = (
+  entry: HlFundingUpdate,
+  providerKey: string
+): FundingActivity => ({
+  id: entry.hash,
+  provider: providerKey,
+  timestamp: new Date(entry.time).toISOString(),
+  type: ActivityType.FUNDING,
+  asset: {
+    assetId: entry.delta.coin,
+    market: '',
+    displaySymbol: entry.delta.coin,
+    displayQuote: null,
+  },
+  amount: entry.delta.usdc,
+  positionSize: entry.delta.szi,
+  fundingRate: entry.delta.fundingRate,
+})

package/src/providers/hyperliquid/mappers/{market.ts → asset.ts}

@@ -1,26 +1,22 @@
-import type { Market } from '../../../market.js'
-import { calculateAssetId } from '../assetId.js'
+import type { Asset } from '../../../asset.js'
 import type { HlAssetCtx, HlUniverseItem } from '../types.js'
 
 const NEXT_FUNDING_INTERVAL_MS = 60 * 60 * 1000 // 1 hour
 
-export const mapMarket = (
+export const mapAsset = (
   universe: HlUniverseItem,
-  assetCtx: HlAssetCtx,
-  dexIndex: number,
-  indexInDex: number,
-  dexKey: string
-): Market => {
+  assetCtx: HlAssetCtx
+): Asset => {
   const now = Date.now()
   const nextFundingTime =
     Math.ceil(now / NEXT_FUNDING_INTERVAL_MS) * NEXT_FUNDING_INTERVAL_MS
 
   return {
-    symbol: universe.name,
-    name: universe.name,
+    assetId: universe.name,
+    market: '',
+    displaySymbol: universe.name,
+    displayQuote: null,
     logoURI: `https://app.hyperliquid.xyz/coins/${universe.name}.svg`,
-    assetId: calculateAssetId(dexIndex, indexInDex),
-    dex: dexKey,
     szDecimals: universe.szDecimals,
     maxLeverage: universe.maxLeverage,
     onlyIsolated: universe.onlyIsolated === true,
@@ -30,6 +26,7 @@ export const mapMarket = (
     },
     openInterest: assetCtx.openInterest,
     volume24h: assetCtx.dayNtlVlm,
+    prevDayPrice: assetCtx.prevDayPx,
     markPrice: assetCtx.markPx,
   }
 }

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

@@ -0,0 +1,77 @@
+import {
+  FillClassification,
+  FillStatus,
+  OrderSide,
+  OrderType,
+} from '../../../enums.js'
+import type { Fill } from '../../../account.js'
+import type { HlUserFill } from '../types.js'
+import { assetIsSpot } from '../assetId.js'
+
+export function classifyFillFromPosition(
+  startPosition: string,
+  side: string,
+  sz: string
+): FillClassification {
+  const start = parseFloat(startPosition)
+  const delta = side === 'B' ? parseFloat(sz) : -parseFloat(sz)
+  const end = start + delta
+
+  // Position was flat → opening
+  if (start === 0) {
+    return end > 0
+      ? FillClassification.OPENED_LONG
+      : FillClassification.OPENED_SHORT
+  }
+
+  // Position was long
+  if (start > 0) {
+    if (end === 0) {
+      return FillClassification.CLOSED_LONG
+    }
+    if (end < 0) {
+      return FillClassification.SWITCHED_SHORT
+    }
+    if (end > start) {
+      return FillClassification.INCREASED_LONG
+    }
+    return FillClassification.REDUCED_LONG
+  }
+
+  // Position was short (start < 0)
+  if (end === 0) {
+    return FillClassification.CLOSED_SHORT
+  }
+  if (end > 0) {
+    return FillClassification.SWITCHED_LONG
+  }
+  if (end < start) {
+    return FillClassification.INCREASED_SHORT
+  }
+  return FillClassification.REDUCED_SHORT
+}
+
+export const mapFill = (fill: HlUserFill): Fill => ({
+  id: String(fill.tid),
+  asset: {
+    assetId: fill.coin,
+    market: '',
+    displaySymbol: fill.coin,
+    displayQuote: null,
+  },
+  side: fill.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
+  type: fill.dir?.includes('Limit') ? OrderType.LIMIT : OrderType.MARKET,
+  size: fill.sz,
+  price: fill.px,
+  status: FillStatus.FILLED,
+  filledSize: fill.sz,
+  fee: fill.fee,
+  realizedPnl: fill.closedPnl === '0' ? null : fill.closedPnl,
+  startPosition: fill.startPosition,
+  classification: assetIsSpot(fill.coin)
+    ? fill.side === 'B'
+      ? FillClassification.SPOT_BUY
+      : FillClassification.SPOT_SELL
+    : classifyFillFromPosition(fill.startPosition, fill.side, fill.sz),
+  createdAt: new Date(fill.time).toISOString(),
+})

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

@@ -1,5 +1,11 @@
-export { resolveAssetIdFromLookup } from './shared.js'
-export { mapMarket } from './market.js'
-export { mapOpenOrder, mapOrder } from './order.js'
+export { mapAsset } from './asset.js'
+export {
+  isTriggerType,
+  mapOpenOrder,
+  mapOrder,
+  mapOrderType,
+  mapTriggerOrder,
+} from './order.js'
 export { mapPosition } from './position.js'
-export { mapHistoryItem } from './history.js'
+export { classifyFillFromPosition, mapFill } from './fill.js'
+export { mapLedgerEntry, mapFundingActivity } from './activity.js'

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

@@ -4,32 +4,75 @@ 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 { 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 mapOpenOrder = (
-  o: HlFrontendOpenOrder,
-  dexKey: string,
-  assetIdLookup: Map<string, number>
-): OpenOrder => ({
+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): OpenOrder => ({
   id: String(o.oid),
-  symbol: o.coin,
-  assetId: resolveAssetIdFromLookup(assetIdLookup, o.coin),
-  dex: dexKey,
+  asset: {
+    assetId: o.coin,
+    market: '',
+    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: '',
+      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':
@@ -70,10 +113,14 @@ export const mapOrder = (detail: HlOrderDetail): Order => {
 
   return {
     orderId: String(o.oid),
-    clientOrderId: o.cloid ?? undefined,
-    symbol: o.coin,
+    asset: {
+      assetId: o.coin,
+      market: '',
+      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,

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

@@ -2,20 +2,17 @@ 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 => {
+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: '',
+      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
-}