@lifi/perps-sdk-provider-hyperliquid 30.0.2 → 31.0.0

package/src/services/getOrders.ts

@@ -12,7 +12,6 @@ import type {
   HlFrontendOpenOrders,
   HlHistoricalOrders,
   HlTwapHistoryEntry,
-  HlTwapSliceFill,
 } from '../types/index.js'
 import { withExplorerLinks } from '../utils/explorer.js'
 import { mapOrder, perpsDexNames } from '../utils/index.js'
@@ -23,6 +22,7 @@ import {
   resolveTwapExecution,
 } from '../utils/twapHistory.js'
 import { requireAccountExists } from './getAccountExists.js'
+import { fetchTwapSliceFills } from './twapSliceFills.js'
 
 /** Parameters for a lifecycle-filtered Hyperliquid order read. */
 export type GetOrdersParams = ProviderGetOrdersParams
@@ -78,16 +78,8 @@ export const getOrders = async (
   ])
   const latestTwaps = resolveLatestTwapEntries(twaps)
   const sliceFills =
-    (active || statuses.includes(OrderStatus.FILLED)) &&
-    latestTwaps.some(
-      (entry) =>
-        entry.twapId !== undefined && entry.status.status === 'activated'
-    )
-      ? await infoRequest<HlTwapSliceFill[]>(
-          apiUrl,
-          { type: 'userTwapSliceFills', user: params.address },
-          infoOpts
-        )
+    active || statuses.includes(OrderStatus.FILLED)
+      ? await fetchTwapSliceFills(apiUrl, params.address, latestTwaps, infoOpts)
       : []
   const rows = new Map<string, Order>()
   const keep = (key: string, order: Order | undefined): void => {

package/src/services/twapSliceFills.ts

@@ -0,0 +1,65 @@
+import type { Address } from 'viem'
+import type { HlTwapHistoryEntry, HlTwapSliceFill } from '../types/index.js'
+import { type InfoRequestOptions, infoRequest } from '../utils/infoClient.js'
+import { historyPage } from './historyPagination.js'
+
+/** Row cap of both `userTwapSliceFills` and `userTwapSliceFillsByTime`. */
+const TWAP_SLICE_FILLS_CAP = 2000
+
+/**
+ * Read the slice fills of each `activated` TWAP in `entries`, or none without
+ * a request when no entry is `activated`. `userTwapSliceFills` holds only the
+ * newest rows of the account, so a full window that does not reach back to a
+ * TWAP start gets its older rows from `userTwapSliceFillsByTime`.
+ */
+export const fetchTwapSliceFills = async (
+  apiUrl: string,
+  user: Address,
+  entries: readonly HlTwapHistoryEntry[],
+  options?: InfoRequestOptions
+): Promise<HlTwapSliceFill[]> => {
+  const starts = entries.flatMap((entry) =>
+    entry.twapId !== undefined && entry.status.status === 'activated'
+      ? [entry.state.timestamp]
+      : []
+  )
+  if (starts.length === 0) {
+    return []
+  }
+  const window = await infoRequest<HlTwapSliceFill[]>(
+    apiUrl,
+    { type: 'userTwapSliceFills', user },
+    options
+  )
+  if (window.length < TWAP_SLICE_FILLS_CAP) {
+    return window
+  }
+  const oldest = Math.min(...window.map(({ fill }) => fill.time))
+  const startTime = Math.min(...starts)
+  if (startTime > oldest) {
+    return window
+  }
+  // The window can end inside its oldest millisecond, so read that millisecond again.
+  const older = await historyPage(
+    { startTime, endTime: oldest },
+    Number.MAX_SAFE_INTEGER,
+    async (rangeStart, rangeEnd) => {
+      const fills = await infoRequest<HlTwapSliceFill[]>(
+        apiUrl,
+        {
+          type: 'userTwapSliceFillsByTime',
+          user,
+          startTime: rangeStart,
+          endTime: rangeEnd,
+        },
+        options
+      )
+      return fills.length >= TWAP_SLICE_FILLS_CAP
+        ? { items: [], saturated: true }
+        : { items: fills, saturated: false }
+    },
+    ({ fill }) => ({ time: fill.time, key: fill.tid }),
+    options?.signal
+  )
+  return [...window.filter(({ fill }) => fill.time > oldest), ...older.items]
+}

package/src/types/account.ts

@@ -18,8 +18,11 @@ export type HlPosition = {
   entryPx: string
   /** Position notional value as a decimal string. */
   positionValue: string
-  /** Estimated liquidation price; may be an empty string when unavailable. */
-  liquidationPx: string
+  /**
+   * Estimated liquidation price. `null` when no price liquidates the
+   * position, which Hyperliquid reports for a cross position.
+   */
+  liquidationPx: string | null
   /** Unrealized PnL in quote-asset units. */
   unrealizedPnl: string
   /** Margin currently assigned to this position. */

package/src/types/fill.ts

@@ -55,8 +55,10 @@ export type HlUserFills = HlUserFill[]
 export type HlUserFillsByTime = HlUserFill[]
 
 /**
- * One row of the `userTwapSliceFills` query: a fill that a TWAP slice made.
- * The venue returns at most 2,000 recent rows, newest first.
+ * One row of the `userTwapSliceFills` or `userTwapSliceFillsByTime` query: a
+ * fill that a TWAP slice made. Each query returns at most 2,000 rows:
+ * `userTwapSliceFills` the newest, newest first, and `userTwapSliceFillsByTime`
+ * the oldest of its inclusive range, oldest first.
  * @public
  */
 export type HlTwapSliceFill = {

package/src/utils/isFillLiquidatingAccount.ts

@@ -0,0 +1,12 @@
+import type { HlUserFill } from '../types/index.js'
+
+/**
+ * Whether the fill liquidates `address`. Hyperliquid attaches `liquidation` to
+ * the fills of both parties, so only a fill whose `liquidatedUser` is the
+ * address counts. The address compare ignores case.
+ */
+export const isFillLiquidatingAccount = (
+  fill: Pick<HlUserFill, 'liquidation'>,
+  address: string
+): boolean =>
+  fill.liquidation?.liquidatedUser.toLowerCase() === address.toLowerCase()

package/src/utils/liquidation.ts

@@ -16,10 +16,17 @@ import {
   createSafeFunction,
   divideDecimalString,
   estimateLiquidationPrice,
+  type LiquidationEstimateParams,
   numberToDecimalString,
   PerpsError,
+  subtractDecimalString,
 } from '@lifi/perps-sdk'
-import { type DecimalString, PerpsErrorCode } from '@lifi/perps-types'
+import {
+  type DecimalString,
+  MarginMode,
+  PerpsErrorCode,
+  PositionSide,
+} from '@lifi/perps-types'
 
 /**
  * Maintenance margin fraction for a Hyperliquid asset: half of the initial
@@ -50,34 +57,54 @@ export const safeCalculateMaintenanceMarginRate = createSafeFunction(
 )
 
 /**
- * Liquidation price of a new isolated position with the exact Hyperliquid
- * formula. For an existing position, prefer `Position.liquidationPrice` from
- * the API.
- *
- * Formula derivation (isolated margin, single position):
- *   margin_available = entryPrice × (1 / leverage - mmr)
- *   liq_price        = entryPrice - side × margin_available / (1 - mmr × side)
+ * Liquidation price of the isolated position that an order leaves, with the
+ * exact Hyperliquid formula: a new position, or the blend of the order into
+ * `params.position`. Hyperliquid isolated `marginUsed` includes the
+ * unrealized PnL, so the collateral of the position is `marginUsed` minus
+ * `unrealizedPnl`. For an existing position, prefer
+ * `Position.liquidationPrice` from the API.
  *
- * @param leverage - User-selected leverage (e.g., `'10'`)
  * @param maxLeverage - Asset's maximum leverage (e.g., 50 for BTC). Sets
  *   mmr = 1 / (2 × maxLeverage).
- * @returns The estimate, or `undefined` when `leverage` is at or above
- *   `2 × maxLeverage`, as {@link estimateLiquidationPrice} documents.
+ * @returns The estimate, or `undefined` when the order or the position is
+ *   cross (the liquidation depends on the whole account), when the order
+ *   reduces the position, or when `leverage` is at or above `2 × maxLeverage`,
+ *   as {@link estimateLiquidationPrice} documents.
  * @throws {PerpsError} `ValidationError` when `maxLeverage` is not a finite
  *   number above zero, or on an input that `estimateLiquidationPrice` rejects.
  * @public
  */
 export function calculateLiquidationPrice(
-  entryPrice: string,
-  leverage: string,
-  isLong: boolean,
+  params: LiquidationEstimateParams,
   maxLeverage: number
 ): string | undefined {
+  const { position } = params
+  if (
+    params.marginMode === MarginMode.CROSS ||
+    position?.marginMode === MarginMode.CROSS ||
+    (position !== undefined &&
+      (position.side === PositionSide.LONG) !== params.isLong)
+  ) {
+    return undefined
+  }
   return estimateLiquidationPrice({
-    entryPrice,
-    leverage,
-    isLong,
+    entryPrice: params.entryPrice,
+    leverage: params.leverage,
+    isLong: params.isLong,
     maintenanceMarginRate: calculateMaintenanceMarginRate(maxLeverage),
+    size: params.size,
+    ...(position === undefined
+      ? {}
+      : {
+          current: {
+            size: position.size,
+            entryPrice: position.entryPrice,
+            margin: subtractDecimalString(
+              position.marginUsed,
+              position.unrealizedPnl
+            ),
+          },
+        }),
   })
 }
 

package/src/utils/mapActivity.ts

@@ -38,6 +38,7 @@ import {
   isVaultTransferDelta,
   isWithdrawDelta,
 } from '../types/index.js'
+import { isFillLiquidatingAccount } from './isFillLiquidatingAccount.js'
 import { rowTimestampToIsoStringOrUndefined } from './rowTimestamp.js'
 
 /**
@@ -371,11 +372,10 @@ export const mapLiquidationFills = (
   resolveMarket: (coin: string) => MarketDisplay | undefined,
   ledgerHashes: ReadonlySet<string>
 ): LiquidationActivity[] => {
-  const queried = queriedAddress.toLowerCase()
   const byOrder = new Map<number, HlUserFill[]>()
   for (const fill of fills) {
     if (
-      fill.liquidation?.liquidatedUser.toLowerCase() !== queried ||
+      !isFillLiquidatingAccount(fill, queriedAddress) ||
       (fill.hash !== undefined && ledgerHashes.has(fill.hash))
     ) {
       continue

package/src/utils/mapFill.ts

@@ -4,29 +4,60 @@ import {
   explorerTxUrl,
   warnSkippedVenueRow,
 } from '@lifi/perps-sdk'
-import type { Fill, MarketDisplay } from '@lifi/perps-types'
+import type { Fill, FillLiquidation, MarketDisplay } from '@lifi/perps-types'
 import {
   FillClassification,
+  LiquidationMethod,
   LiquidityRole,
   OrderSide,
-  OrderType,
 } from '@lifi/perps-types'
 import { PROVIDER_KEY, SPOT_MARKET_ID } from '../constants.js'
-import type { HlUserFill } from '../types/index.js'
+import type { HlFillLiquidation, HlUserFill } from '../types/index.js'
 import { rowTimestampToIsoStringOrUndefined } from './rowTimestamp.js'
 
 /** Re-export the shared fill-position classifier used by Hyperliquid mappings. @public */
 export { classifyFillFromPosition }
 
-/**
- * Spot-ness comes from the resolved market's category, not the coin string —
- * HL's canonical spot pair 0 is addressed as `PURR/USDC`, not `@0`. A fill with
- * an invalid time gives `undefined`.
+const mapLiquidationMethod = (
+  method: string
+): LiquidationMethod | undefined => {
+  switch (method) {
+    case 'market':
+      return LiquidationMethod.MARKET
+    case 'backstop':
+      return LiquidationMethod.BACKSTOP
+    default:
+      return undefined
+  }
+}
+
+// Hyperliquid attaches `liquidation` to the fills of both parties.
+const mapFillLiquidation = (
+  liquidation: HlFillLiquidation | undefined,
+  address: string
+): FillLiquidation | undefined => {
+  if (
+    liquidation === undefined ||
+    liquidation.liquidatedUser.toLowerCase() !== address.toLowerCase()
+  ) {
+    return undefined
+  }
+  const method = mapLiquidationMethod(liquidation.method)
+  return {
+    ...(method === undefined ? {} : { method }),
+    markPrice: liquidation.markPx,
+  }
+}
+
+/** Maps a fill using the market category; the order type stays absent.
+ * Invalid times return `undefined`. The venue does not report the order type.
+ * @param address - Fill owner; only the liquidated account carries `liquidation`.
  * @public
  */
 export const mapFill = (
   fill: HlUserFill,
-  market: MarketDisplay
+  market: MarketDisplay,
+  address: string
 ): Fill | undefined => {
   const size = fill.sz
   const createdAt = rowTimestampToIsoStringOrUndefined(fill.time)
@@ -40,6 +71,7 @@ export const mapFill = (
   // HL charges the builder portion in the same token as the total fee.
   const feeAsset = fill.feeToken ?? market.quoteAsset.displaySymbol
   const side = fill.side === 'B' ? OrderSide.BUY : OrderSide.SELL
+  const liquidation = mapFillLiquidation(fill.liquidation, address)
 
   return {
     ...(market.categoryId === SPOT_MARKET_ID
@@ -50,11 +82,6 @@ export const mapFill = (
     clientOrderId: fill.cloid,
     market,
     side,
-    // HL fills don't carry the originating order type. A maker fill (crossed:
-    // false) can only come from a resting order, so it's necessarily a limit;
-    // a taker fill (crossed: true) may be a market OR an aggressive limit order,
-    // which the payload can't distinguish, so the type is left undefined.
-    type: fill.crossed ? undefined : OrderType.LIMIT,
     size,
     price: fill.px,
     liquidity: fill.crossed ? LiquidityRole.TAKER : LiquidityRole.MAKER,
@@ -76,5 +103,6 @@ export const mapFill = (
           : FillClassification.SPOT_SELL
         : classifyFillFromPosition(fill.startPosition, side, size),
     createdAt,
+    ...(liquidation === undefined ? {} : { liquidation }),
   }
 }

package/src/utils/mapOrder.ts

@@ -388,5 +388,11 @@ export const mapOrder = (
     default:
       throw venueError(`Unknown Hyperliquid time in force: ${o.tif}`)
   }
-  return { ...base, type, price: o.limitPx, timeInForce }
+  return {
+    ...base,
+    type,
+    price: o.limitPx,
+    timeInForce,
+    ...(o.tif === 'LiquidationMarket' ? { isLiquidation: true } : {}),
+  }
 }

package/src/utils/mapPosition.ts

@@ -43,7 +43,7 @@ export const isOpenAssetPosition = (ap: HlAssetPosition): boolean =>
  * Hyperliquid signs funding paid as positive and `accruedFunding` signs it as
  * negative. A row with an invalid size gives `undefined`; an invalid position
  * value, a non-positive leverage or an invalid funding leaves the derived field
- * absent.
+ * absent, and a `null` or empty `liquidationPx` leaves `liquidationPrice` absent.
  * @public
  */
 export const mapPosition = (
@@ -93,7 +93,7 @@ export const mapPosition = (
     size,
     entryPrice: pos.entryPx ?? '0',
     ...(markPrice === undefined ? {} : { markPrice }),
-    liquidationPrice: pos.liquidationPx || '0',
+    ...(pos.liquidationPx ? { liquidationPrice: pos.liquidationPx } : {}),
     unrealizedPnl: pos.unrealizedPnl,
     ...(accruedFunding === undefined ? {} : { accruedFunding }),
     ...(leverage === undefined ? {} : { leverage }),

package/src/websocket/HyperliquidWsProvider.ts

@@ -1243,7 +1243,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
             return []
           }
           const market = this.registry?.get(f.coin)
-          const mapped = market && mapFill(f as HlUserFill, market)
+          const mapped = market && mapFill(f as HlUserFill, market, data.user)
           return mapped ? [mapped] : []
         })
     this.emit(`userFills:${data.user.toLowerCase()}`, {