@lifi/perps-sdk-provider-hyperliquid 19.0.0 → 20.1.0

package/src/services/getFills.ts

@@ -1,19 +1,12 @@
 import { getMarketRegistry, type SDKRequestOptions } from '@lifi/perps-sdk'
 import type { Fill, FillsResponse } from '@lifi/perps-types'
 import type { Address } from 'viem'
-import {
-  DEFAULT_HISTORY_LIMIT,
-  MAX_HISTORY_LIMIT,
-  PROVIDER_KEY,
-} from '../constants.js'
+import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
-import type {
-  HlUserFill,
-  HlUserFills,
-  HlUserFillsByTime,
-} from '../types/index.js'
+import type { HlUserFills } from '../types/index.js'
 import { assetIsOutcome, mapFill } from '../utils/index.js'
 import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+import { getHistoryLimit, historyPage } from './historyPagination.js'
 
 /**
  * Parameters for {@link getFills}.
@@ -22,7 +15,7 @@ import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
  */
 export interface GetFillsParams {
   address: Address
-  /** Maximum items returned; defaults to 50 and is capped at 200. */
+  /** Positive safe integer; defaults to 50 and is capped at 200. */
   limit?: number
   /** Opaque cursor returned in the previous page's `pagination.cursor`. */
   cursor?: string
@@ -32,101 +25,55 @@ export interface GetFillsParams {
   endTime?: number
 }
 
-interface FillCursor {
-  time: number
-  tid: number
-}
-
-// HL's docs specify neither newest-first ordering nor monotonic `tid` for
-// `userFills`/`userFillsByTime`, so pagination can't rely on upstream order —
-// it must impose its own (time desc, tid desc as tiebreaker for same-time fills).
-const compareFillsDesc = (a: FillCursor, b: FillCursor): number =>
-  b.time - a.time || b.tid - a.tid
-
-const encodeCursor = (fill: FillCursor): string => `${fill.time}:${fill.tid}`
-
-const decodeCursor = (cursor: string): FillCursor => {
-  const [time, tid] = cursor.split(':').map(Number)
-  return { time, tid }
-}
-
-/**
- * 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.
- *
- * The response is sorted (time desc, `tid` as tiebreaker) before pagination —
- * see {@link compareFillsDesc}. The cursor encodes the last returned fill's
- * `(time, tid)`; the next page keeps fills that sort strictly after it.
- * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
- * @public
- */
+/** Fetch retained fills newest-first, using opaque cursors across inclusive time ranges. */
 export const getFills = async (
   { client, apiUrl }: HyperliquidContext,
   params: GetFillsParams,
   options?: SDKRequestOptions
 ): Promise<FillsResponse> => {
+  const limit = getHistoryLimit(params.limit)
   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>(
+  let useRecent =
+    params.cursor === undefined &&
+    params.startTime === undefined &&
+    params.endTime === undefined
+  const page = await historyPage(
+    params,
+    limit,
+    async (startTime, endTime) => {
+      const fills = await infoRequest<HlUserFills>(
         apiUrl,
-        { type: 'userFills', user: params.address },
+        useRecent
+          ? { type: 'userFills', user: params.address }
+          : {
+              type: 'userFillsByTime',
+              user: params.address,
+              startTime,
+              endTime,
+            },
         infoOpts
       )
-
-  const sorted = [...allFills].sort(compareFillsDesc)
-
-  const filtered =
-    params.cursor === undefined
-      ? sorted
-      : sorted.filter(
-          (f) => compareFillsDesc(f, decodeCursor(params.cursor!)) > 0
-        )
-
-  const hasMore = filtered.length > limit
-  const page = filtered.slice(0, limit)
-  // `get`, not `require`: a coin the backend market list does not hold drops
-  // only its own row instead of rejecting the whole page. The registry warns
-  // once per unresolved id. A delisted market still resolves, so its rows stay.
-  const items = page.flatMap((f): Fill[] => {
-    if (assetIsOutcome(f.coin)) {
-      return []
-    }
-    const market = registry.get(f.coin)
-    return market === undefined ? [] : [mapFill(f, market)]
-  })
-  const lastPageFill: HlUserFill | undefined = page[page.length - 1]
-
-  return {
-    provider: PROVIDER_KEY,
-    items,
-    pagination: {
-      limit,
-      hasMore,
-      cursor: lastPageFill ? encodeCursor(lastPageFill) : undefined,
+      useRecent = false
+      if (fills.length >= 2000) {
+        return { items: [], saturated: true }
+      }
+      const items = fills.flatMap((fill): Fill[] => {
+        if (assetIsOutcome(fill.coin)) {
+          return []
+        }
+        const market = registry.get(fill.coin)
+        return market === undefined ? [] : [mapFill(fill, market)]
+      })
+      return { items, saturated: false }
     },
-  }
+    (fill) => ({
+      time: new Date(fill.createdAt).getTime(),
+      key: Number(fill.id),
+    }),
+    options?.signal
+  )
+  return { provider: PROVIDER_KEY, ...page }
 }

package/src/services/getMarketSettings.ts

@@ -1,11 +1,12 @@
-import type { SDKRequestOptions } from '@lifi/perps-sdk'
+import { PerpsError, type SDKRequestOptions } from '@lifi/perps-sdk'
 import {
   MarginMode,
   type MarketRef,
   type MarketSettings,
+  PerpsErrorCode,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
-import { SPOT_MARKET_ID } from '../constants.js'
+import { PROVIDER_KEY, SPOT_MARKET_ID } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import { fetchActiveAssetData } from './activeAssetData.js'
 
@@ -22,17 +23,23 @@ export interface GetMarketSettingsParams {
 /**
  * The user's venue-stored margin mode and leverage for one perps market,
  * read from `activeAssetData` — present whether or not a position is open.
- * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
+ * @throws {PerpsError} `ValidationError` for a spot market; `SDKError` when
+ *   the response carries no positive leverage; any other `PerpsError` on
+ *   Hyperliquid REST error, network, or parsing failures.
  * @public
  */
 export const getMarketSettings = async (
   context: HyperliquidContext,
   params: GetMarketSettingsParams,
   options?: SDKRequestOptions
-): Promise<MarketSettings | undefined> => {
-  // Spot markets carry no leverage state on the venue.
+): Promise<MarketSettings> => {
   if (params.market.categoryId === SPOT_MARKET_ID) {
-    return undefined
+    const error = new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Hyperliquid market '${params.market.marketId}' is a spot market and carries no leverage setting`
+    )
+    error.tool = PROVIDER_KEY
+    throw error
   }
   const data = await fetchActiveAssetData(
     context,
@@ -41,8 +48,13 @@ export const getMarketSettings = async (
     options
   )
   const leverage = data.leverage
-  if (!leverage) {
-    return undefined
+  if (!leverage || !(leverage.value > 0)) {
+    const error = new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Hyperliquid returned no leverage for market '${params.market.marketId}'`
+    )
+    error.tool = PROVIDER_KEY
+    throw error
   }
   return {
     marginMode:

package/src/services/historyPagination.ts

@@ -0,0 +1,169 @@
+import { PerpsError } from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT } from '../constants.js'
+
+type HistoryKey = string | number
+interface HistoryBoundary {
+  time: number
+  key: HistoryKey
+  startTime: number
+  endTime: number
+}
+
+const compareKeys = (a: HistoryKey, b: HistoryKey): number =>
+  typeof a === 'number' && typeof b === 'number'
+    ? b - a
+    : a < b
+      ? 1
+      : a > b
+        ? -1
+        : 0
+
+export const getHistoryLimit = (limit = DEFAULT_HISTORY_LIMIT): number => {
+  if (!Number.isSafeInteger(limit) || limit < 1) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      'Hyperliquid history limit must be a positive safe integer'
+    )
+  }
+  return Math.min(limit, MAX_HISTORY_LIMIT)
+}
+
+const decodeCursor = (cursor: string): HistoryBoundary => {
+  let value: unknown
+  try {
+    value = JSON.parse(cursor)
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      'Invalid Hyperliquid history cursor'
+    )
+  }
+  if (
+    !Array.isArray(value) ||
+    value.length !== 4 ||
+    !Number.isSafeInteger(value[0]) ||
+    (typeof value[1] !== 'string' && typeof value[1] !== 'number') ||
+    !Number.isSafeInteger(value[2]) ||
+    value[2] > value[0] ||
+    !Number.isSafeInteger(value[3]) ||
+    value[3] < value[0]
+  ) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      'Invalid Hyperliquid history cursor'
+    )
+  }
+  return {
+    time: value[0],
+    key: value[1],
+    startTime: value[2],
+    endTime: value[3],
+  }
+}
+
+export async function historyPage<T>(
+  params: { startTime?: number; endTime?: number; cursor?: string },
+  limit: number,
+  fetchWindow: (
+    startTime: number,
+    endTime: number,
+    snapshotEnd: number
+  ) => Promise<{ items: T[]; saturated: boolean }>,
+  identify: (item: T) => { time: number; key: HistoryKey },
+  signal?: AbortSignal
+): Promise<{
+  items: T[]
+  pagination: { limit: number; hasMore: boolean; cursor?: string }
+}> {
+  const boundary =
+    params.cursor === undefined ? undefined : decodeCursor(params.cursor)
+  const lower = params.startTime ?? 0
+  const snapshotEnd = boundary?.endTime ?? params.endTime ?? Date.now()
+  const upper = Math.min(snapshotEnd, boundary?.time ?? Infinity)
+  const windows: { startTime: number; endTime: number }[] = []
+  if (boundary && boundary.startTime > lower) {
+    windows.push({ startTime: lower, endTime: boundary.startTime - 1 })
+  }
+  windows.push({
+    startTime: Math.max(lower, boundary?.startTime ?? lower),
+    endTime: upper,
+  })
+  const items: T[] = []
+  let last: HistoryBoundary | undefined
+  while (windows.length > 0) {
+    signal?.throwIfAborted()
+    const window = windows.pop()!
+    if (window.startTime > window.endTime) {
+      continue
+    }
+    const result = await fetchWindow(
+      window.startTime,
+      window.endTime,
+      snapshotEnd
+    )
+    signal?.throwIfAborted()
+    if (result.saturated) {
+      if (window.startTime === window.endTime) {
+        throw new PerpsError(
+          PerpsErrorCode.ThirdPartyError,
+          'Hyperliquid history saturates a single millisecond; its time-only API cannot paginate this timestamp safely'
+        )
+      }
+      // Time APIs truncate from the start, so a capped response cannot supply a newest page.
+      const midpoint =
+        window.startTime + Math.floor((window.endTime - window.startTime) / 2)
+      windows.push({ startTime: window.startTime, endTime: midpoint })
+      windows.push({ startTime: midpoint + 1, endTime: window.endTime })
+      continue
+    }
+    const sorted = result.items.sort((a, b) => {
+      const left = identify(a)
+      const right = identify(b)
+      return right.time - left.time || compareKeys(left.key, right.key)
+    })
+    for (const item of sorted) {
+      const identity = identify(item)
+      if (identity.time < window.startTime || identity.time > window.endTime) {
+        continue
+      }
+      if (
+        boundary &&
+        (identity.time > boundary.time ||
+          (identity.time === boundary.time &&
+            compareKeys(identity.key, boundary.key) <= 0))
+      ) {
+        continue
+      }
+      if (items.length === limit) {
+        return {
+          items,
+          pagination: {
+            limit,
+            hasMore: true,
+            cursor:
+              last &&
+              JSON.stringify([
+                last.time,
+                last.key,
+                last.startTime,
+                last.endTime,
+              ]),
+          },
+        }
+      }
+      items.push(item)
+      last = { ...identity, startTime: window.startTime, endTime: snapshotEnd }
+    }
+  }
+  return {
+    items,
+    pagination: {
+      limit,
+      hasMore: false,
+      cursor:
+        last &&
+        JSON.stringify([last.time, last.key, last.startTime, last.endTime]),
+    },
+  }
+}

package/src/types/ledger.ts

@@ -130,6 +130,38 @@ export type HlLiquidationDelta = {
   liquidatedPositions?: HlLiquidatedPosition[]
 }
 
+/**
+ * Hyperliquid `cStakingTransfer` ledger delta. Moves `token` between the
+ * account's spot balance and its staking balance; `isDeposit` is `true` for a
+ * move into staking. `amount` is unsigned. A completed unstake row carries the
+ * zero hash.
+ * @public
+ */
+export type HlCStakingTransferDelta = {
+  type: 'cStakingTransfer'
+  token: string
+  amount: string
+  isDeposit: boolean
+}
+
+/** Borrow-lend market action named by a `borrowLend` ledger delta. @public */
+export type HlBorrowLendOperation = 'supply' | 'withdraw' | 'borrow' | 'repay'
+
+/**
+ * Hyperliquid `borrowLend` ledger delta. Moves `token` between the account's
+ * spot balance and the borrow-lend market; `operation` gives the direction and
+ * `amount` is unsigned. `interestAmount` is the accrued interest that
+ * `amount` includes on a `withdraw` or `repay`, and `"0.0"` otherwise.
+ * @public
+ */
+export type HlBorrowLendDelta = {
+  type: 'borrowLend'
+  token: string
+  operation: HlBorrowLendOperation
+  amount: string
+  interestAmount: string
+}
+
 /**
  * Union of known Hyperliquid non-funding ledger deltas plus an open fallback
  * for endpoint variants the provider does not map.
@@ -143,6 +175,8 @@ export type HlLedgerDelta =
   | HlDepositDelta
   | HlWithdrawDelta
   | HlLiquidationDelta
+  | HlCStakingTransferDelta
+  | HlBorrowLendDelta
   | {
       type: string
       usdc?: string
@@ -202,6 +236,33 @@ export const isLiquidationDelta = (
   delta: HlLedgerDelta
 ): delta is HlLiquidationDelta => delta.type === 'liquidation'
 
+/**
+ * Type guard for `HlCStakingTransferDelta`. `isDeposit` is part of the guard:
+ * a row without a boolean `isDeposit` names no direction for the movement.
+ * @public
+ */
+export const isCStakingTransferDelta = (
+  delta: HlLedgerDelta
+): delta is HlCStakingTransferDelta =>
+  delta.type === 'cStakingTransfer' &&
+  'isDeposit' in delta &&
+  typeof delta.isDeposit === 'boolean'
+
+const HL_BORROW_LEND_OPERATIONS: ReadonlySet<unknown> =
+  new Set<HlBorrowLendOperation>(['supply', 'withdraw', 'borrow', 'repay'])
+
+/**
+ * Type guard for `HlBorrowLendDelta`. The operation is part of the guard: an
+ * unknown operation names no direction for the movement.
+ * @public
+ */
+export const isBorrowLendDelta = (
+  delta: HlLedgerDelta
+): delta is HlBorrowLendDelta =>
+  delta.type === 'borrowLend' &&
+  'operation' in delta &&
+  HL_BORROW_LEND_OPERATIONS.has(delta.operation)
+
 /**
  * One timestamped non-funding ledger update. `time` is milliseconds since
  * epoch and `hash` is the upstream transaction identifier.

package/src/utils/mapActivity.ts

@@ -17,13 +17,17 @@ import type {
 } from '@lifi/perps-types'
 import { ActivityType, PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
+import { zeroHash } from 'viem'
 import type {
+  HlBorrowLendOperation,
   HlFundingUpdate,
   HlLedgerUpdate,
   HlUserFill,
 } from '../types/index.js'
 import {
+  isBorrowLendDelta,
   isCollateralTransferDelta,
+  isCStakingTransferDelta,
   isDepositDelta,
   isLiquidationDelta,
   isSendAssetDelta,
@@ -47,6 +51,17 @@ const HL_NATIVE_TOKEN_SYMBOL = 'HYPE'
 // Hyperliquid reserves spot token index 0 for USDC.
 const HL_COLLATERAL_ASSET_ID = '0'
 
+/**
+ * Direction relative to the account's spot balance, the same frame as an
+ * outbound `vaultDeposit`.
+ */
+const BORROW_LEND_DIRECTION: Record<HlBorrowLendOperation, 'IN' | 'OUT'> = {
+  supply: 'OUT',
+  withdraw: 'IN',
+  borrow: 'IN',
+  repay: 'OUT',
+}
+
 /**
  * A ledger row moves a spot asset — a perp contract cannot be sent, received
  * or withdrawn — so the delta's token symbol resolves inside the spot asset
@@ -69,6 +84,7 @@ const resolveLedgerAsset = (symbol: string, registry: AssetRegistry): Asset => {
 
 /**
  * Map supported ledger entries; exclude same-account moves and unsupported types.
+ * Staking and borrow-lend moves map with the queried account as counterparty.
  * Missing assets throw; unresolved liquidation markets omit only those positions.
  * @public
  */
@@ -143,6 +159,46 @@ export const mapLedgerEntry = (
     } satisfies TransferActivity
   }
 
+  if (isCStakingTransferDelta(delta) || isBorrowLendDelta(delta)) {
+    // A completed unstake is a system event with the zero hash and no venue
+    // transaction, so the id is synthesized and no explorer link applies.
+    const hasTransaction = entry.hash !== zeroHash
+    const direction = isCStakingTransferDelta(delta)
+      ? delta.isDeposit
+        ? 'OUT'
+        : 'IN'
+      : BORROW_LEND_DIRECTION[delta.operation]
+    const action = isCStakingTransferDelta(delta) ? direction : delta.operation
+    return {
+      ...base,
+      ...(hasTransaction
+        ? {}
+        : {
+            id: `${delta.type}:${delta.token}:${action}:${delta.amount}:${base.timestamp}`,
+          }),
+      type: ActivityType.TRANSFER,
+      direction,
+      counterpartyAddress: queriedAddress.toLowerCase(),
+      asset: resolveLedgerAsset(delta.token, assetRegistry),
+      amount: delta.amount,
+      meta: isCStakingTransferDelta(delta)
+        ? { transferType: delta.type }
+        : {
+            transferType: delta.type,
+            operation: delta.operation,
+            interestAmount: delta.interestAmount,
+          },
+      ...(hasTransaction
+        ? {
+            explorerLink: explorerTxUrl(
+              ExplorerChainId.HYPERLIQUID,
+              entry.hash
+            ),
+          }
+        : {}),
+    } satisfies TransferActivity
+  }
+
   if (isVaultTransferDelta(delta)) {
     const queried = queriedAddress.toLowerCase()
     const vault = delta.vault.toLowerCase()

package/src/utils/withdrawableBalances.ts

@@ -17,7 +17,8 @@ import { toWireBig } from './decimal.js'
  *
  * @param quoteAssetId - `Asset.id` the perps-route row is keyed by.
  * @param withdrawalFee - Flat venue fee in quote-asset units, set on every
- *   quote-asset row. Absent leaves every row without a fee.
+ *   quote-asset row. Hyperliquid deducts it from the requested amount. Absent
+ *   leaves every row without a fee.
  * @public
  */
 export const hyperliquidWithdrawableBalances = (
@@ -32,8 +33,12 @@ export const hyperliquidWithdrawableBalances = (
     withdrawalFee === undefined
       ? undefined
       : toWireBig(withdrawalFee, 'providers.withdrawalFeeUsd').toFixed()
-  const feeFor = (assetId: string) =>
-    fee === undefined || assetId !== quoteAssetId ? {} : { withdrawalFee: fee }
+  const feeFor = (
+    assetId: string
+  ): Pick<ProviderWithdrawableBalance, 'withdrawalFee' | 'isFeeDeducted'> =>
+    fee === undefined || assetId !== quoteAssetId
+      ? {}
+      : { withdrawalFee: fee, isFeeDeducted: true }
 
   if (isUnifiedAbstraction(abstraction)) {
     for (const balance of spotState.balances) {