@lifi/perps-sdk-provider-hyperliquid 8.0.0 → 9.0.0

package/src/utils/mapActivity.ts

@@ -1,6 +1,7 @@
 import type {
   ActivityItem,
   DepositActivity,
+  Fee,
   FundingActivity,
   LiquidationActivity,
   MarketDisplay,
@@ -9,15 +10,44 @@ import type {
 } from '@lifi/perps-types'
 import { ActivityType } from '@lifi/perps-types'
 import type { HlFundingUpdate, HlLedgerUpdate } from '../types/index.js'
-import { isSendAssetDelta, isSpotTransferDelta } from '../types/index.js'
+import {
+  isDepositDelta,
+  isLiquidationDelta,
+  isSendAssetDelta,
+  isSpotTransferDelta,
+  isWithdrawDelta,
+} from '../types/index.js'
+
+/**
+ * Hyperliquid settles every perp deposit and withdrawal in USDC, and charges
+ * the `spotTransfer` fee in USDC too — that delta carries no `feeToken`.
+ */
+const HL_COLLATERAL_SYMBOL = 'USDC'
+
+/**
+ * Hyperliquid's native token. A `nativeTokenFee` names no token on the wire,
+ * so the symbol comes from the venue rather than from the delta.
+ */
+const HL_NATIVE_TOKEN_SYMBOL = 'HYPE'
+
+/**
+ * Display symbol for a ledger delta's wire token (`"USDC"`, `"PURR:0x..."`).
+ * The colon separates the name from the token id, so the symbol is the part
+ * BEFORE it — the opposite half to a market coin's `dex:COIN`, which is why
+ * `coinAsset` cannot be reused here.
+ */
+const ledgerTokenSymbol = (token: string): string => {
+  const separator = token.indexOf(':')
+  return separator === -1 ? token : token.slice(0, separator)
+}
 
 /**
  * Map a Hyperliquid non-funding ledger entry to an ActivityItem.
  *
  * Direction for `spotTransfer` and `sendAsset` is derived from
  * `queriedAddress` matching the delta's `user` (OUT) or `destination` (IN).
- * Returns null for unsupported delta types and for same-user `sendAsset`
- * dex moves (where `user === destination === queriedAddress`).
+ * Returns null for unsupported delta types and for same-account moves, where
+ * `user === destination === queriedAddress`.
  * @public
  */
 export const mapLedgerEntry = (
@@ -40,6 +70,13 @@ export const mapLedgerEntry = (
     const queried = queriedAddress.toLowerCase()
     const sender = delta.user.toLowerCase()
     const recipient = delta.destination.toLowerCase()
+
+    // A transfer reports a movement between two accounts. A row whose sender
+    // and recipient are the queried account moves nothing between accounts.
+    if (sender === recipient && sender === queried) {
+      return null
+    }
+
     const direction: 'IN' | 'OUT' = queried === sender ? 'OUT' : 'IN'
     const counterpartyAddress = direction === 'OUT' ? recipient : sender
     const meta: Record<string, unknown> = {
@@ -48,22 +85,27 @@ export const mapLedgerEntry = (
     if (delta.usdcValue !== undefined) {
       meta.usdcValue = delta.usdcValue
     }
+    if (delta.nonce !== undefined) {
+      meta.nonce = delta.nonce
+    }
+    const fees: Fee[] = []
     if (delta.fee !== undefined) {
-      meta.fee = delta.fee
+      fees.push({ amount: delta.fee, asset: HL_COLLATERAL_SYMBOL })
     }
     if (delta.nativeTokenFee !== undefined) {
-      meta.nativeTokenFee = delta.nativeTokenFee
-    }
-    if (delta.nonce !== undefined) {
-      meta.nonce = delta.nonce
+      fees.push({
+        amount: delta.nativeTokenFee,
+        asset: HL_NATIVE_TOKEN_SYMBOL,
+      })
     }
     return {
       ...base,
       type: ActivityType.TRANSFER,
       direction,
       counterpartyAddress,
-      asset: delta.token,
+      asset: ledgerTokenSymbol(delta.token),
       amount: delta.amount,
+      ...(fees.length === 0 ? {} : { fees }),
       meta,
       explorerLink: entry.hash
         ? `https://app.hyperliquid.xyz/explorer/tx/${entry.hash}`
@@ -91,9 +133,6 @@ export const mapLedgerEntry = (
       sourceDex: delta.sourceDex,
       destinationDex: delta.destinationDex,
       usdcValue: delta.usdcValue,
-      fee: delta.fee,
-      nativeTokenFee: delta.nativeTokenFee,
-      feeToken: delta.feeToken,
       nonce: delta.nonce,
     }
     return {
@@ -101,8 +140,12 @@ export const mapLedgerEntry = (
       type: ActivityType.TRANSFER,
       direction,
       counterpartyAddress,
-      asset: delta.token,
+      asset: ledgerTokenSymbol(delta.token),
       amount: delta.amount,
+      fees: [
+        { amount: delta.fee, asset: ledgerTokenSymbol(delta.feeToken) },
+        { amount: delta.nativeTokenFee, asset: HL_NATIVE_TOKEN_SYMBOL },
+      ],
       meta,
       explorerLink: entry.hash
         ? `https://app.hyperliquid.xyz/explorer/tx/${entry.hash}`
@@ -110,59 +153,59 @@ export const mapLedgerEntry = (
     } satisfies TransferActivity
   }
 
-  switch (delta.type) {
-    case 'deposit':
-      return {
-        ...base,
-        type: ActivityType.DEPOSIT,
-        amount: delta.usdc ?? '0',
-        explorerLink: entry.hash
-          ? `https://scan.li.fi/tx/${entry.hash}`
-          : undefined,
-      } satisfies DepositActivity
-
-    case 'withdraw':
-      return {
-        ...base,
-        type: ActivityType.WITHDRAWAL,
-        amount: delta.usdc ?? '0',
-        fee: (delta as { fee?: string }).fee ?? '0',
-        explorerLink: entry.hash
-          ? `https://scan.li.fi/tx/${entry.hash}`
-          : undefined,
-      } satisfies WithdrawalActivity
+  if (isDepositDelta(delta)) {
+    return {
+      ...base,
+      type: ActivityType.DEPOSIT,
+      asset: HL_COLLATERAL_SYMBOL,
+      amount: delta.usdc,
+      explorerLink: entry.hash
+        ? `https://scan.li.fi/tx/${entry.hash}`
+        : undefined,
+    } satisfies DepositActivity
+  }
 
-    case 'liquidation': {
-      const d = delta as unknown as {
-        type: string
-        liquidatedNtlPos: string
-        accountValue: string
-        leverageType: string
-        liquidatedPositions?: { coin: string; szi: string }[]
-      }
-      const liquidatedPositions = (d.liquidatedPositions ?? []).map((p) => ({
-        market: resolveMarket(p.coin),
-        size: p.szi,
-      }))
-      // Liquidation rows must point to at least one market. Drop entries with
-      // missing/empty positions so downstream consumers can rely on that
-      // invariant and avoid rendering a market-less liquidation card.
-      if (liquidatedPositions.length === 0) {
-        return null
-      }
-      return {
-        ...base,
-        type: ActivityType.LIQUIDATION,
-        liquidatedNotionalPosition: d.liquidatedNtlPos,
-        accountValue: d.accountValue,
-        leverageType: d.leverageType,
-        liquidatedPositions,
-      } satisfies LiquidationActivity
-    }
+  if (isWithdrawDelta(delta)) {
+    return {
+      ...base,
+      type: ActivityType.WITHDRAWAL,
+      asset: HL_COLLATERAL_SYMBOL,
+      amount: delta.usdc,
+      ...(delta.fee === undefined
+        ? {}
+        : { fee: { amount: delta.fee, asset: HL_COLLATERAL_SYMBOL } }),
+      explorerLink: entry.hash
+        ? `https://scan.li.fi/tx/${entry.hash}`
+        : undefined,
+    } satisfies WithdrawalActivity
+  }
 
-    default:
+  if (isLiquidationDelta(delta)) {
+    const liquidatedPositions = (delta.liquidatedPositions ?? []).map((p) => ({
+      market: resolveMarket(p.coin),
+      size: p.szi,
+    }))
+    // Liquidation rows must point to at least one market. Drop entries with
+    // missing/empty positions so downstream consumers can rely on that
+    // invariant and avoid rendering a market-less liquidation card.
+    if (liquidatedPositions.length === 0) {
       return null
+    }
+    return {
+      ...base,
+      type: ActivityType.LIQUIDATION,
+      ...(delta.liquidatedNtlPos === undefined
+        ? {}
+        : { liquidatedNotionalPosition: delta.liquidatedNtlPos }),
+      ...(delta.accountValue === undefined
+        ? {}
+        : { accountValue: delta.accountValue }),
+      leverageType: delta.leverageType,
+      liquidatedPositions,
+    } satisfies LiquidationActivity
   }
+
+  return null
 }
 
 /**

package/src/utils/mapFill.ts

@@ -40,7 +40,10 @@ export const mapFill = (fill: HlUserFill, market: MarketDisplay): Fill => ({
   status: FillStatus.FILLED,
   liquidity: fill.crossed ? LiquidityRole.TAKER : LiquidityRole.MAKER,
   filledSize: fill.sz,
-  fee: fill.fee,
+  fee: {
+    amount: fill.fee,
+    asset: fill.feeToken ?? market.quoteAsset.displaySymbol,
+  },
   startPosition: fill.startPosition,
   explorerLink: explorerTxUrl(ExplorerChainId.HYPERLIQUID, fill.hash),
   classification:

package/src/utils/mapOrder.ts

@@ -12,6 +12,14 @@ import {
 } from '@lifi/perps-types'
 import type { HlFrontendOpenOrder, HlOrderDetail } from '../types/index.js'
 
+/**
+ * An order as seen by the REST `frontendOpenOrders` payload, or the smaller
+ * shape nested in the `orderUpdates` WebSocket frame. `mapOpenOrder` and
+ * `mapTriggerOrder` accept either so both code paths share one mapper.
+ * @public
+ */
+export type HlOrderLike = HlFrontendOpenOrder | HlOrderDetail['order']
+
 /**
  * Map a Hyperliquid orderType string to the OrderType enum.
  *
@@ -61,9 +69,7 @@ export const isTriggerType = (type: OrderType): boolean =>
  *   5. `orderType` — final fall-back via `isTriggerType`.
  * @public
  */
-export const isTriggerOrder = (
-  o: HlFrontendOpenOrder | HlOrderDetail['order']
-): boolean => {
+export const isTriggerOrder = (o: HlOrderLike): boolean => {
   if ('isTrigger' in o && o.isTrigger === true) {
     return true
   }
@@ -89,20 +95,21 @@ export const isTriggerOrder = (
  * @public
  */
 export const mapOpenOrder = (
-  o: HlFrontendOpenOrder,
+  o: HlOrderLike,
   market: MarketDisplay
 ): OpenOrder => ({
   orderId: String(o.oid),
   market,
   side: o.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
   type: mapOrderType(o.orderType),
-  size: o.sz,
+  originalSize: o.origSz,
+  remainingSize: 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,
+  label: 'isTrigger' in o && o.isTrigger ? o.triggerCondition : undefined,
   createdAt: new Date(o.timestamp).toISOString(),
 })
 
@@ -111,7 +118,7 @@ export const mapOpenOrder = (
  * @public
  */
 export const mapTriggerOrder = (
-  o: HlFrontendOpenOrder,
+  o: HlOrderLike,
   market: MarketDisplay
 ): TriggerOrder => {
   const type = mapOrderType(o.orderType)
@@ -122,7 +129,7 @@ export const mapTriggerOrder = (
     market,
     type,
     size: o.sz,
-    triggerPrice: o.triggerPx,
+    triggerPrice: o.triggerPx ?? '0',
     ...(isLimit ? { limitPrice: o.limitPx } : {}),
     label: o.triggerCondition,
     createdAt: new Date(o.timestamp).toISOString(),

package/src/websocket/HyperliquidWsProvider.ts

@@ -16,18 +16,16 @@ import {
   type WsStatusListener,
   wsLog,
 } from '@lifi/perps-sdk'
-import {
-  type AccountResponse,
-  type Balance,
-  type MarketContext,
-  type OpenOrder,
-  type OrderbookLevel,
-  type OrderbookResponse,
-  OrderSide,
-  OrderType,
-  type Position,
-  type Subscription,
-  type TriggerOrder,
+import type {
+  AccountResponse,
+  Balance,
+  MarketContext,
+  OpenOrder,
+  OrderbookLevel,
+  OrderbookResponse,
+  Position,
+  Subscription,
+  TriggerOrder,
 } from '@lifi/perps-types'
 import Big from 'big.js'
 import { isAddress } from 'viem'
@@ -69,9 +67,10 @@ import {
   isTriggerOrder,
   mapFill,
   mapMarketContext,
+  mapOpenOrder,
   mapOrderStatus,
-  mapOrderType,
   mapPosition,
+  mapTriggerOrder,
   partitionSpotBalances,
   priceStepToAggregation,
   spotAssetFromToken,
@@ -993,39 +992,15 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
         terminated.push(orderId)
         continue
       }
-      const type = mapOrderType(o.orderType)
       // Unknown market id (absent from the synced snapshot); skip just this item.
       const market = this.registry?.get(o.coin)
       if (!market) {
         continue
       }
-      const createdAt = new Date(o.timestamp).toISOString()
       if (isTriggerOrder(o)) {
-        const isLimit =
-          type === OrderType.TAKE_PROFIT_LIMIT || type === OrderType.STOP_LIMIT
-        triggerOrders.push({
-          orderId,
-          market,
-          type,
-          size: o.sz,
-          triggerPrice: o.triggerPx ?? '0',
-          ...(isLimit ? { limitPrice: o.limitPx } : {}),
-          label: o.triggerCondition,
-          createdAt,
-        })
+        triggerOrders.push(mapTriggerOrder(o, market))
       } else {
-        const filled = parseFloat(o.origSz) - parseFloat(o.sz)
-        openOrders.push({
-          orderId,
-          market,
-          side: o.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
-          type,
-          size: o.sz,
-          price: o.limitPx,
-          filledSize: filled.toString(),
-          reduceOnly: o.reduceOnly ?? false,
-          createdAt,
-        })
+        openOrders.push(mapOpenOrder(o, market))
       }
     }
     this.emit(key, {