@lifi/perps-sdk-provider-hyperliquid 25.0.0 → 27.0.0

package/src/services/getPortfolioHistory.ts

@@ -1,11 +1,17 @@
-import { PerpsError, type SDKRequestOptions } from '@lifi/perps-sdk'
 import {
+  PerpsError,
+  type SDKRequestOptions,
+  warnSkippedVenueRow,
+} from '@lifi/perps-sdk'
+import {
+  type DecimalString,
   PerpsErrorCode,
   type PortfolioHistoryPoint,
   type PortfolioHistoryRange,
   type PortfolioHistoryResponse,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
+import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import type {
   HlAbstractionMode,
@@ -40,19 +46,35 @@ const PERP_PERIOD_BY_RANGE: Record<PortfolioHistoryRange, HlPortfolioPeriod> = {
   all: 'perpAllTime',
 }
 
+/** The samples with a finite timestamp; each other sample is skipped. */
+const validSamples = (
+  samples: HlPortfolioWindow['pnlHistory'],
+  row: string
+): [number, DecimalString][] =>
+  samples.flatMap(([timestamp, value]): [number, DecimalString][] => {
+    if (!Number.isFinite(timestamp)) {
+      warnSkippedVenueRow(PROVIDER_KEY, row, 'timestamp', timestamp, {
+        expected: 'timestamp',
+      })
+      return []
+    }
+    return [[timestamp, value]]
+  })
+
 /**
  * Join the window's two series on their timestamps. `pnlHistory` is cumulative
  * from the window's start, so a point with no PnL sample carries the last
  * sampled value — `'0'` before the first one.
  */
 const joinWindow = (
-  window: HlPortfolioWindow,
+  accountValueHistory: [number, DecimalString][],
+  pnlHistory: [number, DecimalString][],
   period: HlPortfolioPeriod
 ): PortfolioHistoryPoint[] => {
-  const pnlByTimestamp = new Map(window.pnlHistory)
+  const pnlByTimestamp = new Map(pnlHistory)
   let matched = 0
   let cumulative = '0'
-  const points = window.accountValueHistory.map(([timestamp, accountValue]) => {
+  const points = accountValueHistory.map(([timestamp, accountValue]) => {
     const sample = pnlByTimestamp.get(timestamp)
     if (sample !== undefined) {
       matched += 1
@@ -60,7 +82,7 @@ const joinWindow = (
     }
     return { timestamp, accountValue, pnl: cumulative }
   })
-  if (points.length > 0 && window.pnlHistory.length > 0 && matched === 0) {
+  if (points.length > 0 && pnlHistory.length > 0 && matched === 0) {
     throw new PerpsError(
       PerpsErrorCode.ThirdPartyError,
       `Hyperliquid portfolio window '${period}' samples PnL on no ` +
@@ -111,10 +133,15 @@ export async function getPortfolioHistory(
     )
   }
 
+  const pnlHistory = validSamples(window.pnlHistory, 'portfolio PnL sample')
   return {
     range: params.range,
-    points: joinWindow(window, period),
+    points: joinWindow(
+      validSamples(window.accountValueHistory, 'portfolio value sample'),
+      pnlHistory,
+      period
+    ),
     volume: window.vlm,
-    totalPnl: window.pnlHistory.at(-1)?.[1],
+    totalPnl: pnlHistory.at(-1)?.[1],
   }
 }

package/src/services/getPositions.ts

@@ -67,12 +67,13 @@ export const getPositions = async (
       .filter(
         (ap) => !assetIsOutcome(ap.position.coin) && isOpenAssetPosition(ap)
       )
-      .map((ap) =>
-        mapPosition(
+      .flatMap((ap) => {
+        const position = mapPosition(
           ap,
           toPerpsMarketDisplay(registry.require(ap.position.coin))
         )
-      )
+        return position === undefined ? [] : [position]
+      })
   )
 
   if (params.marketId !== undefined) {

package/src/services/getWithdrawableBalances.ts

@@ -27,7 +27,7 @@ export type GetWithdrawableBalancesParams =
   ProviderGetWithdrawableBalancesParams
 
 /**
- * The `(asset, route)` pairs `params.address` can withdraw from Hyperliquid,
+ * The `(asset, category)` pairs `params.address` can withdraw from Hyperliquid,
  * read from the venue's own `withdrawable` and spot `total`/`hold` figures.
  * Hyperliquid charges its flat withdrawal fee in USDC, so the backend's
  * `withdrawalFeeUsd` is the fee in quote-asset units on every USDC row.

package/src/types/ws.ts

@@ -1,5 +1,6 @@
 // Hyperliquid WebSocket incoming message types.
 
+import type { DecimalString } from '@lifi/perps-types'
 import type { HlClearinghouseState, HlSpotBalance } from './account.js'
 import type { HlCandle, HlL2Book } from './asset.js'
 import type { HlUserFill } from './fill.js'
@@ -77,8 +78,8 @@ export type HlWsMessage = {
  * @public
  */
 export type HlWsFastAssetCtx = {
-  markPx?: string
-  midPx?: string | null
+  markPx?: DecimalString
+  midPx?: DecimalString | null
 }
 
 /**

package/src/utils/index.ts

@@ -27,6 +27,8 @@ export { hlInfoOptions, infoRequest } from './infoClient.js'
 export {
   calculateLiquidationPrice,
   calculateMaintenanceMarginRate,
+  safeCalculateLiquidationPrice,
+  safeCalculateMaintenanceMarginRate,
 } from './liquidation.js'
 export {
   mapFundingActivity,

package/src/utils/liquidation.ts

@@ -12,63 +12,75 @@
  * - margin_available = isolated_margin - maintenance_margin_required
  */
 
-import { estimateLiquidationPrice } from '@lifi/perps-sdk'
+import {
+  createSafeFunction,
+  divideDecimalString,
+  estimateLiquidationPrice,
+  numberToDecimalString,
+  PerpsError,
+} from '@lifi/perps-sdk'
+import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
 
 /**
- * Calculate the maintenance margin fraction for a Hyperliquid asset.
- *
- * Maintenance margin is half of the initial margin at max leverage.
+ * Maintenance margin fraction for a Hyperliquid asset: half of the initial
+ * margin at max leverage, `1 / (2 × maxLeverage)`.
  *
  * @param maxLeverage - Maximum leverage for the asset (e.g., 50 for BTC)
- * @returns Maintenance margin fraction (e.g., 0.01 for 50x max leverage),
- *   or undefined if maxLeverage is zero
+ * @returns Maintenance margin fraction (`'0.01'` for 50x max leverage)
+ * @throws {PerpsError} `ValidationError` when `maxLeverage` is not a finite
+ *   number above zero.
  * @public
  */
 export function calculateMaintenanceMarginRate(
   maxLeverage: number
-): number | undefined {
-  if (maxLeverage === 0) {
-    return undefined
+): DecimalString {
+  if (!Number.isFinite(maxLeverage) || maxLeverage <= 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `\`maxLeverage\` must be a finite number above zero, got ${maxLeverage}.`
+    )
   }
-  return 1 / (2 * maxLeverage)
+  return divideDecimalString('1', numberToDecimalString(2 * maxLeverage))
 }
 
+/** @public */
+export const safeCalculateMaintenanceMarginRate = createSafeFunction(
+  'calculateMaintenanceMarginRate',
+  calculateMaintenanceMarginRate
+)
+
 /**
- * Calculate liquidation price using the exact Hyperliquid formula.
- *
- * For isolated margin, new position prediction. For existing positions,
- * prefer Position.liquidationPrice from the API.
+ * Liquidation price of a new isolated position with the exact Hyperliquid
+ * formula. For an existing position, prefer `Position.liquidationPrice` from
+ * the API.
  *
  * Formula derivation (isolated margin, single position):
- *   margin_per_unit        = entryPrice / leverage
- *   maintenance_per_unit   = entryPrice * mmr
- *   margin_available       = margin_per_unit - maintenance_per_unit
- *   liq_price              = entryPrice - side * margin_available / (1 - mmr * side)
+ *   margin_available = entryPrice × (1 / leverage - mmr)
+ *   liq_price        = entryPrice - side × margin_available / (1 - mmr × side)
  *
- * Where mmr = 1 / (2 * maxLeverage).
- *
- * @param entryPrice - Position entry price
- * @param leverage - User-selected leverage (e.g., 10)
- * @param isLong - True if long position, false if short
- * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Determines
- *   the maintenance margin rate: mmr = 1 / (2 * maxLeverage)
- * @returns Estimated liquidation price, or undefined if inputs are invalid
+ * @param leverage - User-selected leverage (e.g., `'10'`)
+ * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Sets
+ *   mmr = 1 / (2 × maxLeverage).
+ * @throws {PerpsError} `ValidationError` when `maxLeverage` is not a finite
+ *   number above zero, or on an input that `estimateLiquidationPrice` rejects.
  * @public
  */
 export function calculateLiquidationPrice(
-  entryPrice: number,
-  leverage: number,
+  entryPrice: string,
+  leverage: string,
   isLong: boolean,
   maxLeverage: number
-): number | undefined {
-  const mmr = calculateMaintenanceMarginRate(maxLeverage)
-  if (mmr === undefined) {
-    return undefined
-  }
+): string {
   return estimateLiquidationPrice({
     entryPrice,
     leverage,
     isLong,
-    maintenanceMarginRate: mmr,
+    maintenanceMarginRate: calculateMaintenanceMarginRate(maxLeverage),
   })
 }
+
+/** @public */
+export const safeCalculateLiquidationPrice = createSafeFunction(
+  'calculateLiquidationPrice',
+  calculateLiquidationPrice
+)

package/src/utils/mapActivity.ts

@@ -3,6 +3,10 @@ import {
   ExplorerChainId,
   explorerTxUrl,
   PerpsError,
+  safeAddDecimalString,
+  safeMultiplyDecimalString,
+  safeSubtractDecimalString,
+  warnSkippedVenueRow,
 } from '@lifi/perps-sdk'
 import type {
   ActivityItem,
@@ -16,7 +20,6 @@ import type {
   WithdrawalActivity,
 } from '@lifi/perps-types'
 import { ActivityType, PerpsErrorCode } from '@lifi/perps-types'
-import Big from 'big.js'
 import { zeroHash } from 'viem'
 import type {
   HlBorrowLendOperation,
@@ -35,6 +38,7 @@ import {
   isVaultTransferDelta,
   isWithdrawDelta,
 } from '../types/index.js'
+import { rowTimestampToIsoStringOrUndefined } from './rowTimestamp.js'
 
 /**
  * Hyperliquid settles every perp deposit and withdrawal in USDC, and charges
@@ -96,11 +100,14 @@ export const mapLedgerEntry = (
   resolveMarket: (coin: string) => MarketDisplay | undefined
 ): ActivityItem | null => {
   const { delta } = entry
-  const base = {
-    id: entry.hash,
-    provider: providerKey,
-    timestamp: new Date(entry.time).toISOString(),
+  const timestamp = rowTimestampToIsoStringOrUndefined(entry.time)
+  if (timestamp === undefined) {
+    warnSkippedVenueRow(providerKey, 'ledger', 'time', entry.time, {
+      expected: 'timestamp',
+    })
+    return null
   }
+  const base = { id: entry.hash, provider: providerKey, timestamp }
 
   if (
     isSpotTransferDelta(delta) ||
@@ -315,7 +322,13 @@ export const mapFundingActivity = (
   if (market === undefined) {
     return null
   }
-  const timestamp = new Date(entry.time).toISOString()
+  const timestamp = rowTimestampToIsoStringOrUndefined(entry.time)
+  if (timestamp === undefined) {
+    warnSkippedVenueRow(providerKey, 'funding', 'time', entry.time, {
+      expected: 'timestamp',
+    })
+    return null
+  }
   return {
     id: `funding:${entry.delta.coin}:${timestamp}`,
     provider: providerKey,
@@ -334,7 +347,8 @@ export const mapFundingActivity = (
  * parties, so only fills whose `liquidatedUser` is the queried address count.
  * A fill whose hash a ledger liquidation row already carries is the same
  * event and is skipped. The size sign follows the closed position: a sell
- * fill closes a long. Groups whose market does not resolve are dropped.
+ * fill closes a long. Groups whose market or time does not resolve are
+ * dropped; an invalid fill size or price leaves the derived field absent.
  * @public
  */
 export const mapLiquidationFills = (
@@ -363,26 +377,40 @@ export const mapLiquidationFills = (
     if (market === undefined) {
       return []
     }
-    let size = new Big(0)
-    let notional = new Big(0)
-    let time = first.time
-    for (const fill of group) {
-      size = size.plus(fill.sz)
-      notional = notional.plus(new Big(fill.px).times(fill.sz))
-      time = Math.max(time, fill.time)
+    const size = group.reduce<string | undefined>(
+      (sum, fill) =>
+        sum === undefined ? undefined : safeAddDecimalString(sum, fill.sz),
+      '0'
+    )
+    const notional = group.reduce<string | undefined>((sum, fill) => {
+      const fillNotional = safeMultiplyDecimalString(fill.px, fill.sz)
+      return sum === undefined || fillNotional === undefined
+        ? undefined
+        : safeAddDecimalString(sum, fillNotional)
+    }, '0')
+    const time = Math.max(...group.map((fill) => fill.time))
+    const timestamp = rowTimestampToIsoStringOrUndefined(time)
+    if (timestamp === undefined) {
+      warnSkippedVenueRow(providerKey, 'liquidation', 'time', time, {
+        expected: 'timestamp',
+      })
+      return []
     }
+    const closedSize =
+      size === undefined || first.side === 'A'
+        ? size
+        : safeSubtractDecimalString('0', size)
     return [
       {
         id: `liquidation:${oid}`,
         provider: providerKey,
-        timestamp: new Date(time).toISOString(),
+        timestamp,
         type: ActivityType.LIQUIDATION,
-        liquidatedNotionalPosition: notional.toFixed(),
+        ...(notional === undefined
+          ? {}
+          : { liquidatedNotionalPosition: notional }),
         liquidatedPositions: [
-          {
-            market,
-            size: (first.side === 'A' ? size : size.neg()).toFixed(),
-          },
+          { market, ...(closedSize === undefined ? {} : { size: closedSize }) },
         ],
       } satisfies LiquidationActivity,
     ]

package/src/utils/mapFill.ts

@@ -2,6 +2,7 @@ import {
   classifyFillFromPosition,
   ExplorerChainId,
   explorerTxUrl,
+  warnSkippedVenueRow,
 } from '@lifi/perps-sdk'
 import type { Fill, MarketDisplay } from '@lifi/perps-types'
 import {
@@ -10,20 +11,35 @@ import {
   OrderSide,
   OrderType,
 } from '@lifi/perps-types'
-import { SPOT_MARKET_ID } from '../constants.js'
+import { PROVIDER_KEY, SPOT_MARKET_ID } from '../constants.js'
 import type { HlUserFill } from '../types/index.js'
+import { rowTimestampToIsoStringOrUndefined } from './rowTimestamp.js'
 
 /** Re-export the shared fill-position classifier used by Hyperliquid mappings. @public */
 export { classifyFillFromPosition }
 
 /**
  * Spot-ness comes from the resolved market's category, not the coin string —
- * HL's canonical spot pair 0 is addressed as `PURR/USDC`, not `@0`.
+ * HL's canonical spot pair 0 is addressed as `PURR/USDC`, not `@0`. A fill with
+ * an invalid time gives `undefined`.
  * @public
  */
-export const mapFill = (fill: HlUserFill, market: MarketDisplay): Fill => {
+export const mapFill = (
+  fill: HlUserFill,
+  market: MarketDisplay
+): Fill | undefined => {
+  const size = fill.sz
+  const createdAt = rowTimestampToIsoStringOrUndefined(fill.time)
+  if (createdAt === undefined) {
+    warnSkippedVenueRow(PROVIDER_KEY, 'fill', 'time', fill.time, {
+      marketId: market.id,
+      expected: 'timestamp',
+    })
+    return undefined
+  }
   // HL charges the builder portion in the same token as the total fee.
   const feeAsset = fill.feeToken ?? market.quoteAsset.displaySymbol
+  const side = fill.side === 'B' ? OrderSide.BUY : OrderSide.SELL
 
   return {
     ...(market.categoryId === SPOT_MARKET_ID
@@ -33,16 +49,16 @@ export const mapFill = (fill: HlUserFill, market: MarketDisplay): Fill => {
     orderId: String(fill.oid),
     clientOrderId: fill.cloid,
     market,
-    side: fill.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
+    side,
     // HL fills don't carry the originating order type. A maker fill (crossed:
     // false) can only come from a resting order, so it's necessarily a limit;
     // a taker fill (crossed: true) may be a market OR an aggressive limit order,
     // which the payload can't distinguish, so the type is left undefined.
     type: fill.crossed ? undefined : OrderType.LIMIT,
-    size: fill.sz,
+    size,
     price: fill.px,
     liquidity: fill.crossed ? LiquidityRole.TAKER : LiquidityRole.MAKER,
-    filledSize: fill.sz,
+    filledSize: size,
     fee: {
       amount: fill.fee,
       asset: feeAsset,
@@ -55,10 +71,10 @@ export const mapFill = (fill: HlUserFill, market: MarketDisplay): Fill => {
     explorerLink: explorerTxUrl(ExplorerChainId.HYPERLIQUID, fill.hash),
     classification:
       market.categoryId === SPOT_MARKET_ID
-        ? fill.side === 'B'
+        ? side === OrderSide.BUY
           ? FillClassification.SPOT_BUY
           : FillClassification.SPOT_SELL
-        : classifyFillFromPosition(fill.startPosition, fill.side, fill.sz),
-    createdAt: new Date(fill.time).toISOString(),
+        : classifyFillFromPosition(fill.startPosition, side, size),
+    createdAt,
   }
 }

package/src/utils/mapMarket.ts

@@ -1,16 +1,16 @@
+import { safeMultiplyDecimalString } from '@lifi/perps-sdk'
 import type { PerpsMarket } from '@lifi/perps-types'
 import { PositionMarginAdjustment } from '@lifi/perps-types'
-import Big from 'big.js'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HlMaxMarketOrderNtls, HlUniverseItem } from '../types/index.js'
-import { calculateMaintenanceMarginRate } from './liquidation.js'
+import { safeCalculateMaintenanceMarginRate } from './liquidation.js'
 import { coinAsset } from './marketDisplay.js'
 import { getMaxPriceDecimals } from './orderFormatting.js'
 
 /** Hyperliquid quotes every perp market in USDC. */
 const QUOTE_SYMBOL = 'USDC'
 /** Hyperliquid documents the limit-order notional cap as 10x the market-order cap. */
-const LIMIT_ORDER_VALUE_MULTIPLIER = 10
+const LIMIT_ORDER_VALUE_MULTIPLIER = '10'
 
 type MarketOrderLimits = Pick<
   PerpsMarket,
@@ -28,19 +28,21 @@ const mapMarketOrderLimits = (
   if (selected === undefined) {
     return {}
   }
-  const maxMarketOrderUsd = new Big(selected[1])
-  return {
-    maxMarketOrderUsd: maxMarketOrderUsd.toFixed(),
-    maxLimitOrderUsd: maxMarketOrderUsd
-      .times(LIMIT_ORDER_VALUE_MULTIPLIER)
-      .toFixed(),
+  const [, maxMarketOrderUsd] = selected
+  const maxLimitOrderUsd = safeMultiplyDecimalString(
+    maxMarketOrderUsd,
+    LIMIT_ORDER_VALUE_MULTIPLIER
+  )
+  if (maxLimitOrderUsd === undefined) {
+    return {}
   }
+  return { maxMarketOrderUsd, maxLimitOrderUsd }
 }
 
 /**
  * Map Hyperliquid universe metadata and optional `maxMarketOrderNtls` tiers to
- * a {@link PerpsMarket}. Missing tiers leave both order caps unset. Live stats
- * stay on {@link MarketContext}; callers supply the provider category id
+ * a {@link PerpsMarket}. Missing tiers or an invalid cap leave both order caps
+ * unset. Live stats stay on {@link MarketContext}; callers supply the provider category id
  * because the coin string does not contain it.
  * @public
  */
@@ -70,5 +72,7 @@ export const mapMarket = (
     (universe.marginMode === undefined && universe.onlyIsolated !== true)
       ? PositionMarginAdjustment.ADD_AND_REMOVE
       : PositionMarginAdjustment.ADD_ONLY,
-  maintenanceMarginRate: calculateMaintenanceMarginRate(universe.maxLeverage),
+  maintenanceMarginRate: safeCalculateMaintenanceMarginRate(
+    universe.maxLeverage
+  ),
 })

package/src/utils/mapMarketContext.ts

@@ -1,5 +1,8 @@
+import {
+  safeIsDecimalStringGreaterThan,
+  safeMultiplyDecimalString,
+} from '@lifi/perps-sdk'
 import type { MarketContext } from '@lifi/perps-types'
-import Big from 'big.js'
 import type { HlWsFastAssetCtx, HlWsPerpAssetCtx } from '../types/index.js'
 
 const NEXT_FUNDING_INTERVAL_MS = 60 * 60 * 1000 // 1 hour
@@ -12,15 +15,10 @@ const toOpenInterestNotional = (
   openInterest: string,
   markPrice: string
 ): string | undefined => {
-  try {
-    const mark = new Big(markPrice)
-    if (mark.lte(0)) {
-      return undefined
-    }
-    return new Big(openInterest).times(mark).toFixed()
-  } catch {
+  if (safeIsDecimalStringGreaterThan(markPrice, '0') !== true) {
     return undefined
   }
+  return safeMultiplyDecimalString(openInterest, markPrice)
 }
 
 /**