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

package/src/services/getOrder.ts

@@ -15,8 +15,12 @@ import type {
 import { withExplorerLinks } from '../utils/explorer.js'
 import { assetIsOutcome, mapOrder } from '../utils/index.js'
 import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
-import { resolveLatestTwapEntries } from '../utils/twapHistory.js'
+import {
+  resolveLatestTwapEntries,
+  resolveTwapExecution,
+} from '../utils/twapHistory.js'
 import { requireAccountExists } from './getAccountExists.js'
+import { fetchTwapSliceFills } from './twapSliceFills.js'
 
 /**
  * Parameters for {@link getOrder}.
@@ -78,9 +82,16 @@ export const getOrder = async (
         String(entry.twapId) === params.id && !assetIsOutcome(entry.state.coin)
     )
     if (twap !== undefined) {
+      const sliceFills = await fetchTwapSliceFills(
+        apiUrl,
+        params.address,
+        [twap],
+        infoOpts
+      )
+      const [resolved] = resolveTwapExecution([twap], sliceFills)
       const registry = getMarketRegistry(client, PROVIDER_KEY)
       await registry.sync()
-      const order = mapOrder(twap, registry.require(twap.state.coin))
+      const order = mapOrder(resolved, registry.require(twap.state.coin))
       if (order === undefined) {
         throw orderNotFound(params.id)
       }

package/src/services/getOrders.ts

@@ -5,7 +5,7 @@ import {
   type ProviderGetOrdersParams,
   type SDKRequestOptions,
 } from '@lifi/perps-sdk'
-import type { Order, OrdersResponse } from '@lifi/perps-types'
+import { type Order, OrderStatus, type OrdersResponse } from '@lifi/perps-types'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import type {
@@ -17,8 +17,12 @@ import { withExplorerLinks } from '../utils/explorer.js'
 import { mapOrder, perpsDexNames } from '../utils/index.js'
 import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
 import { mapOrderRow } from '../utils/mapOrder.js'
-import { resolveLatestTwapEntries } from '../utils/twapHistory.js'
+import {
+  resolveLatestTwapEntries,
+  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
@@ -72,6 +76,11 @@ export const getOrders = async (
       infoOpts
     ),
   ])
+  const latestTwaps = resolveLatestTwapEntries(twaps)
+  const sliceFills =
+    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 => {
     if (order !== undefined) {
@@ -117,7 +126,7 @@ export const getOrders = async (
     }
   }
   // TWAP ids and regular order ids occupy separate venue namespaces.
-  for (const twap of resolveLatestTwapEntries(twaps)) {
+  for (const twap of resolveTwapExecution(latestTwaps, sliceFills)) {
     keep(
       `twap:${twap.twapId}`,
       mapOrderRow(twap.state.coin, registry, (market) => mapOrder(twap, market))

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

@@ -53,3 +53,15 @@ export type HlUserFills = HlUserFill[]
 
 /** Fills returned by the time-bounded `userFillsByTime` query. @public */
 export type HlUserFillsByTime = HlUserFill[]
+
+/**
+ * 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 = {
+  fill: HlUserFill
+  twapId: number
+}

package/src/types/ledger.ts

@@ -18,7 +18,7 @@ export type HlSpotTransferDelta = {
   destination: Address
   fee?: string
   nativeTokenFee?: string
-  nonce?: number
+  nonce?: number | null
 }
 
 /**

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

@@ -239,14 +239,20 @@ export const mapOrder = (
     if (updatedAt === undefined) {
       return skipOrder(market.id, 'time', raw.time)
     }
+    const hasRemaining =
+      safeIsDecimalStringGreaterThan(remainingSize, '0') === true
     let status: OrderStatus
     let statusReason: string | undefined
     switch (raw.status.status) {
       case 'activated':
-        status =
-          safeIsDecimalStringGreaterThan(state.executedSz, '0') === true
-            ? OrderStatus.PARTIALLY_FILLED
-            : OrderStatus.OPEN
+        if (!hasRemaining) {
+          status = OrderStatus.FILLED
+        } else {
+          status =
+            safeIsDecimalStringGreaterThan(state.executedSz, '0') === true
+              ? OrderStatus.PARTIALLY_FILLED
+              : OrderStatus.OPEN
+        }
         break
       case 'waitingForTrigger':
         status = OrderStatus.OPEN
@@ -278,7 +284,7 @@ export const mapOrder = (
       type: OrderType.TWAP,
       side: state.side === 'B' ? OrderSide.BUY : OrderSide.SELL,
       originalSize: state.sz,
-      remainingSize,
+      remainingSize: hasRemaining ? remainingSize : '0',
       filledSize: state.executedSz,
       ...(averagePrice === undefined ? {} : { averagePrice }),
       reduceOnly: state.reduceOnly,
@@ -382,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/utils/twapHistory.ts

@@ -1,4 +1,8 @@
-import type { HlTwapHistoryEntry } from '../types/index.js'
+import {
+  safeAddDecimalStrings,
+  safeCalculateNotionalValue,
+} from '@lifi/perps-sdk'
+import type { HlTwapHistoryEntry, HlTwapSliceFill } from '../types/index.js'
 
 /**
  * Keep the newest `twapHistory` row of each TWAP, in first-seen id order. The
@@ -16,3 +20,44 @@ export const resolveLatestTwapEntries = (
   }
   return [...latest.values()]
 }
+
+/**
+ * Take the executed size and notional of each `activated` row from the slice
+ * fills of its `twapId`. The venue writes that row once, at activation. A row
+ * with no slice fill, or with a slice fill that does not read, keeps its state.
+ */
+export const resolveTwapExecution = (
+  entries: readonly HlTwapHistoryEntry[],
+  sliceFills: readonly HlTwapSliceFill[]
+): HlTwapHistoryEntry[] => {
+  const fillsByTwap = new Map<number, HlTwapSliceFill['fill'][]>()
+  for (const { twapId, fill } of sliceFills) {
+    const fills = fillsByTwap.get(twapId)
+    if (fills === undefined) {
+      fillsByTwap.set(twapId, [fill])
+    } else {
+      fills.push(fill)
+    }
+  }
+  return entries.map((entry) => {
+    const fills =
+      entry.status.status === 'activated' && entry.twapId !== undefined
+        ? fillsByTwap.get(entry.twapId)
+        : undefined
+    if (fills === undefined) {
+      return entry
+    }
+    const notionals = fills.map((fill) =>
+      safeCalculateNotionalValue(fill.sz, fill.px)
+    )
+    if (!notionals.every((notional) => notional !== undefined)) {
+      return entry
+    }
+    const executedSz = safeAddDecimalStrings(fills.map((fill) => fill.sz))
+    const executedNtl = safeAddDecimalStrings(notionals)
+    if (executedSz === undefined || executedNtl === undefined) {
+      return entry
+    }
+    return { ...entry, state: { ...entry.state, executedSz, executedNtl } }
+  })
+}

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()}`, {