@lifi/perps-sdk-provider-hyperliquid 0.0.0-preview-c903f1e

package/src/types/index.ts

@@ -0,0 +1,11 @@
+// biome-ignore-all lint/performance/noBarrelFile lint/performance/noReExportAll: single re-export entry point
+// for every Hyperliquid wire type. Internal modules import per-file paths
+// (e.g. `../types/account.js`) to avoid pulling unrelated types into bundles.
+
+export * from './account.js'
+export * from './action.js'
+export * from './asset.js'
+export * from './fill.js'
+export * from './ledger.js'
+export * from './order.js'
+export * from './ws.js'

package/src/types/ledger.ts

@@ -0,0 +1,111 @@
+import type { Address } from 'viem'
+
+// `userNonFundingLedgerUpdates` + `userFunding` shapes.
+
+/**
+ * Hyperliquid `spotTransfer` ledger delta. Emitted for transfers of spot
+ * tokens between Hyperliquid accounts. `user` is the sender, `destination`
+ * the recipient; direction is derived at the call site from the queried
+ * address.
+ * @public
+ */
+export type HlSpotTransferDelta = {
+  type: 'spotTransfer'
+  token: string
+  amount: string
+  usdcValue: string
+  user: Address
+  destination: Address
+  fee?: string
+  nativeTokenFee?: string
+  nonce?: number
+}
+
+/**
+ * Hyperliquid ledger delta emitted for the `sendAsset` exchange action. The
+ * wire `type` literal is `'send'` (NOT `'sendAsset'`); the TS name retains
+ * the `SendAsset` prefix to match `HL_PRIMARY_TYPE_SEND_ASSET`.
+ *
+ * - `user` is the sender, `destination` the recipient. For same-user dex
+ *   moves both equal the queried address.
+ * - `sourceDex` / `destinationDex` use `""` for the main USDC perp DEX,
+ *   `"spot"` for spot, or the perp DEX name otherwise.
+ * - `token` is a wire token identifier (e.g. `"USDC"` or `"TOKEN:0x..."`).
+ * - `nonce` is the wire nonce (ms timestamp); always present on `send`
+ *   deltas, unlike `spotTransfer` where it may be null.
+ * @public
+ */
+export type HlSendAssetDelta = {
+  type: 'send'
+  user: Address
+  destination: Address
+  sourceDex: string
+  destinationDex: string
+  token: string
+  amount: string
+  usdcValue: string
+  fee: string
+  nativeTokenFee: string
+  nonce: number
+  feeToken: string
+}
+
+/** @public */
+export type HlLedgerDelta =
+  | HlSpotTransferDelta
+  | HlSendAssetDelta
+  | {
+      type: string
+      usdc?: string
+      [key: string]: unknown
+    }
+
+/**
+ * Type guard for `HlSpotTransferDelta` — TypeScript cannot narrow off the
+ * `type` discriminant alone because the catch-all arm of `HlLedgerDelta` has
+ * `type: string` (a supertype of the literal `'spotTransfer'`). Use this at
+ * call sites that need the strongly-typed shape.
+ * @public
+ */
+export const isSpotTransferDelta = (
+  delta: HlLedgerDelta
+): delta is HlSpotTransferDelta => delta.type === 'spotTransfer'
+
+/**
+ * Type guard for `HlSendAssetDelta`. The wire `type` literal is `'send'`;
+ * see `HlSendAssetDelta` for the naming-vs-wire-format rationale. Same
+ * catch-all-arm caveat as `isSpotTransferDelta`.
+ * @public
+ */
+export const isSendAssetDelta = (
+  delta: HlLedgerDelta
+): delta is HlSendAssetDelta => delta.type === 'send'
+
+/** @public */
+export type HlLedgerUpdate = {
+  time: number
+  hash: string
+  delta: HlLedgerDelta
+}
+
+/** @public */
+export type HlUserNonFundingLedgerUpdates = HlLedgerUpdate[]
+
+/** @public */
+export type HlFundingDelta = {
+  type: 'funding'
+  coin: string
+  usdc: string
+  szi: string
+  fundingRate: string
+}
+
+/** @public */
+export type HlFundingUpdate = {
+  time: number
+  hash: string
+  delta: HlFundingDelta
+}
+
+/** @public */
+export type HlUserFunding = HlFundingUpdate[]

package/src/types/order.ts

@@ -0,0 +1,56 @@
+// Order shapes returned by Hyperliquid `/info`.
+
+/** @public */
+export type HlFrontendOpenOrder = {
+  oid: number
+  coin: string
+  side: string
+  sz: string
+  limitPx: string
+  orderType: string
+  origSz: string
+  reduceOnly: boolean
+  timestamp: number
+  isTrigger: boolean
+  isPositionTpsl: boolean
+  triggerCondition: string
+  triggerPx: string
+  children: HlFrontendOpenOrder[]
+  tif: string | null
+  cloid: string | null
+}
+
+/** @public */
+export type HlFrontendOpenOrders = HlFrontendOpenOrder[]
+
+/** @public */
+export type HlOrderDetail = {
+  order: {
+    oid: number
+    coin: string
+    side: string
+    sz: string
+    limitPx: string
+    orderType: string
+    origSz: string
+    reduceOnly: boolean
+    timestamp: number
+    tif: string | null
+    cloid: string | null
+    triggerCondition: string
+    triggerPx: string | null
+  }
+  status: string
+  statusTimestamp: number
+}
+
+/** @public */
+export type HlOrderStatusFound = {
+  status: 'order'
+  order: HlOrderDetail
+}
+
+/** @public */
+export type HlOrderStatusResponse =
+  | HlOrderStatusFound
+  | { status: 'unknownOid' }

package/src/types/ws.ts

@@ -0,0 +1,47 @@
+// Hyperliquid WebSocket incoming message types.
+
+import type { HlClearinghouseState, HlSpotBalance } from './account.js'
+import type { HlAllMids, HlCandle, HlL2Book } from './asset.js'
+import type { HlUserFill } from './fill.js'
+
+/** @public */
+export type HlWsMessage = {
+  channel: string
+  data: unknown
+}
+
+/** @public */
+export type HlWsAllMidsData = {
+  mids: HlAllMids
+  dex?: string
+}
+
+/** @public */
+export type HlWsL2BookData = HlL2Book & { coin: string }
+
+/** @public */
+export type HlWsCandleData = HlCandle & {
+  T: number
+  s: string
+  i: string
+  n: number
+}
+
+/** @public */
+export type HlWsUserFillsData = {
+  isSnapshot: boolean
+  user: string
+  fills: HlUserFill[]
+}
+
+/** @public */
+export type HlWsAllDexsClearinghouseStateData = {
+  user: string
+  clearinghouseStates: [string, Pick<HlClearinghouseState, 'assetPositions'>][]
+}
+
+/** @public */
+export type HlWsSpotStateData = {
+  user: string
+  spotState: { balances: HlSpotBalance[] }
+}

package/src/utils/assetId.ts

@@ -0,0 +1,38 @@
+/**
+ * Spot asset IDs use the @pairIndex format (e.g. "@230").
+ *
+ * @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
+ * @public
+ */
+export const calculateAssetId = (
+  providerIndex: number,
+  indexInProvider: number
+): number => {
+  if (providerIndex === 0) {
+    return indexInProvider
+  }
+  return 100_000 + providerIndex * 10_000 + indexInProvider
+}
+
+/**
+ * Get the provider index from the given list of provider names.
+ * @public
+ */
+export const getProviderIndex = (
+  provider: string,
+  providerNames: string[]
+): number => {
+  const index = providerNames.indexOf(provider)
+  if (index === -1) {
+    throw new Error(`Unknown sub-provider: ${provider}`)
+  }
+  return index
+}

package/src/utils/index.ts

@@ -0,0 +1,38 @@
+// biome-ignore-all lint/performance/noBarrelFile: single re-export entry point
+// for the package's utility surface. Internal modules import per-file paths
+// (e.g. `./assetId.js`, `./mapFill.js`) directly.
+
+export { assetIsSpot, calculateAssetId, getProviderIndex } from './assetId.js'
+export type { InfoRequestOptions } from './infoClient.js'
+export { hlInfoOptions, infoRequest } from './infoClient.js'
+export {
+  calculateLiquidationPrice,
+  calculateMaintenanceMarginRate,
+} from './liquidation.js'
+export { mapFundingActivity, mapLedgerEntry } from './mapActivity.js'
+export { classifyFillFromPosition, mapFill } from './mapFill.js'
+export { mapMarket } from './mapMarket.js'
+export { mapMarketPrice } from './mapMarketPrice.js'
+export {
+  isTriggerOrder,
+  isTriggerType,
+  mapOpenOrder,
+  mapOrder,
+  mapOrderStatus,
+  mapOrderType,
+  mapStatusReason,
+  mapTriggerOrder,
+} from './mapOrder.js'
+export { isOpenAssetPosition, mapPosition } from './mapPosition.js'
+export { coinAsset, perpsDexNames } from './marketDisplay.js'
+export {
+  formatOrderPrice,
+  formatOrderSize,
+  getMaxPriceDecimals,
+} from './orderFormatting.js'
+export { priceStepToAggregation } from './priceStepToAggregation.js'
+export {
+  spotAssetFromToken,
+  spotBalance,
+  spotPriceById,
+} from './spotBalance.js'

package/src/utils/infoClient.ts

@@ -0,0 +1,111 @@
+import {
+  fetchWithRetry,
+  PerpsError,
+  type PerpsSDKClient,
+  type ResolvedRetryPolicy,
+  resolveRetryPolicy,
+  type SDKRequestOptions,
+} from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PROVIDER_KEY } from '../constants.js'
+
+/** @internal */
+export const HYPERLIQUID_RETRY_DEFAULTS: ResolvedRetryPolicy = {
+  enabled: true,
+  maxAttempts: 3,
+  baseDelayMs: 2_000,
+  maxDelayMs: 15_000,
+  respectRetryAfter: true,
+  classify: ({ response }) => {
+    if (response.status === 429) {
+      return 'retry-rate-limit'
+    }
+    if (
+      response.status === 502 ||
+      response.status === 503 ||
+      response.status === 504
+    ) {
+      return 'retry-server'
+    }
+    return 'fail'
+  },
+}
+
+/** @public */
+export interface InfoRequestOptions {
+  signal?: AbortSignal
+  policy?: ResolvedRetryPolicy
+  fetchImpl?: typeof fetch
+}
+
+/**
+ * Resolve the client's retry/fetch config into options for {@link infoRequest}.
+ *
+ * @public
+ */
+export const hlInfoOptions = (
+  client: PerpsSDKClient,
+  options?: SDKRequestOptions
+): InfoRequestOptions => ({
+  signal: options?.signal,
+  policy: resolveRetryPolicy(
+    HYPERLIQUID_RETRY_DEFAULTS,
+    client.config.retry,
+    PROVIDER_KEY
+  ),
+  fetchImpl: client.config.fetch,
+})
+
+/**
+ * POST to the Hyperliquid `/info` endpoint and return the parsed JSON body.
+ *
+ * Direct-to-venue: no proxy, no AJV validation, no cache. The caller's type
+ * parameter is trusted; consumers should treat the response shape as
+ * upstream-controlled and normalise into `@lifi/perps-types` shapes before
+ * surfacing.
+ *
+ * Non-2xx responses raise a {@link PerpsError} with the Hyperliquid provider key.
+ * @public
+ */
+export async function infoRequest<T>(
+  apiUrl: string,
+  body: Record<string, unknown>,
+  options?: InfoRequestOptions
+): Promise<T> {
+  const policy = options?.policy ?? HYPERLIQUID_RETRY_DEFAULTS
+
+  let response: Response
+  try {
+    response = await fetchWithRetry(
+      `${apiUrl}/info`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      },
+      {
+        policy,
+        fetchImpl: options?.fetchImpl,
+        signal: options?.signal,
+      }
+    )
+  } catch (error) {
+    const err = new PerpsError(
+      PerpsErrorCode.ServerError,
+      error instanceof Error ? error.message : 'Hyperliquid info request failed'
+    )
+    err.tool = PROVIDER_KEY
+    throw err
+  }
+
+  if (!response.ok) {
+    const err = new PerpsError(
+      PerpsErrorCode.ThirdPartyError,
+      `Hyperliquid info request failed: ${response.status}`
+    )
+    err.tool = PROVIDER_KEY
+    throw err
+  }
+
+  return (await response.json()) as T
+}

package/src/utils/liquidation.ts

@@ -0,0 +1,74 @@
+/**
+ * Hyperliquid-specific liquidation price calculation.
+ *
+ * Uses the exact formula from Hyperliquid docs:
+ * https://hyperliquid.gitbook.io/hyperliquid-docs/trading/liquidations
+ *
+ * liq_price = price - side * margin_available / position_size / (1 - l * side)
+ *
+ * Where:
+ * - l = 1 / (2 * maxLeverage) (maintenance margin fraction)
+ * - side = 1 (long) or -1 (short)
+ * - margin_available = isolated_margin - maintenance_margin_required
+ */
+
+import { estimateIsolatedLiquidationPrice } from '@lifi/perps-sdk'
+
+/**
+ * Calculate the maintenance margin fraction for a Hyperliquid asset.
+ *
+ * Maintenance margin is half of the initial margin at max leverage.
+ *
+ * @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
+ * @public
+ */
+export function calculateMaintenanceMarginRate(
+  maxLeverage: number
+): number | undefined {
+  if (maxLeverage === 0) {
+    return undefined
+  }
+  return 1 / (2 * maxLeverage)
+}
+
+/**
+ * Calculate liquidation price using the exact Hyperliquid formula.
+ *
+ * For isolated margin, new position prediction. For existing positions,
+ * 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)
+ *
+ * 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
+ * @public
+ */
+export function calculateLiquidationPrice(
+  entryPrice: number,
+  leverage: number,
+  isLong: boolean,
+  maxLeverage: number
+): number | undefined {
+  const mmr = calculateMaintenanceMarginRate(maxLeverage)
+  if (mmr === undefined) {
+    return undefined
+  }
+  return estimateIsolatedLiquidationPrice({
+    entryPrice,
+    leverage,
+    isLong,
+    maintenanceMarginRate: mmr,
+  })
+}

package/src/utils/mapActivity.ts

@@ -0,0 +1,182 @@
+import type {
+  ActivityItem,
+  DepositActivity,
+  FundingActivity,
+  LiquidationActivity,
+  MarketDisplay,
+  TransferActivity,
+  WithdrawalActivity,
+} 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'
+
+/**
+ * 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`).
+ * @public
+ */
+export const mapLedgerEntry = (
+  entry: HlLedgerUpdate,
+  providerKey: string,
+  queriedAddress: string,
+  resolveMarket: (coin: string) => MarketDisplay
+): ActivityItem | null => {
+  const { delta } = entry
+  const base = {
+    id: entry.hash,
+    provider: providerKey,
+    timestamp: new Date(entry.time).toISOString(),
+  }
+
+  // Handled before the switch: the catch-all arm of `HlLedgerDelta` is a
+  // structural supertype of the concrete delta, so a `switch (delta.type)`
+  // cannot narrow off the discriminant. The user-defined type guard does.
+  if (isSpotTransferDelta(delta)) {
+    const queried = queriedAddress.toLowerCase()
+    const sender = delta.user.toLowerCase()
+    const recipient = delta.destination.toLowerCase()
+    const direction: 'IN' | 'OUT' = queried === sender ? 'OUT' : 'IN'
+    const counterpartyAddress = direction === 'OUT' ? recipient : sender
+    const meta: Record<string, unknown> = {
+      transferType: 'spotTransfer',
+    }
+    if (delta.usdcValue !== undefined) {
+      meta.usdcValue = delta.usdcValue
+    }
+    if (delta.fee !== undefined) {
+      meta.fee = delta.fee
+    }
+    if (delta.nativeTokenFee !== undefined) {
+      meta.nativeTokenFee = delta.nativeTokenFee
+    }
+    if (delta.nonce !== undefined) {
+      meta.nonce = delta.nonce
+    }
+    return {
+      ...base,
+      type: ActivityType.TRANSFER,
+      direction,
+      counterpartyAddress,
+      asset: delta.token,
+      amount: delta.amount,
+      meta,
+      explorerLink: entry.hash
+        ? `https://app.hyperliquid.xyz/explorer/tx/${entry.hash}`
+        : undefined,
+    } satisfies TransferActivity
+  }
+
+  // `sendAsset` (wire `type === 'send'`) covers cross-user transfers
+  // (modelled as TRANSFER) and same-user dex moves (returned as null —
+  // overloading TRANSFER for those would lie about direction). Pre-switch
+  // narrowing for the same reason as spotTransfer.
+  if (isSendAssetDelta(delta)) {
+    const queried = queriedAddress.toLowerCase()
+    const sender = delta.user.toLowerCase()
+    const recipient = delta.destination.toLowerCase()
+
+    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> = {
+      transferType: 'sendAsset',
+      sourceDex: delta.sourceDex,
+      destinationDex: delta.destinationDex,
+      usdcValue: delta.usdcValue,
+      fee: delta.fee,
+      nativeTokenFee: delta.nativeTokenFee,
+      feeToken: delta.feeToken,
+      nonce: delta.nonce,
+    }
+    return {
+      ...base,
+      type: ActivityType.TRANSFER,
+      direction,
+      counterpartyAddress,
+      asset: delta.token,
+      amount: delta.amount,
+      meta,
+      explorerLink: entry.hash
+        ? `https://app.hyperliquid.xyz/explorer/tx/${entry.hash}`
+        : undefined,
+    } 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
+
+    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
+    }
+
+    default:
+      return null
+  }
+}
+
+/** @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,
+})