@lifi/perps-sdk-provider-hyperliquid 15.0.0 → 16.0.0

package/src/services/getAvailableToTrade.ts

@@ -0,0 +1,72 @@
+import {
+  getMarketRegistry,
+  PerpsError,
+  type SDKRequestOptions,
+  toAssetDisplay,
+} from '@lifi/perps-sdk'
+import type { AvailableToTrade } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { PROVIDER_KEY, SPOT_MARKET_ID } from '../constants.js'
+import type { HyperliquidContext } from '../context.js'
+import { fetchActiveAssetData } from './activeAssetData.js'
+
+/**
+ * Parameters for {@link getAvailableToTrade}.
+ *
+ * @public
+ */
+export interface GetAvailableToTradeParams {
+  address: Address
+  marketId: string
+}
+
+/**
+ * The amounts the account can still buy and sell on one perps market, read
+ * from `activeAssetData`. The amounts are denominated in the market's margin
+ * asset: USDC on the main dex, and the dex margin asset on a builder-deployed
+ * dex. Resolves `undefined` for a spot market, which carries no such state.
+ *
+ * @throws {PerpsError} On an unknown market, an `availableToTrade` payload
+ *   that is not a buy/sell pair, Hyperliquid REST error, network, or parsing
+ *   failures.
+ * @public
+ */
+export const getAvailableToTrade = async (
+  context: HyperliquidContext,
+  params: GetAvailableToTradeParams,
+  options?: SDKRequestOptions
+): Promise<AvailableToTrade | undefined> => {
+  const registry = getMarketRegistry(context.client, PROVIDER_KEY)
+  await registry.sync()
+  const market = registry.require(params.marketId)
+  if (market.categoryId === SPOT_MARKET_ID) {
+    return undefined
+  }
+  const data = await fetchActiveAssetData(
+    context,
+    params.address,
+    params.marketId,
+    options
+  )
+  // The wire type states the pair; nothing verifies the response, so read it
+  // as a plain list to keep the length check in reach of the type checker.
+  const amounts: readonly string[] = data.availableToTrade
+  if (amounts.length !== 2) {
+    const err = new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Hyperliquid returned ${amounts.length} availableToTrade amounts for market '${params.marketId}'. Expected a buy amount and a sell amount.`
+    )
+    err.tool = PROVIDER_KEY
+    throw err
+  }
+  // Hyperliquid orders the pair buy-side first, sell-side second.
+  const [buy, sell] = amounts
+  return {
+    providerId: market.providerId,
+    marketId: market.id,
+    asset: toAssetDisplay(market.quoteAsset),
+    buy,
+    sell,
+  }
+}

package/src/services/getMarketSettings.ts

@@ -7,8 +7,7 @@ import {
 import type { Address } from 'viem'
 import { SPOT_MARKET_ID } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
-import type { HlActiveAssetData } from '../types/index.js'
-import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+import { fetchActiveAssetData } from './activeAssetData.js'
 
 /**
  * Parameters for {@link getMarketSettings}.
@@ -27,7 +26,7 @@ export interface GetMarketSettingsParams {
  * @public
  */
 export const getMarketSettings = async (
-  { client, apiUrl }: HyperliquidContext,
+  context: HyperliquidContext,
   params: GetMarketSettingsParams,
   options?: SDKRequestOptions
 ): Promise<MarketSettings | undefined> => {
@@ -35,14 +34,11 @@ export const getMarketSettings = async (
   if (params.market.categoryId === SPOT_MARKET_ID) {
     return undefined
   }
-  const data = await infoRequest<HlActiveAssetData>(
-    apiUrl,
-    {
-      type: 'activeAssetData',
-      user: params.address,
-      coin: params.market.marketId,
-    },
-    hlInfoOptions(client, options)
+  const data = await fetchActiveAssetData(
+    context,
+    params.address,
+    params.market.marketId,
+    options
   )
   const leverage = data.leverage
   if (!leverage) {

package/src/services/getWithdrawableBalances.ts

@@ -0,0 +1,84 @@
+import {
+  getMarketRegistry,
+  PerpsError,
+  type ProviderGetWithdrawableBalancesParams,
+  type ProviderWithdrawableBalance,
+  type SDKRequestOptions,
+} from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { MAIN_MARKET_ID, PROVIDER_KEY } from '../constants.js'
+import type { HyperliquidContext } from '../context.js'
+import type {
+  HlAbstractionMode,
+  HlClearinghouseState,
+  HlSpotClearinghouseState,
+} from '../types/index.js'
+import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+import { hyperliquidWithdrawableBalances } from '../utils/withdrawableBalances.js'
+
+/**
+ * Parameters for {@link getWithdrawableBalances}.
+ *
+ * @public
+ */
+export type GetWithdrawableBalancesParams =
+  ProviderGetWithdrawableBalancesParams
+
+/**
+ * The `(asset, route)` pairs `params.address` can withdraw from Hyperliquid,
+ * read from the venue's own `withdrawable` and spot `total`/`hold` figures.
+ *
+ * Only the main perps dex is read: a withdrawal to L1 draws on that account,
+ * and a sub-dex balance reaches it through a transfer first.
+ *
+ * @throws {PerpsError} On Hyperliquid REST error, network, or parsing
+ * failures, and `SDKError` when the market registry carries no main perps
+ * market to name the quote asset.
+ * @public
+ */
+export const getWithdrawableBalances = async (
+  { client, apiUrl }: HyperliquidContext,
+  params: GetWithdrawableBalancesParams,
+  options?: SDKRequestOptions
+): Promise<ProviderWithdrawableBalance[]> => {
+  const registry = getMarketRegistry(client, PROVIDER_KEY)
+  const infoOpts = hlInfoOptions(client, options)
+
+  const [markets, abstraction, state, spotState] = await Promise.all([
+    registry.sync(),
+    infoRequest<HlAbstractionMode | null>(
+      apiUrl,
+      { type: 'userAbstraction', user: params.address },
+      infoOpts
+    ),
+    infoRequest<HlClearinghouseState>(
+      apiUrl,
+      { type: 'clearinghouseState', user: params.address },
+      infoOpts
+    ),
+    infoRequest<HlSpotClearinghouseState>(
+      apiUrl,
+      { type: 'spotClearinghouseState', user: params.address },
+      infoOpts
+    ),
+  ])
+
+  const quoteAsset = markets.find(
+    (market) => market.categoryId === MAIN_MARKET_ID
+  )?.quoteAsset
+  if (quoteAsset === undefined) {
+    const error = new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Hyperliquid market registry carries no '${MAIN_MARKET_ID}' market to name the withdrawal quote asset`
+    )
+    error.tool = PROVIDER_KEY
+    throw error
+  }
+
+  return hyperliquidWithdrawableBalances(
+    abstraction,
+    state,
+    spotState,
+    quoteAsset.id
+  )
+}

package/src/types/account.ts

@@ -51,6 +51,19 @@ export type HlAssetPosition = {
   position: HlPosition
 }
 
+/**
+ * Margin totals block of a Hyperliquid clearinghouse state. Monetary fields
+ * are decimal strings in the account's quote asset.
+ * @public
+ */
+export type HlMarginSummary = {
+  /** Total equity: locked margin and unrealized PnL included. */
+  accountValue: string
+  totalNtlPos: string
+  totalRawUsd: string
+  totalMarginUsed: string
+}
+
 /**
  * Perpetual clearinghouse account state returned by Hyperliquid `/info`.
  * `assetPositions` includes zero-size rows that callers may discard. Monetary
@@ -60,14 +73,10 @@ export type HlAssetPosition = {
  */
 export type HlClearinghouseState = {
   assetPositions: HlAssetPosition[]
-  marginSummary: {
-    accountValue: string
-    totalMarginUsed: string
-  }
-  crossMarginSummary: {
-    accountValue: string
-    totalMarginUsed: string
-  }
+  marginSummary: HlMarginSummary
+  crossMarginSummary: HlMarginSummary
+  crossMaintenanceMarginUsed: string
+  withdrawable: string
 }
 
 /**
@@ -90,6 +99,11 @@ export type HlSpotBalance = {
  */
 export type HlSpotClearinghouseState = {
   balances: HlSpotBalance[]
+  /**
+   * Venue buying power per spot token, as `[token index, amount]` pairs.
+   * The venue reports the amount after maintenance margin.
+   */
+  tokenToAvailableAfterMaintenance: [number, string][]
 }
 
 /**

package/src/types/ws.ts

@@ -184,6 +184,18 @@ export type HlWsUserFillsData = {
   fills: HlUserFill[]
 }
 
+/**
+ * One sub-dex slice of an `allDexsClearinghouseState` frame. `marginSummary`
+ * is absent on a frame that reports positions only, so a reader must treat it
+ * as optional.
+ * @public
+ */
+export type HlWsDexClearinghouseState = Pick<
+  HlClearinghouseState,
+  'assetPositions'
+> &
+  Partial<Pick<HlClearinghouseState, 'marginSummary'>>
+
 /**
  * Per-dex clearinghouse event for one user. Each tuple contains a wire DEX name
  * and the perp positions/equity fields supplied by that DEX.
@@ -191,14 +203,15 @@ export type HlWsUserFillsData = {
  */
 export type HlWsAllDexsClearinghouseStateData = {
   user: string
-  clearinghouseStates: [
-    string,
-    Pick<HlClearinghouseState, 'assetPositions' | 'marginSummary'>,
-  ][]
+  clearinghouseStates: [string, HlWsDexClearinghouseState][]
 }
 
 /** User spot clearinghouse event containing the current spot balances. @public */
 export type HlWsSpotStateData = {
   user: string
-  spotState: { balances: HlSpotBalance[] }
+  spotState: {
+    balances: HlSpotBalance[]
+    /** Absent on some frames; the REST `spotClearinghouseState` read covers it. */
+    tokenToAvailableAfterMaintenance?: [number, string][]
+  }
 }

package/src/utils/abstractionMode.ts

@@ -6,7 +6,7 @@ import { HlAbstractionMode } from '../types/account.js'
  * per-dex, apart from the spot balances.
  */
 export const isUnifiedAbstraction = (
-  abstraction: HlAbstractionMode | null
+  abstraction: HlAbstractionMode | string | null
 ): boolean =>
   abstraction === HlAbstractionMode.UNIFIED_ACCOUNT ||
   abstraction === HlAbstractionMode.PORTFOLIO_MARGIN

package/src/utils/index.ts

@@ -57,3 +57,9 @@ export {
 } from './spotBalance.js'
 export { partitionSpotBalances, type SpotPartition } from './spotCollateral.js'
 export { positionMarginConstraints } from './transferMargin.js'
+export {
+  type DexMarginSummary,
+  perpsTotals,
+  sumUnrealizedPnl,
+} from './venueTotals.js'
+export { hyperliquidWithdrawableBalances } from './withdrawableBalances.js'

package/src/utils/mapPosition.ts

@@ -30,10 +30,6 @@ export const mapPosition = (
   const leverage = new Big(pos.leverage.value)
   const marginMode =
     pos.leverage.type === 'cross' ? MarginMode.CROSS : MarginMode.ISOLATED
-  const marginUsed =
-    marginMode === MarginMode.ISOLATED
-      ? new Big(pos.marginUsed).minus(pos.unrealizedPnl).toFixed()
-      : pos.marginUsed
 
   return {
     market,
@@ -45,7 +41,7 @@ export const mapPosition = (
     unrealizedPnl: pos.unrealizedPnl,
     accruedFunding: new Big(pos.cumFunding.sinceOpen).neg().toFixed(),
     leverage: ap.position.leverage.value,
-    marginUsed,
+    marginUsed: pos.marginUsed,
     initialMarginRequirement: positionValue.div(leverage).toFixed(),
     marginMode,
   }

package/src/utils/spotCollateral.ts

@@ -1,19 +1,6 @@
 import type { Balance } from '@lifi/perps-types'
 import { toWireBig } from './decimal.js'
 
-/**
- * Portfolio-margin collateral beyond the category quote assets, keyed by spot
- * display symbol with its loan-to-value weight. Hyperliquid credits these
- * toward buying power at the given fraction (0.5 for both today). Quote assets
- * (USDC/USDT) are already full-value collateral via the category model, so
- * they are not listed here.
- * https://hyperliquid.gitbook.io/hyperliquid-docs/trading/portfolio-margin
- */
-const PORTFOLIO_MARGIN_LTV: Readonly<Record<string, number>> = {
-  HYPE: 0.5,
-  UBTC: 0.5,
-}
-
 /**
  * Result of {@link partitionSpotBalances}: balances that count toward
  * collateral and balances treated as ordinary holdings.
@@ -25,15 +12,14 @@ export interface SpotPartition {
 }
 
 /**
- * Partition spot balances into collateral and ordinary holdings. Quote assets
- * are full-value collateral; portfolio-margin-supported assets retain their
- * LTV as `collateralWeight`.
+ * Partition spot balances into collateral and ordinary holdings. Category
+ * quote assets are collateral; every other token is an ordinary holding.
+ * Zero-unit rows are dropped from both lists.
  * @public
  */
 export const partitionSpotBalances = (
   spotBalances: readonly Balance[],
-  quoteAssetIds: ReadonlySet<string>,
-  portfolioMargin: boolean
+  quoteAssetIds: ReadonlySet<string>
 ): SpotPartition => {
   const collateralBalances: Balance[] = []
   const balances: Balance[] = []
@@ -43,13 +29,6 @@ export const partitionSpotBalances = (
     }
     if (quoteAssetIds.has(balance.asset.id)) {
       collateralBalances.push(balance)
-      continue
-    }
-    const ltv = portfolioMargin
-      ? PORTFOLIO_MARGIN_LTV[balance.asset.displaySymbol]
-      : undefined
-    if (ltv !== undefined) {
-      collateralBalances.push({ ...balance, collateralWeight: ltv })
     } else {
       balances.push(balance)
     }

package/src/utils/venueTotals.ts

@@ -0,0 +1,48 @@
+import type { HyperliquidMarginSummary, Position } from '@lifi/perps-types'
+import Big from 'big.js'
+import { toWireBig } from './decimal.js'
+
+/**
+ * One perps sub-dex entry {@link perpsTotals} reads. The REST response always
+ * carries `marginSummary`; a WebSocket frame may omit it.
+ * @public
+ */
+export interface DexMarginSummary {
+  marginSummary?: HyperliquidMarginSummary
+}
+
+/**
+ * Sum the venue `marginSummary` totals over every perps sub-dex of an
+ * account. `accountValue` is total equity, so it already carries locked
+ * margin and unrealized PnL. An entry without a `marginSummary` adds nothing.
+ * @public
+ */
+export const perpsTotals = (
+  dexStates: readonly DexMarginSummary[]
+): { accountValue: Big; marginUsed: Big } => {
+  let accountValue = new Big(0)
+  let marginUsed = new Big(0)
+  for (const { marginSummary } of dexStates) {
+    if (marginSummary === undefined) {
+      continue
+    }
+    accountValue = accountValue.plus(
+      toWireBig(marginSummary.accountValue, 'marginSummary.accountValue')
+    )
+    marginUsed = marginUsed.plus(
+      toWireBig(marginSummary.totalMarginUsed, 'marginSummary.totalMarginUsed')
+    )
+  }
+  return { accountValue, marginUsed }
+}
+
+/**
+ * Sum the unrealized PnL of every position, in quote-asset units.
+ * @public
+ */
+export const sumUnrealizedPnl = (positions: readonly Position[]): Big =>
+  positions.reduce(
+    (sum, position) =>
+      sum.plus(toWireBig(position.unrealizedPnl, 'position.unrealizedPnl')),
+    new Big(0)
+  )

package/src/utils/withdrawableBalances.ts

@@ -0,0 +1,57 @@
+import type { ProviderWithdrawableBalance } from '@lifi/perps-sdk'
+import type {
+  HlAbstractionMode,
+  HlClearinghouseState,
+  HlSpotClearinghouseState,
+} from '../types/index.js'
+import { isUnifiedAbstraction } from './abstractionMode.js'
+import { assetIsOutcome } from './assetId.js'
+import { toWireBig } from './decimal.js'
+
+/**
+ * Split a Hyperliquid account's venue figures into the routes a withdrawal
+ * draws on. A unified or portfolio-margin account holds its collateral in spot,
+ * so each spot token adds the part of `total` that no order or margin holds. A
+ * route with nothing left to draw carries no row, and the caller applies the
+ * per-asset venue minimum.
+ *
+ * @param quoteAssetId - `Asset.id` the perps-route row is keyed by.
+ * @public
+ */
+export const hyperliquidWithdrawableBalances = (
+  abstraction: HlAbstractionMode | null,
+  state: HlClearinghouseState,
+  spotState: HlSpotClearinghouseState,
+  quoteAssetId: string
+): ProviderWithdrawableBalance[] => {
+  const rows: ProviderWithdrawableBalance[] = []
+
+  if (isUnifiedAbstraction(abstraction)) {
+    for (const balance of spotState.balances) {
+      if (assetIsOutcome(balance.coin)) {
+        continue
+      }
+      const spot = toWireBig(balance.total, 'spotBalance.total').minus(
+        toWireBig(balance.hold, 'spotBalance.hold')
+      )
+      if (spot.gt(0)) {
+        rows.push({
+          assetId: String(balance.token),
+          route: 'spot',
+          available: spot.toFixed(),
+        })
+      }
+    }
+  }
+
+  const perps = toWireBig(state.withdrawable, 'clearinghouseState.withdrawable')
+  if (perps.gt(0)) {
+    rows.push({
+      assetId: quoteAssetId,
+      route: 'perps',
+      available: perps.toFixed(),
+    })
+  }
+
+  return rows
+}