@lifi/perps-sdk-provider-hyperliquid 5.1.0 → 6.0.1

package/src/types/ledger.ts

@@ -50,7 +50,11 @@ export type HlSendAssetDelta = {
   feeToken: string
 }
 
-/** @public */
+/**
+ * Union of known Hyperliquid non-funding ledger deltas plus an open fallback
+ * for endpoint variants the provider does not map.
+ * @public
+ */
 export type HlLedgerDelta =
   | HlSpotTransferDelta
   | HlSendAssetDelta
@@ -81,17 +85,26 @@ export const isSendAssetDelta = (
   delta: HlLedgerDelta
 ): delta is HlSendAssetDelta => delta.type === 'send'
 
-/** @public */
+/**
+ * One timestamped non-funding ledger update. `time` is milliseconds since
+ * epoch and `hash` is the upstream transaction identifier.
+ * @public
+ */
 export type HlLedgerUpdate = {
   time: number
   hash: string
   delta: HlLedgerDelta
 }
 
-/** @public */
+/** Array returned by `userNonFundingLedgerUpdates`. @public */
 export type HlUserNonFundingLedgerUpdates = HlLedgerUpdate[]
 
-/** @public */
+/**
+ * Funding ledger delta returned by Hyperliquid `userFunding`. `usdc` is the
+ * funding payment, `szi` is signed position size, and `fundingRate` is a
+ * decimal fraction; all are decimal strings.
+ * @public
+ */
 export type HlFundingDelta = {
   type: 'funding'
   coin: string
@@ -100,12 +113,17 @@ export type HlFundingDelta = {
   fundingRate: string
 }
 
-/** @public */
+/**
+ * Timestamped funding update. `time` is milliseconds since epoch; `hash` is
+ * always the zero hash — funding is a system ledger event with no venue
+ * transaction behind it.
+ * @public
+ */
 export type HlFundingUpdate = {
   time: number
   hash: string
   delta: HlFundingDelta
 }
 
-/** @public */
+/** Array returned by the `userFunding` info query. @public */
 export type HlUserFunding = HlFundingUpdate[]

package/src/types/order.ts

@@ -1,6 +1,11 @@
 // Order shapes returned by Hyperliquid `/info`.
 
-/** @public */
+/**
+ * Open order payload returned by Hyperliquid `frontendOpenOrders`.
+ * Sizes/prices are decimal strings; timestamps are milliseconds. Trigger
+ * flags and optional `children` describe attached TP/SL orders.
+ * @public
+ */
 export type HlFrontendOpenOrder = {
   oid: number
   coin: string
@@ -20,10 +25,15 @@ export type HlFrontendOpenOrder = {
   cloid: string | null
 }
 
-/** @public */
+/** Array returned by the `frontendOpenOrders` info query. @public */
 export type HlFrontendOpenOrders = HlFrontendOpenOrder[]
 
-/** @public */
+/**
+ * Order detail nested in an `orderStatus` response. `statusTimestamp` is the
+ * last status-change time in milliseconds; `triggerPx` is nullable for orders
+ * without a trigger.
+ * @public
+ */
 export type HlOrderDetail = {
   order: {
     oid: number
@@ -44,13 +54,17 @@ export type HlOrderDetail = {
   statusTimestamp: number
 }
 
-/** @public */
+/** Successful `orderStatus` response containing the requested order. @public */
 export type HlOrderStatusFound = {
   status: 'order'
   order: HlOrderDetail
 }
 
-/** @public */
+/**
+ * Result of `orderStatus`: either a found order or the exact `'unknownOid'`
+ * sentinel when Hyperliquid has no record for the numeric order ID.
+ * @public
+ */
 export type HlOrderStatusResponse =
   | HlOrderStatusFound
   | { status: 'unknownOid' }

package/src/types/ws.ts

@@ -23,7 +23,11 @@ export type HlWsPerpAssetCtx = {
   oraclePx: string
 }
 
-/** @public */
+/**
+ * Partial perp context carried by compressed (`pac`) updates. Omitted fields
+ * are unchanged from the prior context and must be merged by the consumer.
+ * @public
+ */
 export type HlWsPerpAssetCtxPayload = Partial<HlWsPerpAssetCtx>
 
 /**
@@ -44,7 +48,7 @@ export type HlWsAllDexsAssetCtxsData = {
  */
 export type HlWsPacData = [string, HlWsPerpAssetCtxPayload[]][]
 
-/** @public */
+/** Generic Hyperliquid WS envelope; `channel` identifies the subscription and `data` is channel-specific. @public */
 export type HlWsMessage = {
   channel: string
   data: unknown
@@ -61,7 +65,12 @@ export type HlWsFastAssetCtx = {
   midPx?: string | null
 }
 
-/** @public */
+/**
+ * Incremental spot asset context. Hyperliquid may encode numeric fields as
+ * strings or numbers and omits unchanged fields; `midPx: null` means no book
+ * midpoint is available.
+ * @public
+ */
 export type HlWsSpotAssetCtx = {
   dayNtlVlm?: HlWsNumberString
   prevDayPx?: HlWsNumberString
@@ -71,13 +80,13 @@ export type HlWsSpotAssetCtx = {
   circulatingSupply?: HlWsNumberString
 }
 
-/** @public */
+/** Active perp context event keyed by its Hyperliquid wire coin. @public */
 export type HlWsActiveAssetCtxData = {
   coin: string
   ctx: Partial<Record<keyof HlWsPerpAssetCtx, HlWsNumberString | null>>
 }
 
-/** @public */
+/** Active spot context event keyed by its Hyperliquid wire coin. @public */
 export type HlWsActiveSpotAssetCtxData = {
   coin: string
   ctx: HlWsSpotAssetCtx
@@ -90,23 +99,31 @@ export type HlWsActiveSpotAssetCtxData = {
  */
 export type HlWsSacData = Record<string, HlWsSpotAssetCtx>
 
-/** @public */
+/** L2 snapshot envelope with the wire coin attached to {@link HlL2Book}. @public */
 export type HlWsL2BookData = HlL2Book & { coin: string }
 
-/** @public */
+/**
+ * L2 channel payload. `s` is a full snapshot, while `u` is a compressed delta;
+ * `c` carries the checksum/control value when present.
+ * @public
+ */
 export type HlWsL2Data = {
   s?: HlL2Book & { coin: string }
   c?: string
   u?: HlWsCompressedL2Data
 }
 
-/** @public */
+/** One level in a compressed L2 update: `p` is price and `s` is size. @public */
 export type HlWsCompressedL2Level = {
   p: string
   s: string
 }
 
-/** @public */
+/**
+ * Compressed L2 delta. `t` is the update timestamp in milliseconds, `l` holds
+ * bid/ask levels, and optional `r` describes removals.
+ * @public
+ */
 export type HlWsCompressedL2Data = {
   c: string
   t: number
@@ -117,7 +134,11 @@ export type HlWsCompressedL2Data = {
   ]
 }
 
-/** @public */
+/**
+ * Candle event payload. Inherited `t` is candle-open time; `T` is close time,
+ * `s` is the symbol, `i` is interval, and `n` is the trade count.
+ * @public
+ */
 export type HlWsCandleData = HlCandle & {
   T: number
   s: string
@@ -125,7 +146,11 @@ export type HlWsCandleData = HlCandle & {
   n: number
 }
 
-/** @public */
+/**
+ * Public trade event. Prices and size are decimal strings; `time` is
+ * milliseconds since epoch, with optional trade ID and transaction hash.
+ * @public
+ */
 export type HlWsTrade = {
   coin: string
   side: string
@@ -136,14 +161,18 @@ export type HlWsTrade = {
   hash?: string
 }
 
-/** @public */
+/** User fills event; `isSnapshot` distinguishes the initial snapshot from updates. @public */
 export type HlWsUserFillsData = {
   isSnapshot: boolean
   user: string
   fills: HlUserFill[]
 }
 
-/** @public */
+/**
+ * Per-dex clearinghouse event for one user. Each tuple contains a wire DEX name
+ * and the perp positions/equity fields supplied by that DEX.
+ * @public
+ */
 export type HlWsAllDexsClearinghouseStateData = {
   user: string
   clearinghouseStates: [
@@ -152,7 +181,7 @@ export type HlWsAllDexsClearinghouseStateData = {
   ][]
 }
 
-/** @public */
+/** User spot clearinghouse event containing the current spot balances. @public */
 export type HlWsSpotStateData = {
   user: string
   spotState: { balances: HlSpotBalance[] }

package/src/utils/assetId.ts

@@ -1,15 +1,14 @@
 /**
- * Spot asset IDs use the @pairIndex format (e.g. "@230").
- *
+ * Return whether a Hyperliquid asset ID identifies spot (`@<pairIndex>`).
+ * @param assetId - Raw Hyperliquid asset ID.
  * @public
  */
 export const assetIsSpot = (assetId: string): boolean => assetId.startsWith('@')
 
 /**
- * Calculate the asset ID for a given provider index and asset index.
- *
- * Main provider (provider = ''): assetId = indexInProvider
- * HIP-3 providers (provider = 'xyz'): assetId = 100_000 + perpDexIndex * 10_000 + indexInProvider
+ * Calculate Hyperliquid's numeric asset ID from a perp DEX index and the
+ * asset's zero-based index within that DEX. The main DEX uses the index
+ * directly; HIP-3 DEXes use `100000 + dexIndex * 10000 + assetIndex`.
  * @public
  */
 export const calculateAssetId = (
@@ -23,7 +22,8 @@ export const calculateAssetId = (
 }
 
 /**
- * Get the provider index from the given list of provider names.
+ * Find a sub-DEX's zero-based index in the names returned by Hyperliquid.
+ * @throws If `provider` is absent from `providerNames`.
  * @public
  */
 export const getProviderIndex = (

package/src/utils/assetLogo.ts

@@ -47,7 +47,12 @@ const UNIT_UNDERLYING_SYMBOL: Readonly<Record<string, string>> = {
   UANSEM: 'ANSEM',
 }
 
-/** Token `name`s of the Unit-bridged HL spot assets. */
+/**
+ * Names of Unit-bridged Hyperliquid spot tokens recognized by the logo
+ * resolver. The set is read-only and is intended for callers that need to
+ * distinguish Unit balances before resolving their icons.
+ * @public
+ */
 export const UNIT_TOKEN_NAMES: ReadonlySet<string> = new Set(
   Object.keys(UNIT_UNDERLYING_SYMBOL)
 )
@@ -58,24 +63,21 @@ const unitSpotLogoURI = (name: string): string => {
   return underlying === undefined ? '' : `${HL_COIN_CDN}/${underlying}.svg`
 }
 
-/** Return `asset` with its `logoURI` replaced when a display-symbol override exists. */
+/**
+ * Apply the provider's known symbol-specific logo corrections to an asset.
+ * Returns the original object when no override exists.
+ * @public
+ */
 export const applyLogoOverride = (asset: Asset): Asset => {
   const override = BASE_ASSET_LOGO_OVERRIDES[asset.displaySymbol]
   return override === undefined ? asset : { ...asset, logoURI: override }
 }
 
 /**
- * Override-aware logo URI for a Hyperliquid spot token. Base rule is
- * `coins/${name}_spot.svg`; a Unit-bridged token (`fullName` starts with
- * "Unit") resolves to its underlying's icon instead; the override table wins
- * over both.
- *
- * When `fullName` is absent — spot *balances* (`HlSpotBalance`) carry no
- * `fullName` and this issue deliberately does not fetch `spotMeta` on the
- * account path — the derivation degrades to the symbol-keyed override + base
- * `_spot` rule, so a Unit-bridged balance uses the base rule rather than its
- * underlying's icon. The registry path (which has `fullName`) keeps full Unit
- * resolution.
+ * Resolve the logo URI for a Hyperliquid spot token. Unit-bridged tokens use
+ * the underlying symbol's icon when `fullName` starts with `'Unit'`; otherwise
+ * the base URI is `coins/${name}_spot.svg`. Known symbol overrides win.
+ * @public
  */
 export const spotLogoURI = (name: string, fullName?: string | null): string => {
   const base = fullName?.startsWith('Unit')

package/src/utils/decodeFastAssetCtxs.ts

@@ -1,6 +1,11 @@
 import type { HlWsFastAssetCtx } from '../types/index.js'
 
-/** Decode a base64 + raw-DEFLATE (RFC 1951) payload into parsed JSON. */
+/**
+ * Decode a base64-encoded raw-DEFLATE payload and parse its UTF-8 JSON body.
+ * @typeParam T - Expected shape of the decoded JSON value.
+ * @throws If decompression or JSON parsing fails.
+ * @public
+ */
 export async function decodeCompressedJson<T>(base64: string): Promise<T> {
   const binary = atob(base64)
   const bytes = new Uint8Array(binary.length)
@@ -24,6 +29,7 @@ export async function decodeCompressedJson<T>(base64: string): Promise<T> {
  * (Node 18+, modern browsers), so no dependency is needed.
  *
  * @throws If the input is not valid base64 / raw-DEFLATE / JSON.
+ * @public
  */
 export async function decodeFastAssetCtxs(
   base64: string

package/src/utils/index.ts

@@ -46,3 +46,4 @@ export {
   spotPriceById,
 } from './spotBalance.js'
 export { partitionSpotBalances, type SpotPartition } from './spotCollateral.js'
+export { positionMarginConstraints } from './transferMargin.js'

package/src/utils/infoClient.ts

@@ -50,7 +50,12 @@ export const HYPERLIQUID_RETRY_DEFAULTS: ResolvedRetryPolicy = {
   },
 }
 
-/** @public */
+/**
+ * Transport options for a direct Hyperliquid `/info` request. `policy`
+ * controls retries, `signal` cancels the request, and `fetchImpl` overrides
+ * the runtime's global `fetch` implementation.
+ * @public
+ */
 export interface InfoRequestOptions {
   signal?: AbortSignal
   policy?: ResolvedRetryPolicy

package/src/utils/mapActivity.ts

@@ -165,18 +165,30 @@ export const mapLedgerEntry = (
   }
 }
 
-/** @public */
+/**
+ * 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.
+ *
+ * `userFunding` entries all carry the zero hash, so a deterministic
+ * `funding:<coin>:<ISO time>` id is synthesized — funding accrues at most
+ * once per coin per hourly settlement, so the pair is unique per account.
+ * @public
+ */
 export const mapFundingActivity = (
   entry: HlFundingUpdate,
   providerKey: string,
   resolveMarket: (coin: string) => MarketDisplay
-): FundingActivity => ({
-  id: entry.hash,
-  provider: providerKey,
-  timestamp: new Date(entry.time).toISOString(),
-  type: ActivityType.FUNDING,
-  market: resolveMarket(entry.delta.coin),
-  amount: entry.delta.usdc,
-  positionSize: entry.delta.szi,
-  fundingRate: entry.delta.fundingRate,
-})
+): FundingActivity => {
+  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),
+    amount: entry.delta.usdc,
+    positionSize: entry.delta.szi,
+    fundingRate: entry.delta.fundingRate,
+  }
+}

package/src/utils/mapFill.ts

@@ -14,6 +14,7 @@ import {
 import { SPOT_MARKET_ID } from '../constants.js'
 import type { HlUserFill } from '../types/index.js'
 
+/** Re-export the shared fill-position classifier used by Hyperliquid mappings. @public */
 export { classifyFillFromPosition }
 
 /**

package/src/utils/mapMarket.ts

@@ -1,4 +1,5 @@
 import type { PerpsMarket } from '@lifi/perps-types'
+import { PositionMarginAdjustment } from '@lifi/perps-types'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HlUniverseItem } from '../types/index.js'
 import { calculateMaintenanceMarginRate } from './liquidation.js'
@@ -31,6 +32,14 @@ export const mapMarket = (
   szDecimals: universe.szDecimals,
   priceDecimals: getMaxPriceDecimals(universe.szDecimals),
   maxLeverage: universe.maxLeverage,
-  onlyIsolated: universe.onlyIsolated === true,
+  onlyIsolated:
+    universe.marginMode !== undefined || universe.onlyIsolated === true,
+  // Deprecated `onlyIsolated` cannot distinguish strict-isolated from
+  // no-cross, so the ambiguous legacy shape fails closed as add-only.
+  positionMarginAdjustment:
+    universe.marginMode === 'noCross' ||
+    (universe.marginMode === undefined && universe.onlyIsolated !== true)
+      ? PositionMarginAdjustment.ADD_AND_REMOVE
+      : PositionMarginAdjustment.ADD_ONLY,
   maintenanceMarginRate: calculateMaintenanceMarginRate(universe.maxLeverage),
 })

package/src/utils/mapOrder.ts

@@ -34,7 +34,7 @@ export const mapOrderType = (orderType: string): OrderType => {
   }
 }
 
-/** @public */
+/** Return whether an SDK order type represents a take-profit or stop trigger. @public */
 export const isTriggerType = (type: OrderType): boolean =>
   type === OrderType.TAKE_PROFIT_MARKET ||
   type === OrderType.TAKE_PROFIT_LIMIT ||
@@ -83,7 +83,11 @@ export const isTriggerOrder = (
   return isTriggerType(mapOrderType(o.orderType))
 }
 
-/** @public */
+/**
+ * Map an open Hyperliquid order to the SDK's normalized open-order shape.
+ * Numeric IDs become strings and wire millisecond timestamps become ISO dates.
+ * @public
+ */
 export const mapOpenOrder = (
   o: HlFrontendOpenOrder,
   market: MarketDisplay
@@ -102,7 +106,10 @@ export const mapOpenOrder = (
   createdAt: new Date(o.timestamp).toISOString(),
 })
 
-/** @public */
+/**
+ * Map a Hyperliquid trigger/TP-SL order to the SDK's trigger-order shape.
+ * @public
+ */
 export const mapTriggerOrder = (
   o: HlFrontendOpenOrder,
   market: MarketDisplay
@@ -232,7 +239,11 @@ const mapTimeInForce = (tif: string | undefined): TimeInForce | undefined => {
   }
 }
 
-/** @public */
+/**
+ * Map an `orderStatus` detail to the SDK's normalized order shape, preserving
+ * decimal size/price strings and translating status, side, and time-in-force.
+ * @public
+ */
 export const mapOrder = (
   detail: HlOrderDetail,
   market: MarketDisplay

package/src/utils/mapPosition.ts

@@ -1,5 +1,6 @@
-import type { MarketDisplay, Position } from '@lifi/perps-types'
+import type { PerpsMarketDisplay, Position } from '@lifi/perps-types'
 import { MarginMode, PositionSide } from '@lifi/perps-types'
+import Big from 'big.js'
 import type { HlAssetPosition } from '../types/index.js'
 
 /**
@@ -11,30 +12,38 @@ import type { HlAssetPosition } from '../types/index.js'
 export const isOpenAssetPosition = (ap: HlAssetPosition): boolean =>
   Number.parseFloat(ap.position.szi) !== 0
 
-/** @public */
+/**
+ * Map a non-zero Hyperliquid position payload to the SDK's normalized
+ * position. Signed wire size determines side; decimal strings remain strings
+ * in the normalized response.
+ * @public
+ */
 export const mapPosition = (
   ap: HlAssetPosition,
-  market: MarketDisplay
+  market: PerpsMarketDisplay
 ): Position => {
   const pos = ap.position
-  const szi = parseFloat(pos.szi)
+  const szi = new Big(pos.szi)
+  const positionValue = new Big(pos.positionValue).abs()
+  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,
-    side: szi >= 0 ? PositionSide.LONG : PositionSide.SHORT,
-    size: Math.abs(szi).toString(),
+    side: szi.gte(0) ? PositionSide.LONG : PositionSide.SHORT,
+    size: szi.abs().toFixed(),
     entryPrice: pos.entryPx ?? '0',
-    markPrice:
-      pos.positionValue && szi !== 0
-        ? (parseFloat(pos.positionValue) / Math.abs(szi)).toString()
-        : '0',
+    markPrice: szi.eq(0) ? '0' : positionValue.div(szi.abs()).toFixed(),
     liquidationPrice: pos.liquidationPx ?? '0',
     unrealizedPnl: pos.unrealizedPnl,
     leverage: ap.position.leverage.value,
-    marginUsed: pos.marginUsed,
-    marginMode:
-      ap.position.leverage.type === 'cross'
-        ? MarginMode.CROSS
-        : MarginMode.ISOLATED,
+    marginUsed,
+    initialMarginRequirement: positionValue.div(leverage).toFixed(),
+    marginMode,
   }
 }

package/src/utils/spotBalance.ts

@@ -6,10 +6,10 @@ import { spotLogoURI } from './assetLogo.js'
 import { coinAsset } from './marketDisplay.js'
 
 /**
- * USD price keyed by spot token index: each spot market's live USD price
- * (from `priceByMarketId`, keyed by `Market.id`) under its base-asset id, and
- * every market's quote-asset id at $1. A spot market absent from
- * `priceByMarketId` values its token at 0.
+ * Build USD prices keyed by spot token asset ID. Base tokens use the supplied
+ * market mark price; quote tokens default to exactly `$1`; missing base prices
+ * default to `0`.
+ * @public
  */
 export const spotPriceById = (
   markets: readonly Market[],
@@ -30,11 +30,10 @@ export const spotPriceById = (
 }
 
 /**
- * The held spot {@link Asset} for an HL balance: the venue token index
- * (`b.token`) as `Asset.id` — equal to that token's spot `Market.baseAsset.id`
- * — with display fields derived from the coin and the override-aware spot logo.
- * `HlSpotBalance` carries no `fullName`, so Unit-bridged balances take the base
- * `_spot` rule (see {@link spotLogoURI}).
+ * Convert a Hyperliquid spot balance's numeric token index into an SDK asset.
+ * The balance payload has no `fullName`, so logo resolution uses the base
+ * `_spot` URI rule rather than Unit-underlying lookup.
+ * @public
  */
 export const spotAssetFromToken = (b: HlSpotBalance): Asset => ({
   ...coinAsset(b.coin),
@@ -42,7 +41,7 @@ export const spotAssetFromToken = (b: HlSpotBalance): Asset => ({
   logoURI: spotLogoURI(b.coin),
 })
 
-/** Assemble a typed spot {@link Balance} from its resolved asset and raw size. */
+/** Assemble a typed spot {@link Balance}; `total` is native token units and its USD value uses `priceById`. @public */
 export const spotBalance = (
   asset: Asset,
   total: string,

package/src/utils/spotCollateral.ts

@@ -13,17 +13,21 @@ const PORTFOLIO_MARGIN_LTV: Readonly<Record<string, number>> = {
   UBTC: 0.5,
 }
 
-/** @internal */
+/**
+ * Result of {@link partitionSpotBalances}: balances that count toward
+ * collateral and balances treated as ordinary holdings.
+ * @public
+ */
 export interface SpotPartition {
   collateralBalances: Balance[]
   balances: Balance[]
 }
 
 /**
- * Split spot balances into margin collateral and flat holdings. A balance is
- * collateral when its token is a category quote asset (full value) or, under
- * portfolio margin, an LTV-weighted asset (HYPE/BTC); everything else is a
- * flat holding.
+ * Partition spot balances into collateral and ordinary holdings. Quote assets
+ * are full-value collateral; portfolio-margin-supported assets retain their
+ * LTV as `collateralWeight`.
+ * @public
  */
 export const partitionSpotBalances = (
   spotBalances: readonly Balance[],