@lifi/perps-sdk-provider-hyperliquid 12.0.0 → 13.0.0

package/src/HyperliquidProvider.ts

@@ -14,6 +14,7 @@ import {
   type ProviderGetMarketSettingsParams,
   type ProviderGetOrderParams,
   type ProviderGetOrdersParams,
+  type ProviderGetPortfolioHistoryParams,
   type ProviderGetPositionsParams,
   type ProviderGetQuoteParams,
   type ProviderGetRunningTwapsParams,
@@ -38,6 +39,7 @@ import {
   PerpsErrorCode,
   type PerpsMarket,
   PerpsSigner,
+  type PortfolioHistoryResponse,
   type Position,
   type PositionsResponse,
   type ProviderAction,
@@ -63,6 +65,7 @@ import { getFills } from './services/getFills.js'
 import { getMarketSettings } from './services/getMarketSettings.js'
 import { getOrder } from './services/getOrder.js'
 import { getOrders } from './services/getOrders.js'
+import { getPortfolioHistory } from './services/getPortfolioHistory.js'
 import { getPositions } from './services/getPositions.js'
 import { getRunningTwaps } from './services/getRunningTwaps.js'
 import {
@@ -387,6 +390,16 @@ export function hyperliquidProvider(
         opts
       ),
 
+    getPortfolioHistory: (
+      params: ProviderGetPortfolioHistoryParams,
+      opts?: SDKRequestOptions
+    ): Promise<PortfolioHistoryResponse> =>
+      getPortfolioHistory(
+        contextRef.require(),
+        { address: params.address, range: params.range },
+        opts
+      ),
+
     getQuote: (
       params: ProviderGetQuoteParams,
       opts?: SDKRequestOptions

package/src/index.ts

@@ -35,6 +35,8 @@ export type { GetOrderParams } from './services/getOrder.js'
 export { getOrder } from './services/getOrder.js'
 export type { GetOrdersParams } from './services/getOrders.js'
 export { getOrders } from './services/getOrders.js'
+export type { GetPortfolioHistoryParams } from './services/getPortfolioHistory.js'
+export { getPortfolioHistory } from './services/getPortfolioHistory.js'
 export type { GetPositionsParams } from './services/getPositions.js'
 export { getPositions } from './services/getPositions.js'
 export type { GetRunningTwapsParams } from './services/getRunningTwaps.js'

package/src/services/getAccount.ts

@@ -13,6 +13,7 @@ import type {
   HyperliquidAccountConfig,
   Position,
 } from '@lifi/perps-types'
+import type Big from 'big.js'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import {
@@ -22,6 +23,8 @@ import {
   type HlSpotClearinghouseState,
   type HlUserFees,
 } from '../types/index.js'
+import { isUnifiedAbstraction } from '../utils/abstractionMode.js'
+import { toWireBig } from '../utils/decimal.js'
 import {
   partitionSpotBalances,
   perpsDexNames,
@@ -42,8 +45,8 @@ export type GetAccountParams = ProviderGetAccountParams
 // `marginSummary` covers the whole account (cross AND isolated positions);
 // `crossMarginSummary` is the cross-only subset and would drop isolated
 // equity/margin.
-const getAccountValue = (state: HlClearinghouseState): number =>
-  Number.parseFloat(state.marginSummary.accountValue)
+const getAccountValue = (state: HlClearinghouseState): Big =>
+  toWireBig(state.marginSummary.accountValue, 'marginSummary.accountValue')
 
 const getTotalMarginUsed = (state: HlClearinghouseState): number =>
   Number.parseFloat(state.marginSummary.totalMarginUsed)
@@ -81,10 +84,6 @@ const getMarginUsed = (
   return getTotalMarginUsed(mainState).toString()
 }
 
-const isUnifiedMode = (abstraction: HlAbstractionMode | null): boolean =>
-  abstraction === HlAbstractionMode.UNIFIED_ACCOUNT ||
-  abstraction === HlAbstractionMode.PORTFOLIO_MARGIN
-
 interface BalancePartition {
   balances: Balance[]
   collateralBalances: Balance[]
@@ -110,17 +109,20 @@ const buildBalances = (
   // double-count. Only disabled/dexAbstraction carry separate venue collateral.
   // `accountValue` is the dex's TOTAL equity: locked margin and unrealized
   // PnL are already included, so summaries must not add them on top.
-  if (!isUnifiedMode(abstraction)) {
+  if (!isUnifiedAbstraction(abstraction)) {
     for (const [dex, state] of stateByDex) {
       const categoryId = dex || PROVIDER_KEY
       const value = getAccountValue(state)
+      if (!value.gt(0)) {
+        continue
+      }
       collateralBalances.push({
         categoryId,
         // Always present: every dex in `stateByDex` derives from `markets`,
         // which is what populates `quoteAssetByCategory`.
         asset: quoteAssetByCategory.get(categoryId)!,
-        units: value.toString(),
-        valueUsd: value.toString(),
+        units: value.toFixed(),
+        valueUsd: value.toFixed(),
       })
     }
   }

package/src/services/getPortfolioHistory.ts

@@ -0,0 +1,118 @@
+import { PerpsError, type SDKRequestOptions } from '@lifi/perps-sdk'
+import {
+  PerpsErrorCode,
+  type PortfolioHistoryPoint,
+  type PortfolioHistoryRange,
+  type PortfolioHistoryResponse,
+} from '@lifi/perps-types'
+import type { Address } from 'viem'
+import type { HyperliquidContext } from '../context.js'
+import type {
+  HlAbstractionMode,
+  HlPortfolio,
+  HlPortfolioPeriod,
+  HlPortfolioWindow,
+} from '../types/index.js'
+import { isUnifiedAbstraction } from '../utils/abstractionMode.js'
+import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+
+/** Parameters for {@link getPortfolioHistory}. @public */
+export interface GetPortfolioHistoryParams {
+  address: Address
+  range: PortfolioHistoryRange
+}
+
+const COMBINED_PERIOD_BY_RANGE: Record<
+  PortfolioHistoryRange,
+  HlPortfolioPeriod
+> = {
+  '24h': 'day',
+  '7d': 'week',
+  '30d': 'month',
+  all: 'allTime',
+}
+
+const PERP_PERIOD_BY_RANGE: Record<PortfolioHistoryRange, HlPortfolioPeriod> = {
+  '24h': 'perpDay',
+  '7d': 'perpWeek',
+  '30d': 'perpMonth',
+  all: 'perpAllTime',
+}
+
+/**
+ * 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,
+  period: HlPortfolioPeriod
+): PortfolioHistoryPoint[] => {
+  const pnlByTimestamp = new Map(window.pnlHistory)
+  let matched = 0
+  let cumulative = '0'
+  const points = window.accountValueHistory.map(([timestamp, accountValue]) => {
+    const sample = pnlByTimestamp.get(timestamp)
+    if (sample !== undefined) {
+      matched += 1
+      cumulative = sample
+    }
+    return { timestamp, accountValue, pnl: cumulative }
+  })
+  if (points.length > 0 && window.pnlHistory.length > 0 && matched === 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ThirdPartyError,
+      `Hyperliquid portfolio window '${period}' samples PnL on no ` +
+        'account-value timestamp.'
+    )
+  }
+  return points
+}
+
+/**
+ * Read the account's portfolio value and cumulative PnL for `params.range`
+ * from one `portfolio` info request. An account whose collateral lives
+ * per-dex reads the perps-only window; a unified or portfolio-margin account
+ * holds its collateral in spot, so it reads the combined window.
+ * @public
+ */
+export async function getPortfolioHistory(
+  ctx: HyperliquidContext,
+  params: GetPortfolioHistoryParams,
+  options?: SDKRequestOptions
+): Promise<PortfolioHistoryResponse> {
+  const { client, apiUrl } = ctx
+  const infoOpts = hlInfoOptions(client, options)
+  const [portfolio, abstraction] = await Promise.all([
+    infoRequest<HlPortfolio>(
+      apiUrl,
+      { type: 'portfolio', user: params.address },
+      infoOpts
+    ),
+    // "Never set abstraction" is a successful 200 `null` body, not an error —
+    // so a fetch failure must propagate, never be coerced to `null` (which
+    // would silently read the combined window for a perps-only account).
+    infoRequest<HlAbstractionMode | null>(
+      apiUrl,
+      { type: 'userAbstraction', user: params.address },
+      infoOpts
+    ),
+  ])
+  const period = isUnifiedAbstraction(abstraction)
+    ? COMBINED_PERIOD_BY_RANGE[params.range]
+    : PERP_PERIOD_BY_RANGE[params.range]
+  const window = portfolio.find(([key]) => key === period)?.[1]
+  if (window === undefined) {
+    throw new PerpsError(
+      PerpsErrorCode.ThirdPartyError,
+      `Hyperliquid portfolio response has no '${period}' window.`
+    )
+  }
+
+  return {
+    range: params.range,
+    points: joinWindow(window, period),
+    volume: window.vlm,
+    totalPnl: window.pnlHistory.at(-1)?.[1],
+  }
+}

package/src/types/index.ts

@@ -8,4 +8,5 @@ export * from './asset.js'
 export * from './fill.js'
 export * from './ledger.js'
 export * from './order.js'
+export * from './portfolio.js'
 export * from './ws.js'

package/src/types/portfolio.ts

@@ -0,0 +1,29 @@
+// `portfolio` info response shapes.
+
+/** `[Unix milliseconds, decimal string]` sample of one portfolio series. @public */
+export type HlPortfolioSample = [number, string]
+
+/**
+ * One window of the Hyperliquid `portfolio` info response. `vlm` is the
+ * traded volume in the window; `pnlHistory` is cumulative from its start.
+ * @public
+ */
+export type HlPortfolioWindow = {
+  accountValueHistory: HlPortfolioSample[]
+  pnlHistory: HlPortfolioSample[]
+  vlm: string
+}
+
+/** Hyperliquid `portfolio` window keys. @public */
+export type HlPortfolioPeriod =
+  | 'day'
+  | 'week'
+  | 'month'
+  | 'allTime'
+  | 'perpDay'
+  | 'perpWeek'
+  | 'perpMonth'
+  | 'perpAllTime'
+
+/** Hyperliquid `portfolio` info response: a list of `[period, window]` pairs. @public */
+export type HlPortfolio = [HlPortfolioPeriod, HlPortfolioWindow][]

package/src/utils/abstractionMode.ts

@@ -0,0 +1,12 @@
+import { HlAbstractionMode } from '../types/account.js'
+
+/**
+ * Whether the mode holds the account's collateral in spot. Unified and
+ * portfolio-margin accounts do; every other mode keeps perps collateral
+ * per-dex, apart from the spot balances.
+ */
+export const isUnifiedAbstraction = (
+  abstraction: HlAbstractionMode | null
+): boolean =>
+  abstraction === HlAbstractionMode.UNIFIED_ACCOUNT ||
+  abstraction === HlAbstractionMode.PORTFOLIO_MARGIN

package/src/utils/decimal.ts

@@ -0,0 +1,21 @@
+import { PerpsError } from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import Big from 'big.js'
+
+/**
+ * Exact-decimal parse of a Hyperliquid wire decimal string. `field` names the
+ * offending field on failure, so a venue contract breach is diagnosable
+ * instead of surfacing as an anonymous big.js throw or an `NaN` unit.
+ *
+ * @throws {PerpsError} `SDKError` when `value` is not a decimal numeric string.
+ */
+export const toWireBig = (value: string, field: string): Big => {
+  try {
+    return new Big(value)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Hyperliquid field \`${field}\` is not a valid decimal: '${value}'`
+    )
+  }
+}

package/src/utils/mapMarketContext.ts

@@ -1,30 +1,55 @@
 import type { MarketContext } from '@lifi/perps-types'
-import type { HlWsPerpAssetCtx } from '../types/index.js'
+import Big from 'big.js'
+import type { HlWsFastAssetCtx, HlWsPerpAssetCtx } from '../types/index.js'
 
 const NEXT_FUNDING_INTERVAL_MS = 60 * 60 * 1000 // 1 hour
 
+/**
+ * Convert venue base-unit open interest to a quote-asset notional. A mark that
+ * is not a positive number leaves the notional unknown rather than zero.
+ */
+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 {
+    return undefined
+  }
+}
+
 /**
  * Map a Hyperliquid perp asset context from the `allDexsAssetCtxs` feed to a
- * {@link MarketContext}. `midPx` is null when the book is empty; mid then falls
- * back to the mark so the context always carries a usable mid.
+ * {@link MarketContext}, with mid and mark overlaid from a `fastAssetCtxs`
+ * context where one is given. `midPx` is null when the book is empty; mid then
+ * falls back to the mark so the context always carries a usable mid. The
+ * open-interest notional follows the emitted mark, so it never mixes the two
+ * feeds' prices.
  * @public
  */
 export const mapMarketContext = (
   marketId: string,
-  ctx: HlWsPerpAssetCtx
+  ctx: HlWsPerpAssetCtx,
+  fast?: HlWsFastAssetCtx
 ): MarketContext => {
   const now = Date.now()
   const nextFundingTime =
     Math.ceil(now / NEXT_FUNDING_INTERVAL_MS) * NEXT_FUNDING_INTERVAL_MS
+  const markPrice = fast?.markPx != null ? fast.markPx : ctx.markPx
 
   return {
     marketId,
-    midPrice: ctx.midPx ?? ctx.markPx,
-    markPrice: ctx.markPx,
+    midPrice: fast?.midPx != null ? fast.midPx : (ctx.midPx ?? ctx.markPx),
+    markPrice,
     oraclePrice: ctx.oraclePx,
     prevDayPrice: ctx.prevDayPx,
     volume24h: ctx.dayNtlVlm,
-    openInterest: ctx.openInterest,
+    openInterest: toOpenInterestNotional(ctx.openInterest, markPrice),
     funding: {
       rate: ctx.funding,
       nextFundingTime,

package/src/utils/spotCollateral.ts

@@ -1,4 +1,5 @@
 import type { Balance } from '@lifi/perps-types'
+import { toWireBig } from './decimal.js'
 
 /**
  * Portfolio-margin collateral beyond the category quote assets, keyed by spot
@@ -37,6 +38,9 @@ export const partitionSpotBalances = (
   const collateralBalances: Balance[] = []
   const balances: Balance[] = []
   for (const balance of spotBalances) {
+    if (!toWireBig(balance.units, 'spotBalance.units').gt(0)) {
+      continue
+    }
     if (quoteAssetIds.has(balance.asset.id)) {
       collateralBalances.push(balance)
       continue

package/src/websocket/HyperliquidWsProvider.ts

@@ -13,6 +13,7 @@ import {
   toPerpsMarketDisplay,
   WsProviderBase,
   type WsProviderFactory,
+  type WsProviderFactoryParams,
   type WsStatusListener,
   wsLog,
 } from '@lifi/perps-sdk'
@@ -58,6 +59,7 @@ import type {
   HlWsUserFillsData,
 } from '../types/index.js'
 import { HlAbstractionMode } from '../types/index.js'
+import { toWireBig } from '../utils/decimal.js'
 import {
   decodeCompressedJson,
   decodeFastAssetCtxs,
@@ -94,13 +96,15 @@ const normalizeHlAddress = (address: string): string =>
  *
  * @public
  */
-export const hyperliquidWsProvider =
-  (): WsProviderFactory =>
-  ({ provider, wsUrl, client }) =>
-    new HyperliquidWsProvider(wsUrl, provider, client)
+export const hyperliquidWsProvider = (): WsProviderFactory =>
+  Object.assign(
+    ({ provider, wsUrl, client }: WsProviderFactoryParams) =>
+      new HyperliquidWsProvider(wsUrl, provider, client),
+    { streamsCandles: true }
+  )
 
 /**
- * Hyperliquid realtime {@link WsProvider}: multiplexes markets context,
+ * Hyperliquid WebSocket {@link WsProvider}: multiplexes markets context,
  * positions, orders, fills and spot balances over a single
  * {@link ReconnectingWebSocket}.
  * Construct via {@link hyperliquidWsProvider}.
@@ -786,12 +790,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       perpCtx = byMarketId[marketId] ?? perpCtx
     }
     if (perpCtx !== undefined) {
-      const base = mapMarketContext(marketId, perpCtx)
-      return {
-        ...base,
-        midPrice: fast?.midPx != null ? fast.midPx : base.midPrice,
-        markPrice: fast?.markPx != null ? fast.markPx : base.markPrice,
-      }
+      return mapMarketContext(marketId, perpCtx, fast)
     }
     const midPrice = fast?.midPx ?? fast?.markPx
     const markPrice = fast?.markPx ?? fast?.midPx
@@ -1254,10 +1253,18 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     const user = data.user.toLowerCase()
     const markets = this.registry?.activeMarkets ?? []
     const priceById = spotPriceById(markets, this.mergedMids())
-    const rows = data.spotState.balances.map((b) => ({
-      balance: spotBalance(spotAssetFromToken(b), b.total, priceById),
-      hold: b.hold,
-    }))
+    const rows = data.spotState.balances
+      .filter((balance) =>
+        toWireBig(balance.total, 'spotState.balances.total').gt(0)
+      )
+      .map((balance) => ({
+        balance: spotBalance(
+          spotAssetFromToken(balance),
+          balance.total,
+          priceById
+        ),
+        hold: balance.hold,
+      }))
     this.emit(`spotState:${user}`, {
       channel: 'spotBalances',
       data: rows.map(({ balance, hold }) => ({ ...balance, locked: hold })),