@lifi/perps-sdk-provider-hyperliquid 20.0.0 → 21.0.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/getWithdrawableBalances.ts

@@ -89,6 +89,6 @@ export const getWithdrawableBalances = async (
     state,
     spotState,
     quoteAsset.id,
-    feeUsd === undefined ? undefined : String(feeUsd)
+    feeUsd
   )
 }

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/utils/index.ts

@@ -45,9 +45,9 @@ export {
 export { isOpenAssetPosition, mapPosition } from './mapPosition.js'
 export { coinAsset, perpsDexNames } from './marketDisplay.js'
 export {
-  formatOrderPrice,
-  formatOrderSize,
   getMaxPriceDecimals,
+  snapOrderPrice,
+  snapOrderSize,
 } from './orderFormatting.js'
 export { priceStepToAggregation } from './priceStepToAggregation.js'
 export {

package/src/utils/liquidation.ts

@@ -12,7 +12,7 @@
  * - margin_available = isolated_margin - maintenance_margin_required
  */
 
-import { estimateIsolatedLiquidationPrice } from '@lifi/perps-sdk'
+import { estimateLiquidationPrice } from '@lifi/perps-sdk'
 
 /**
  * Calculate the maintenance margin fraction for a Hyperliquid asset.
@@ -65,7 +65,7 @@ export function calculateLiquidationPrice(
   if (mmr === undefined) {
     return undefined
   }
-  return estimateIsolatedLiquidationPrice({
+  return estimateLiquidationPrice({
     entryPrice,
     leverage,
     isLong,

package/src/utils/orderFormatting.ts

@@ -1,12 +1,13 @@
 /**
- * Hyperliquid order size and price formatting for exchange submission.
+ * Hyperliquid order size and price snapping for exchange submission.
  *
- * These encode Hyperliquid-specific order submission rules. Getting size/price
- * formatting wrong causes rejected orders.
+ * These encode Hyperliquid-specific order submission rules. Snapping a size or
+ * a price onto the wrong grid causes rejected orders.
  *
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size
  */
 
+import type { DecimalString } from '@lifi/perps-types'
 import Big from 'big.js'
 
 /**
@@ -36,28 +37,30 @@ export function getMaxPriceDecimals(
 }
 
 /**
- * Format a size value for order submission.
+ * Snap a size onto the asset's lot grid for order submission.
  *
  * Per Hyperliquid docs (tick-and-lot-size):
  * - Size must be rounded to the asset's szDecimals
  * - Trailing zeroes must be removed for signing
  *
- * @param size - The size value to format
+ * @param size - The size to snap, as a decimal string
  * @param szDecimals - Number of decimal places allowed for this asset (from meta)
- * @returns Size as a string with correct precision, no trailing zeros
+ * @returns Size as a decimal string with correct precision, no trailing zeros
  * @public
  */
-export function formatOrderSize(size: number, szDecimals: number): string {
+export function snapOrderSize(
+  size: DecimalString,
+  szDecimals: number
+): DecimalString {
   // Big.roundDown truncates toward zero — never round a size up, it could
-  // exceed available balance. Exact decimal arithmetic: flooring the float
-  // product dropped a lot step (0.29 * 100 === 28.999999999999996).
+  // exceed available balance.
   const truncated = new Big(size).round(szDecimals, Big.roundDown)
   // toFixed() with no dp always emits plain notation; eq(0) guards '-0'
   return truncated.eq(0) ? '0' : truncated.toFixed()
 }
 
 /**
- * Format a price value for order submission.
+ * Snap a price onto the asset's tick grid for order submission.
  *
  * Per Hyperliquid docs (tick-and-lot-size):
  * - Maximum 5 significant figures
@@ -66,19 +69,20 @@ export function formatOrderSize(size: number, szDecimals: number): string {
  * - Trailing zeroes must be removed for signing
  *
  * Rounding is half-up (away from zero at exact halfway) on the true decimal
- * value, not on the binary float — (1.005).toFixed(2) would give '1.00'.
+ * value, which is why the price arrives as a string: `(1.005).toFixed(2)`
+ * would give `'1.00'`.
  *
- * @param price - The price value to format
+ * @param price - The price to snap, as a decimal string
  * @param szDecimals - The asset's szDecimals (affects max price decimals)
  * @param market - Optional market type (e.g. 'spot'). Defaults to perps rules.
- * @returns Price as a string with correct precision, no trailing zeros
+ * @returns Price as a decimal string with correct precision, no trailing zeros
  * @public
  */
-export function formatOrderPrice(
-  price: number,
+export function snapOrderPrice(
+  price: DecimalString,
   szDecimals: number,
   market?: string
-): string {
+): DecimalString {
   const maxPriceDecimals = getMaxPriceDecimals(szDecimals, market)
 
   let rounded = new Big(price).round(maxPriceDecimals, Big.roundHalfUp)

package/src/utils/spotBalance.ts

@@ -1,4 +1,4 @@
-import { stringToFloat } from '@lifi/perps-sdk'
+import { numberToDecimalString, parseDecimal } from '@lifi/perps-sdk'
 import type { Asset, Balance, Market } from '@lifi/perps-types'
 import { SPOT_MARKET_ID } from '../constants.js'
 import type { HlSpotBalance } from '../types/index.js'
@@ -52,8 +52,10 @@ export const spotBalance = (
     categoryId: SPOT_MARKET_ID,
     asset,
     units: total,
-    valueUsd: (stringToFloat(total) * price).toString(),
+    valueUsd: numberToDecimalString(
+      (parseDecimal(total) ?? Number.NaN) * price
+    ),
     // A zero entry means the map holds no mark for the asset, not a free asset.
-    ...(price > 0 ? { price: price.toString() } : {}),
+    ...(price > 0 ? { price: numberToDecimalString(price) } : {}),
   }
 }

package/src/utils/withdrawableBalances.ts

@@ -1,4 +1,7 @@
-import type { ProviderWithdrawableBalance } from '@lifi/perps-sdk'
+import {
+  calculateWithdrawMax,
+  type ProviderWithdrawableBalance,
+} from '@lifi/perps-sdk'
 import type {
   HlAbstractionMode,
   HlClearinghouseState,
@@ -50,24 +53,26 @@ export const hyperliquidWithdrawableBalances = (
       )
       if (spot.gt(0)) {
         const assetId = String(balance.token)
-        rows.push({
+        const row = {
           assetId,
-          route: 'spot',
+          route: 'spot' as const,
           available: spot.toFixed(),
           ...feeFor(assetId),
-        })
+        }
+        rows.push({ ...row, max: calculateWithdrawMax(row) })
       }
     }
   }
 
   const perps = toWireBig(state.withdrawable, 'clearinghouseState.withdrawable')
   if (perps.gt(0)) {
-    rows.push({
+    const row = {
       assetId: quoteAssetId,
-      route: 'perps',
+      route: 'perps' as const,
       available: perps.toFixed(),
       ...feeFor(quoteAssetId),
-    })
+    }
+    rows.push({ ...row, max: calculateWithdrawMax(row) })
   }
 
   return rows