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

package/src/context.ts

@@ -0,0 +1,41 @@
+import { PerpsError, type PerpsSDKClient } from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+
+/**
+ * Runtime context the Hyperliquid read services resolve their deps from: the
+ * bound {@link PerpsSDKClient} (config / fetch / retry / market lookups) and
+ * the resolved REST base URL. Captured once in the provider factory's closure
+ * via {@link HyperliquidContextRef.bind}; the read methods read it at call
+ * time. This is the late-bind the SDK's `bindProvider` sets up — the factory
+ * is constructed before the client exists.
+ */
+export interface HyperliquidContext {
+  client: PerpsSDKClient
+  apiUrl: string
+}
+
+/**
+ * Mutable, single-assignment holder for the {@link HyperliquidContext}. The
+ * provider factory creates one per instance and exposes `bind`; the read
+ * services call {@link HyperliquidContextRef.require} at call time.
+ */
+export class HyperliquidContextRef {
+  private context: HyperliquidContext | undefined
+
+  constructor(private readonly apiUrl: string) {}
+
+  bind(client: PerpsSDKClient): void {
+    this.context = { client, apiUrl: this.apiUrl }
+  }
+
+  require(): HyperliquidContext {
+    if (this.context === undefined) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        'hyperliquidProvider used before binding. Register it via ' +
+          'createPerpsClient({ providers: [hyperliquidProvider()] }).'
+      )
+    }
+    return this.context
+  }
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+// biome-ignore-all lint/performance/noBarrelFile: package public entry point.
+// biome-ignore-all lint/performance/noReExportAll: package public entry point.
+
+/**
+ * Hyperliquid provider plugin for `@lifi/perps-sdk`. Reads account-specific
+ * state directly from `${apiUrl}/info`; enriched asset metadata and
+ * public/shared data come from the LI.FI backend. Register the
+ * `hyperliquidProvider()` factory with `createPerpsClient`.
+ *
+ * @packageDocumentation
+ * @public
+ */
+
+export { projectHyperliquidConfigSettings } from './accountConfig.js'
+export { getAccountSummary } from './accountSummary.js'
+export {
+  DEFAULT_HYPERLIQUID_API_URL,
+  HYPERLIQUID_FEE_TIER_FALLBACK,
+  PROVIDER_KEY as HYPERLIQUID_PROVIDER_KEY,
+} from './constants.js'
+export {
+  type HyperliquidPerpsProvider,
+  type HyperliquidProviderOptions,
+  hyperliquidProvider,
+} from './HyperliquidProvider.js'
+export type { GetAccountParams } from './services/getAccount.js'
+export { getAccount } from './services/getAccount.js'
+export type { GetActivityParams } from './services/getActivity.js'
+export { getActivity } from './services/getActivity.js'
+export type { GetFillsParams } from './services/getFills.js'
+export { getFills } from './services/getFills.js'
+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 { GetPositionsParams } from './services/getPositions.js'
+export { getPositions } from './services/getPositions.js'
+export type { HyperliquidAgent } from './signers/HyperliquidAgentStore.js'
+export { HyperliquidAgentStore } from './signers/HyperliquidAgentStore.js'
+export * from './types/index.js'
+export * from './utils/index.js'
+export {
+  HyperliquidWsProvider,
+  hyperliquidWsProvider,
+} from './websocket/HyperliquidWsProvider.js'

package/src/services/getAccount.ts

@@ -0,0 +1,263 @@
+import {
+  getMarketRegistry,
+  getPrices,
+  type ProviderGetAccountParams,
+  type SDKRequestOptions,
+  stringToFloat,
+} from '@lifi/perps-sdk'
+import type {
+  AccountResponse,
+  Asset,
+  Balance,
+  HyperliquidAccountConfig,
+  Position,
+} from '@lifi/perps-types'
+import { PROVIDER_KEY } from '../constants.js'
+import type { HyperliquidContext } from '../context.js'
+import {
+  HlAbstractionMode,
+  type HlClearinghouseState,
+  type HlExtraAgents,
+  type HlSpotClearinghouseState,
+  type HlUserFees,
+} from '../types/index.js'
+import {
+  perpsDexNames,
+  spotAssetFromToken,
+  spotBalance,
+  spotPriceById,
+} from '../utils/index.js'
+import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+import { mapPosition } from '../utils/mapPosition.js'
+
+/**
+ * Parameters for {@link getAccount}.
+ *
+ * @public
+ */
+export type GetAccountParams = ProviderGetAccountParams
+
+const getAccountValue = (state: HlClearinghouseState): number =>
+  Number.parseFloat(
+    state.crossMarginSummary.accountValue || state.marginSummary.accountValue
+  )
+
+const getTotalMarginUsed = (state: HlClearinghouseState): number =>
+  Number.parseFloat(
+    state.crossMarginSummary.totalMarginUsed ||
+      state.marginSummary.totalMarginUsed
+  )
+
+const getMarginUsed = (
+  abstraction: HlAbstractionMode | null,
+  positions: Position[],
+  stateByDex: Map<string, HlClearinghouseState>
+): string => {
+  if (
+    abstraction === HlAbstractionMode.UNIFIED_ACCOUNT ||
+    abstraction === HlAbstractionMode.PORTFOLIO_MARGIN
+  ) {
+    // Per HL docs, individual per-dex states are not meaningful for these
+    // modes; derive total margin from the already-mapped positions.
+    const total = positions.reduce(
+      (sum, p) => sum + Number.parseFloat(p.marginUsed),
+      0
+    )
+    return total.toString()
+  }
+
+  if (abstraction === HlAbstractionMode.DEX_ABSTRACTION) {
+    let total = 0
+    for (const [, state] of stateByDex) {
+      total += getTotalMarginUsed(state)
+    }
+    return total.toString()
+  }
+
+  const mainState = stateByDex.get('')
+  if (!mainState) {
+    return '0'
+  }
+  return getTotalMarginUsed(mainState).toString()
+}
+
+const isUnifiedMode = (abstraction: HlAbstractionMode | null): boolean =>
+  abstraction === HlAbstractionMode.UNIFIED_ACCOUNT ||
+  abstraction === HlAbstractionMode.PORTFOLIO_MARGIN
+
+interface BalancePartition {
+  balances: Balance[]
+  collateralBalances: Balance[]
+}
+
+const buildBalances = (
+  abstraction: HlAbstractionMode | null,
+  spotState: HlSpotClearinghouseState,
+  stateByDex: Map<string, HlClearinghouseState>,
+  quoteAssetIds: ReadonlySet<string>,
+  priceById: Map<string, number>,
+  quoteAssetByCategory: Map<string, Asset>
+): BalancePartition => {
+  const balances: Balance[] = []
+  const collateralBalances: Balance[] = []
+
+  // Spot balances: collateral iff the token is a category quote asset.
+  for (const b of spotState.balances) {
+    const balance = spotBalance(spotAssetFromToken(b), b.total, priceById)
+    if (quoteAssetIds.has(balance.asset.id)) {
+      collateralBalances.push(balance)
+    } else {
+      balances.push(balance)
+    }
+  }
+
+  // Unified/portfolio modes hold everything in spot — per-dex equity would
+  // double-count. Only disabled/dexAbstraction carry separate venue collateral.
+  // `accountValue` is reported net of locked margin, i.e. the free collateral;
+  // the locked portion is carried by the positions' `marginUsed`.
+  if (!isUnifiedMode(abstraction)) {
+    for (const [dex, state] of stateByDex) {
+      const categoryId = dex || PROVIDER_KEY
+      const value = getAccountValue(state)
+      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(),
+      })
+    }
+  }
+
+  return { balances, collateralBalances }
+}
+
+/**
+ * Fetch the Hyperliquid account snapshot for `address`: balances per
+ * sub-dex (and spot), aggregate margin used, unrealised PnL, fee tier, and
+ * the typed `HyperliquidAccountConfig`.
+ *
+ * Issues `userFees`, `userAbstraction`, `extraAgents`,
+ * `spotClearinghouseState` and one `clearinghouseState` per supported perps
+ * sub-dex, all concurrently.
+ *
+ * `config.builderFeeApproval` is intentionally omitted — that field
+ * compares the venue's `maxBuilderFee` against the integrator-specific
+ * builder address LI.FI publishes, which is not data the venue itself
+ * owns. Surfacing it belongs at a higher layer (the LI.FI backend or a
+ * thin client-side helper that has the integrator's builder config).
+ * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
+ * @public
+ */
+export const getAccount = async (
+  { client, apiUrl }: HyperliquidContext,
+  params: GetAccountParams,
+  options?: SDKRequestOptions
+): Promise<AccountResponse> => {
+  const registry = getMarketRegistry(client, PROVIDER_KEY)
+  const markets = await registry.sync()
+  const dexNames = perpsDexNames(markets)
+  const quoteAssetIds = new Set(markets.map((m) => m.quoteAsset.id))
+  const quoteAssetByCategory = new Map(
+    markets.map((m) => [m.categoryId, m.quoteAsset])
+  )
+  const infoOpts = hlInfoOptions(client, options)
+
+  const [
+    feesResult,
+    abstractionResult,
+    agentsResult,
+    spotState,
+    stateResults,
+    { prices },
+  ] = await Promise.all([
+    infoRequest<HlUserFees>(
+      apiUrl,
+      { type: 'userFees', 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 route margin/balance down the wrong, non-unified branch).
+    infoRequest<HlAbstractionMode | null>(
+      apiUrl,
+      { type: 'userAbstraction', user: params.address },
+      infoOpts
+    ),
+    infoRequest<HlExtraAgents>(
+      apiUrl,
+      { type: 'extraAgents', user: params.address },
+      infoOpts
+    ),
+    infoRequest<HlSpotClearinghouseState>(
+      apiUrl,
+      { type: 'spotClearinghouseState', user: params.address },
+      infoOpts
+    ),
+    Promise.all(
+      dexNames.map((name) =>
+        infoRequest<HlClearinghouseState>(
+          apiUrl,
+          {
+            type: 'clearinghouseState',
+            user: params.address,
+            ...(name ? { dex: name } : {}),
+          },
+          infoOpts
+        )
+      )
+    ),
+    getPrices(client, { provider: PROVIDER_KEY }, options),
+  ])
+
+  const priceById = spotPriceById(
+    markets,
+    new Map(prices.map((p) => [p.marketId, stringToFloat(p.markPrice)]))
+  )
+
+  const positions: Position[] = stateResults.flatMap((state) =>
+    state.assetPositions
+      .filter((ap) => Number.parseFloat(ap.position.szi) !== 0)
+      .map((ap) => mapPosition(ap, registry.require(ap.position.coin)))
+  )
+
+  const stateByDex = new Map<string, HlClearinghouseState>()
+  stateResults.forEach((state, i) => {
+    stateByDex.set(dexNames[i], state)
+  })
+
+  const totalUnrealizedPnl = positions.reduce(
+    (sum, p) => sum + Number.parseFloat(p.unrealizedPnl),
+    0
+  )
+
+  const config: HyperliquidAccountConfig = {
+    provider: PROVIDER_KEY,
+    abstractionMode: abstractionResult,
+    agents: agentsResult,
+  }
+
+  const { balances, collateralBalances } = buildBalances(
+    abstractionResult,
+    spotState,
+    stateByDex,
+    quoteAssetIds,
+    priceById,
+    quoteAssetByCategory
+  )
+
+  return {
+    provider: PROVIDER_KEY,
+    address: params.address,
+    balances,
+    collateralBalances,
+    marginUsed: getMarginUsed(abstractionResult, positions, stateByDex),
+    unrealizedPnl: totalUnrealizedPnl.toString(),
+    feeTier: {
+      maker: feesResult.userAddRate ?? '0',
+      taker: feesResult.userCrossRate ?? '0',
+    },
+    config,
+  }
+}

package/src/services/getActivity.ts

@@ -0,0 +1,162 @@
+import { getMarketRegistry, type SDKRequestOptions } from '@lifi/perps-sdk'
+import type {
+  ActivitiesResponse,
+  ActivityItem,
+  MarketDisplay,
+} from '@lifi/perps-types'
+import { ActivityType } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import {
+  DEFAULT_HISTORY_LIMIT,
+  MAX_HISTORY_LIMIT,
+  NINETY_DAYS_MS,
+  PROVIDER_KEY,
+} from '../constants.js'
+import type { HyperliquidContext } from '../context.js'
+import type {
+  HlUserFunding,
+  HlUserNonFundingLedgerUpdates,
+} from '../types/index.js'
+import { mapFundingActivity, mapLedgerEntry } from '../utils/index.js'
+import {
+  hlInfoOptions,
+  type InfoRequestOptions,
+  infoRequest,
+} from '../utils/infoClient.js'
+
+/**
+ * Parameters for {@link getActivity}.
+ *
+ * @public
+ */
+export interface GetActivityParams {
+  address: Address
+  limit?: number
+  /** `cursor` is a ms-since-epoch upper bound — items with `timestamp < cursor` are returned. */
+  cursor?: string
+  startTime?: number
+  endTime?: number
+  type?: ActivityType[]
+}
+
+const fetchActivityData = async (
+  apiUrl: string,
+  typeFilter: ActivityType[] | undefined,
+  timeParams: { user: Address; startTime: number; endTime?: number },
+  resolveMarket: (coin: string) => MarketDisplay,
+  options?: InfoRequestOptions
+): Promise<ActivityItem[]> => {
+  const needLedger =
+    !typeFilter || typeFilter.some((t) => t !== ActivityType.FUNDING)
+  const needFunding = !typeFilter || typeFilter.includes(ActivityType.FUNDING)
+
+  const [ledgerUpdates, fundingUpdates] = await Promise.all([
+    needLedger
+      ? infoRequest<HlUserNonFundingLedgerUpdates>(
+          apiUrl,
+          { type: 'userNonFundingLedgerUpdates', ...timeParams },
+          options
+        )
+      : Promise.resolve([] as HlUserNonFundingLedgerUpdates),
+    needFunding
+      ? infoRequest<HlUserFunding>(
+          apiUrl,
+          { type: 'userFunding', ...timeParams },
+          options
+        )
+      : Promise.resolve([] as HlUserFunding),
+  ])
+
+  const ledgerItems: ActivityItem[] = ledgerUpdates
+    .map((entry) =>
+      mapLedgerEntry(entry, PROVIDER_KEY, timeParams.user, resolveMarket)
+    )
+    .filter((item): item is ActivityItem => item !== null)
+
+  const fundingItems: ActivityItem[] = fundingUpdates.map((entry) =>
+    mapFundingActivity(entry, PROVIDER_KEY, resolveMarket)
+  )
+
+  const merged = [...ledgerItems, ...fundingItems].sort(
+    (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
+  )
+
+  if (!typeFilter) {
+    return merged
+  }
+  const typeSet = new Set(typeFilter)
+  return merged.filter((item) => typeSet.has(item.type))
+}
+
+/**
+ * Fetch a chronological activity feed (deposits, withdrawals, transfers,
+ * liquidations, funding) for `address`. Combines results from Hyperliquid's
+ * `userNonFundingLedgerUpdates` and `userFunding` endpoints, sorted
+ * newest-first.
+ *
+ * Cursor-based pagination uses the ms-since-epoch timestamp of the last
+ * item on the current page. `startTime` defaults to 90 days ago to keep
+ * unbounded queries cheap.
+ * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
+ * @public
+ */
+export const getActivity = async (
+  { client, apiUrl }: HyperliquidContext,
+  params: GetActivityParams,
+  options?: SDKRequestOptions
+): Promise<ActivitiesResponse> => {
+  const registry = getMarketRegistry(client, PROVIDER_KEY)
+  await registry.sync()
+  const infoOpts = hlInfoOptions(client, options)
+
+  const limit = Math.min(
+    params.limit ?? DEFAULT_HISTORY_LIMIT,
+    MAX_HISTORY_LIMIT
+  )
+  const startTime = params.startTime ?? Date.now() - NINETY_DAYS_MS
+  const endTime =
+    params.cursor === undefined
+      ? params.endTime
+      : Number.parseInt(params.cursor, 10)
+
+  const timeParams = {
+    user: params.address,
+    startTime,
+    ...(endTime === undefined ? {} : { endTime }),
+  }
+
+  const merged = await fetchActivityData(
+    apiUrl,
+    params.type,
+    timeParams,
+    (coin) => registry.require(coin),
+    infoOpts
+  )
+
+  // Hyperliquid's endTime is inclusive — drop boundary items so we don't
+  // return the cursor row twice on the next page.
+  const filtered =
+    params.cursor === undefined
+      ? merged
+      : merged.filter(
+          (item) =>
+            new Date(item.timestamp).getTime() <
+            Number.parseInt(params.cursor!, 10)
+        )
+
+  const hasMore = filtered.length > limit
+  const items = filtered.slice(0, limit)
+
+  return {
+    provider: PROVIDER_KEY,
+    items,
+    pagination: {
+      limit,
+      hasMore,
+      cursor:
+        items.length > 0
+          ? String(new Date(items[items.length - 1].timestamp).getTime())
+          : undefined,
+    },
+  }
+}

package/src/services/getFills.ts

@@ -0,0 +1,96 @@
+import { getMarketRegistry, type SDKRequestOptions } from '@lifi/perps-sdk'
+import type { FillsResponse } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import {
+  DEFAULT_HISTORY_LIMIT,
+  MAX_HISTORY_LIMIT,
+  PROVIDER_KEY,
+} from '../constants.js'
+import type { HyperliquidContext } from '../context.js'
+import type { HlUserFills, HlUserFillsByTime } from '../types/index.js'
+import { mapFill } from '../utils/index.js'
+import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+
+/**
+ * Parameters for {@link getFills}.
+ *
+ * @public
+ */
+export interface GetFillsParams {
+  address: Address
+  limit?: number
+  /** `tid` of the oldest fill to return (returned items have `tid < cursor`). */
+  cursor?: string
+  /** Inclusive lower bound in ms-since-epoch — switches to the `userFillsByTime` endpoint. */
+  startTime?: number
+  /** Inclusive upper bound in ms-since-epoch — switches to the `userFillsByTime` endpoint. */
+  endTime?: number
+}
+
+/**
+ * Fetch the user's fills history. When `startTime` or `endTime` is provided,
+ * Hyperliquid's `userFillsByTime` endpoint is used; otherwise the unbounded
+ * `userFills` endpoint returns the full history. The backend's enriched asset
+ * list supplies the display fields; only the fills endpoint is read direct
+ * from HL.
+ *
+ * Pagination is cursor-based on the fill's `tid`: results with
+ * `tid < cursor` are kept and the last-page's tail `id` is returned as the
+ * next cursor.
+ * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
+ * @public
+ */
+export const getFills = async (
+  { client, apiUrl }: HyperliquidContext,
+  params: GetFillsParams,
+  options?: SDKRequestOptions
+): Promise<FillsResponse> => {
+  const registry = getMarketRegistry(client, PROVIDER_KEY)
+  await registry.sync()
+  const infoOpts = hlInfoOptions(client, options)
+
+  const limit = Math.min(
+    params.limit ?? DEFAULT_HISTORY_LIMIT,
+    MAX_HISTORY_LIMIT
+  )
+
+  const useByTime =
+    params.startTime !== undefined || params.endTime !== undefined
+
+  const allFills = useByTime
+    ? await infoRequest<HlUserFillsByTime>(
+        apiUrl,
+        {
+          type: 'userFillsByTime',
+          user: params.address,
+          startTime: params.startTime ?? 0,
+          ...(params.endTime !== undefined ? { endTime: params.endTime } : {}),
+        },
+        infoOpts
+      )
+    : await infoRequest<HlUserFills>(
+        apiUrl,
+        { type: 'userFills', user: params.address },
+        infoOpts
+      )
+
+  const filtered =
+    params.cursor === undefined
+      ? allFills
+      : allFills.filter((f) => f.tid < Number.parseInt(params.cursor!, 10))
+
+  const hasMore = filtered.length > limit
+  const items = filtered
+    .slice(0, limit)
+    .map((f) => mapFill(f, registry.require(f.coin)))
+
+  return {
+    provider: PROVIDER_KEY,
+    items,
+    pagination: {
+      limit,
+      hasMore,
+      cursor: items.length > 0 ? items[items.length - 1].id : undefined,
+    },
+  }
+}

package/src/services/getOrder.ts

@@ -0,0 +1,61 @@
+import {
+  getMarketRegistry,
+  PerpsError,
+  type ProviderGetOrderParams,
+  type SDKRequestOptions,
+} from '@lifi/perps-sdk'
+import type { Order } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PROVIDER_KEY } from '../constants.js'
+import type { HyperliquidContext } from '../context.js'
+import type { HlOrderStatusResponse } from '../types/index.js'
+import { mapOrder } from '../utils/index.js'
+import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+
+/**
+ * Parameters for {@link getOrder}.
+ *
+ * @public
+ */
+export type GetOrderParams = ProviderGetOrderParams
+
+/**
+ * Read getOrder direct from the Hyperliquid REST API.
+ *
+ * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
+ * @public
+ */
+export const getOrder = async (
+  { client, apiUrl }: HyperliquidContext,
+  params: GetOrderParams,
+  options?: SDKRequestOptions
+): Promise<Order> => {
+  const oid = Number.parseInt(params.id, 10)
+  if (Number.isNaN(oid)) {
+    const err = new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Invalid order ID: ${params.id}. Must be a numeric oid.`
+    )
+    err.tool = PROVIDER_KEY
+    throw err
+  }
+
+  const status = await infoRequest<HlOrderStatusResponse>(
+    apiUrl,
+    { type: 'orderStatus', user: params.address, oid },
+    hlInfoOptions(client, options)
+  )
+
+  if (status.status !== 'order') {
+    const err = new PerpsError(
+      PerpsErrorCode.OrderNotFound,
+      `Order not found: ${params.id}`
+    )
+    err.tool = PROVIDER_KEY
+    throw err
+  }
+
+  const registry = getMarketRegistry(client, PROVIDER_KEY)
+  await registry.sync()
+  return mapOrder(status.order, registry.require(status.order.order.coin))
+}