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

package/src/types/ledger.ts

@@ -50,6 +50,51 @@ export type HlSendAssetDelta = {
   feeToken: string
 }
 
+/**
+ * Hyperliquid `deposit` ledger delta. Perp-collateral deposits are always
+ * USDC-denominated, which is why the amount arrives in a field named `usdc`.
+ * @public
+ */
+export type HlDepositDelta = {
+  type: 'deposit'
+  usdc: string
+}
+
+/**
+ * Hyperliquid `withdraw` ledger delta. `fee` is denominated in the withdrawn
+ * asset (USDC) and is absent when the venue charges none.
+ * @public
+ */
+export type HlWithdrawDelta = {
+  type: 'withdraw'
+  usdc: string
+  fee?: string
+}
+
+/**
+ * One position closed by a Hyperliquid liquidation. `coin` is the venue market
+ * key and `szi` the signed position size.
+ * @public
+ */
+export type HlLiquidatedPosition = {
+  coin: string
+  szi: string
+}
+
+/**
+ * Hyperliquid `liquidation` ledger delta. A cross-margin cascade reports every
+ * closed position in `liquidatedPositions`, so the venue itself carries the
+ * grouping and no timestamp heuristic is needed.
+ * @public
+ */
+export type HlLiquidationDelta = {
+  type: 'liquidation'
+  liquidatedNtlPos?: string
+  accountValue?: string
+  leverageType: string
+  liquidatedPositions?: HlLiquidatedPosition[]
+}
+
 /**
  * Union of known Hyperliquid non-funding ledger deltas plus an open fallback
  * for endpoint variants the provider does not map.
@@ -58,6 +103,9 @@ export type HlSendAssetDelta = {
 export type HlLedgerDelta =
   | HlSpotTransferDelta
   | HlSendAssetDelta
+  | HlDepositDelta
+  | HlWithdrawDelta
+  | HlLiquidationDelta
   | {
       type: string
       usdc?: string
@@ -85,6 +133,38 @@ export const isSendAssetDelta = (
   delta: HlLedgerDelta
 ): delta is HlSendAssetDelta => delta.type === 'send'
 
+// `usdc` is declared only on the union's catch-all arm, so reading it off the
+// union needs a widening read before the discriminant has narrowed the type.
+const hasUsdcAmount = (delta: HlLedgerDelta): boolean =>
+  typeof (delta as { usdc?: unknown }).usdc === 'string'
+
+/**
+ * Type guard for `HlDepositDelta`. The amount is part of the guard: a deposit
+ * row without one identifies no movement, and reporting it as a zero amount
+ * would read as a real zero-value deposit.
+ * @public
+ */
+export const isDepositDelta = (delta: HlLedgerDelta): delta is HlDepositDelta =>
+  delta.type === 'deposit' && hasUsdcAmount(delta)
+
+/**
+ * Type guard for `HlWithdrawDelta`. Same amount-bearing requirement as
+ * `isDepositDelta`.
+ * @public
+ */
+export const isWithdrawDelta = (
+  delta: HlLedgerDelta
+): delta is HlWithdrawDelta => delta.type === 'withdraw' && hasUsdcAmount(delta)
+
+/**
+ * Type guard for `HlLiquidationDelta`. Same catch-all-arm caveat as
+ * `isSpotTransferDelta`.
+ * @public
+ */
+export const isLiquidationDelta = (
+  delta: HlLedgerDelta
+): delta is HlLiquidationDelta => delta.type === 'liquidation'
+
 /**
  * One timestamped non-funding ledger update. `time` is milliseconds since
  * epoch and `hash` is the upstream transaction identifier.
@@ -108,6 +188,10 @@ export type HlUserNonFundingLedgerUpdates = HlLedgerUpdate[]
 export type HlFundingDelta = {
   type: 'funding'
   coin: string
+  /**
+   * Signed, in USDC. Positive means the account received funding; negative
+   * means the account paid it. Mapped straight onto `FundingActivity.amount`.
+   */
   usdc: string
   szi: string
   fundingRate: string

package/src/utils/index.ts

@@ -23,6 +23,7 @@ export { classifyFillFromPosition, mapFill } from './mapFill.js'
 export { mapMarket } from './mapMarket.js'
 export { mapMarketContext } from './mapMarketContext.js'
 export {
+  type HlOrderLike,
   isTriggerOrder,
   isTriggerType,
   mapOpenOrder,

package/src/utils/mapActivity.ts

@@ -1,6 +1,7 @@
 import type {
   ActivityItem,
   DepositActivity,
+  Fee,
   FundingActivity,
   LiquidationActivity,
   MarketDisplay,
@@ -9,22 +10,55 @@ 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`.
+ *
+ * @param resolveMarket - Market identity for a venue coin, or `undefined` when
+ * the backend market list does not hold it. A liquidated position the resolver
+ * cannot identify is dropped.
  * @public
  */
 export const mapLedgerEntry = (
   entry: HlLedgerUpdate,
   providerKey: string,
   queriedAddress: string,
-  resolveMarket: (coin: string) => MarketDisplay
+  resolveMarket: (coin: string) => MarketDisplay | undefined
 ): ActivityItem | null => {
   const { delta } = entry
   const base = {
@@ -40,6 +74,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 +89,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 +137,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 +144,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,65 +157,67 @@ 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 resolvedPositions = (delta.liquidatedPositions ?? []).flatMap((p) => {
+      const market = resolveMarket(p.coin)
+      return market === undefined ? [] : [{ market, 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.
+    const [firstPosition, ...restPositions] = resolvedPositions
+    if (firstPosition === undefined) {
       return null
+    }
+    return {
+      ...base,
+      type: ActivityType.LIQUIDATION,
+      ...(delta.liquidatedNtlPos === undefined
+        ? {}
+        : { liquidatedNotionalPosition: delta.liquidatedNtlPos }),
+      ...(delta.accountValue === undefined
+        ? {}
+        : { accountValue: delta.accountValue }),
+      leverageType: delta.leverageType,
+      liquidatedPositions: [firstPosition, ...restPositions],
+    } satisfies LiquidationActivity
   }
+
+  return null
 }
 
 /**
- * Map a Hyperliquid funding ledger update to a normalized funding activity.
- * `amount`, `positionSize`, and `fundingRate` retain the upstream decimal
- * strings; `resolveMarket` supplies the provider-agnostic market metadata.
+ * Map a Hyperliquid funding ledger update to a normalized funding activity, or
+ * `null` when `resolveMarket` cannot identify the row's coin. `amount`,
+ * `positionSize`, and `fundingRate` retain the upstream decimal strings;
+ * `resolveMarket` supplies the provider-agnostic market metadata.
  *
  * `userFunding` entries all carry the zero hash, so a deterministic
  * `funding:<coin>:<ISO time>` id is synthesized — funding accrues at most
@@ -178,15 +227,19 @@ export const mapLedgerEntry = (
 export const mapFundingActivity = (
   entry: HlFundingUpdate,
   providerKey: string,
-  resolveMarket: (coin: string) => MarketDisplay
-): FundingActivity => {
+  resolveMarket: (coin: string) => MarketDisplay | undefined
+): FundingActivity | null => {
+  const market = resolveMarket(entry.delta.coin)
+  if (market === undefined) {
+    return null
+  }
   const timestamp = new Date(entry.time).toISOString()
   return {
     id: `funding:${entry.delta.coin}:${timestamp}`,
     provider: providerKey,
     timestamp,
     type: ActivityType.FUNDING,
-    market: resolveMarket(entry.delta.coin),
+    market,
     amount: entry.delta.usdc,
     positionSize: entry.delta.szi,
     fundingRate: entry.delta.fundingRate,

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, {