@lifi/perps-sdk-provider-hyperliquid 31.0.1 → 31.0.3

package/src/services/getFills.ts

@@ -1,9 +1,9 @@
 import { getMarketRegistry, type SDKRequestOptions } from '@lifi/perps-sdk'
 import type { Fill, FillsResponse } from '@lifi/perps-types'
 import type { Address } from 'viem'
-import { PROVIDER_KEY } from '../constants.js'
+import { FILL_ROWS_CAP, PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
-import type { HlUserFills } from '../types/index.js'
+import type { HlTwapSliceFill, HlUserFills } from '../types/index.js'
 import { assetIsOutcome, mapFill } from '../utils/index.js'
 import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
 import { requireAccountExists } from './getAccountExists.js'
@@ -20,13 +20,16 @@ export interface GetFillsParams {
   limit?: number
   /** Opaque cursor returned in the previous page's `pagination.cursor`. */
   cursor?: string
-  /** Inclusive lower bound in milliseconds; selects `userFillsByTime`. */
+  /** Inclusive lower bound in milliseconds; selects the `...ByTime` feeds. */
   startTime?: number
-  /** Inclusive upper bound in milliseconds; selects `userFillsByTime`. */
+  /** Inclusive upper bound in milliseconds; selects the `...ByTime` feeds. */
   endTime?: number
 }
 
-/** Fetch retained fills newest-first, using opaque cursors across inclusive time ranges. */
+/**
+ * Fetch retained regular and TWAP slice fills newest-first, using opaque
+ * cursors across inclusive time ranges.
+ */
 export const getFills = async (
   { client, apiUrl }: HyperliquidContext,
   params: GetFillsParams,
@@ -46,30 +49,39 @@ export const getFills = async (
     params,
     limit,
     async (startTime, endTime) => {
-      const fills = await infoRequest<HlUserFills>(
-        apiUrl,
-        useRecent
-          ? { type: 'userFills', user: params.address }
-          : {
-              type: 'userFillsByTime',
-              user: params.address,
-              startTime,
-              endTime,
-            },
-        infoOpts
-      )
+      const user = params.address
+      const [fills, sliceFills] = await Promise.all([
+        infoRequest<HlUserFills>(
+          apiUrl,
+          useRecent
+            ? { type: 'userFills', user }
+            : { type: 'userFillsByTime', user, startTime, endTime },
+          infoOpts
+        ),
+        infoRequest<HlTwapSliceFill[]>(
+          apiUrl,
+          useRecent
+            ? { type: 'userTwapSliceFills', user }
+            : { type: 'userTwapSliceFillsByTime', user, startTime, endTime },
+          infoOpts
+        ),
+      ])
       useRecent = false
-      if (fills.length >= 2000) {
+      if (fills.length >= FILL_ROWS_CAP || sliceFills.length >= FILL_ROWS_CAP) {
         return { items: [], saturated: true }
       }
-      const items = fills.flatMap((fill): Fill[] => {
-        if (assetIsOutcome(fill.coin)) {
-          return []
+      const seen = new Set<number>()
+      const items = [...fills, ...sliceFills.map(({ fill }) => fill)].flatMap(
+        (fill): Fill[] => {
+          if (assetIsOutcome(fill.coin) || seen.has(fill.tid)) {
+            return []
+          }
+          seen.add(fill.tid)
+          const market = registry.get(fill.coin)
+          const mapped = market && mapFill(fill, market, params.address)
+          return mapped ? [mapped] : []
         }
-        const market = registry.get(fill.coin)
-        const mapped = market && mapFill(fill, market, params.address)
-        return mapped ? [mapped] : []
-      })
+      )
       return { items, saturated: false }
     },
     (fill) => ({

package/src/services/getMarketSettings.ts

@@ -1,4 +1,5 @@
 import {
+  isSpotCategory,
   numberToDecimalString,
   PerpsError,
   type SDKRequestOptions,
@@ -10,7 +11,7 @@ import {
   PerpsErrorCode,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
-import { PROVIDER_KEY, SPOT_MARKET_ID } from '../constants.js'
+import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import { hlInfoOptions } from '../utils/infoClient.js'
 import { fetchActiveAssetData } from './activeAssetData.js'
@@ -39,7 +40,7 @@ export const getMarketSettings = async (
   params: GetMarketSettingsParams,
   options?: SDKRequestOptions
 ): Promise<MarketSettings> => {
-  if (params.market.categoryId === SPOT_MARKET_ID) {
+  if (isSpotCategory(params.market.categoryId)) {
     const error = new PerpsError(
       PerpsErrorCode.ValidationError,
       `Hyperliquid market '${params.market.marketId}' is a spot market and carries no leverage setting`

package/src/services/twapSliceFills.ts

@@ -1,11 +1,9 @@
 import type { Address } from 'viem'
+import { FILL_ROWS_CAP } from '../constants.js'
 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
@@ -31,7 +29,7 @@ export const fetchTwapSliceFills = async (
     { type: 'userTwapSliceFills', user },
     options
   )
-  if (window.length < TWAP_SLICE_FILLS_CAP) {
+  if (window.length < FILL_ROWS_CAP) {
     return window
   }
   const oldest = Math.min(...window.map(({ fill }) => fill.time))
@@ -54,7 +52,7 @@ export const fetchTwapSliceFills = async (
         },
         options
       )
-      return fills.length >= TWAP_SLICE_FILLS_CAP
+      return fills.length >= FILL_ROWS_CAP
         ? { items: [], saturated: true }
         : { items: fills, saturated: false }
     },

package/src/types/ws.ts

@@ -3,7 +3,7 @@
 import type { DecimalString } from '@lifi/perps-types'
 import type { HlClearinghouseState, HlSpotBalance } from './account.js'
 import type { HlCandle, HlL2Book } from './asset.js'
-import type { HlUserFill } from './fill.js'
+import type { HlTwapSliceFill, HlUserFill } from './fill.js'
 
 type HlWsNumberString = string | number
 
@@ -185,6 +185,13 @@ export type HlWsUserFillsData = {
   fills: HlUserFill[]
 }
 
+/** TWAP slice fills event. A live frame can omit `isSnapshot`. @public */
+export type HlWsUserTwapSliceFillsData = {
+  isSnapshot?: boolean
+  user: string
+  twapSliceFills: HlTwapSliceFill[]
+}
+
 /**
  * One sub-dex slice of an `allDexsClearinghouseState` frame. `marginSummary`
  * is absent on a frame that reports positions only, so a reader must treat it

package/src/utils/mapFill.ts

@@ -2,6 +2,7 @@ import {
   classifyFillFromPosition,
   ExplorerChainId,
   explorerTxUrl,
+  isSpotCategory,
   warnSkippedVenueRow,
 } from '@lifi/perps-sdk'
 import type { Fill, FillLiquidation, MarketDisplay } from '@lifi/perps-types'
@@ -11,8 +12,10 @@ import {
   LiquidityRole,
   OrderSide,
 } from '@lifi/perps-types'
-import { PROVIDER_KEY, SPOT_MARKET_ID } from '../constants.js'
-import type { HlFillLiquidation, HlUserFill } from '../types/index.js'
+import { zeroHash } from 'viem'
+import { PROVIDER_KEY } from '../constants.js'
+import type { HlUserFill } from '../types/index.js'
+import { isFillLiquidatingAccount } from './isFillLiquidatingAccount.js'
 import { rowTimestampToIsoStringOrUndefined } from './rowTimestamp.js'
 
 /** Re-export the shared fill-position classifier used by Hyperliquid mappings. @public */
@@ -33,13 +36,11 @@ const mapLiquidationMethod = (
 
 // Hyperliquid attaches `liquidation` to the fills of both parties.
 const mapFillLiquidation = (
-  liquidation: HlFillLiquidation | undefined,
+  fill: HlUserFill,
   address: string
 ): FillLiquidation | undefined => {
-  if (
-    liquidation === undefined ||
-    liquidation.liquidatedUser.toLowerCase() !== address.toLowerCase()
-  ) {
+  const { liquidation } = fill
+  if (liquidation === undefined || !isFillLiquidatingAccount(fill, address)) {
     return undefined
   }
   const method = mapLiquidationMethod(liquidation.method)
@@ -71,10 +72,10 @@ 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)
+  const liquidation = mapFillLiquidation(fill, address)
 
   return {
-    ...(market.categoryId === SPOT_MARKET_ID
+    ...(isSpotCategory(market.categoryId)
       ? { realizedPnl: fill.closedPnl }
       : { realizedPnl: fill.closedPnl === '0' ? null : fill.closedPnl }),
     id: String(fill.tid),
@@ -95,13 +96,16 @@ export const mapFill = (
         ? undefined
         : { amount: fill.builderFee, asset: feeAsset },
     startPosition: fill.startPosition,
-    explorerLink: explorerTxUrl(ExplorerChainId.HYPERLIQUID, fill.hash),
-    classification:
-      market.categoryId === SPOT_MARKET_ID
-        ? side === OrderSide.BUY
-          ? FillClassification.SPOT_BUY
-          : FillClassification.SPOT_SELL
-        : classifyFillFromPosition(fill.startPosition, side, size),
+    // A TWAP slice fill carries the zero hash: no venue transaction to link.
+    explorerLink: explorerTxUrl(
+      ExplorerChainId.HYPERLIQUID,
+      fill.hash === zeroHash ? undefined : fill.hash
+    ),
+    classification: isSpotCategory(market.categoryId)
+      ? side === OrderSide.BUY
+        ? FillClassification.SPOT_BUY
+        : FillClassification.SPOT_SELL
+      : classifyFillFromPosition(fill.startPosition, side, size),
     createdAt,
     ...(liquidation === undefined ? {} : { liquidation }),
   }

package/src/utils/marketDisplay.ts

@@ -1,10 +1,6 @@
+import { isSpotCategory } from '@lifi/perps-sdk'
 import type { Asset, Market } from '@lifi/perps-types'
-import {
-  MAIN_DEX_NAME,
-  MAIN_MARKET_ID,
-  PROVIDER_KEY,
-  SPOT_MARKET_ID,
-} from '../constants.js'
+import { MAIN_DEX_NAME, MAIN_MARKET_ID, PROVIDER_KEY } from '../constants.js'
 import { applyLogoOverride } from './assetLogo.js'
 
 /**
@@ -37,7 +33,7 @@ export const coinAsset = (coin: string): Asset =>
 export const perpsDexNames = (markets: readonly Market[]): string[] => {
   const hasLiveMarket = new Map<string, boolean>()
   for (const m of markets) {
-    if (m.categoryId === SPOT_MARKET_ID) {
+    if (isSpotCategory(m.categoryId)) {
       continue
     }
     const name = m.categoryId === MAIN_MARKET_ID ? MAIN_DEX_NAME : m.categoryId

package/src/utils/spotBalance.ts

@@ -1,10 +1,11 @@
 import {
   isDecimalString,
   isDecimalStringGreaterThan,
+  isSpotCategory,
   multiplyDecimalString,
 } from '@lifi/perps-sdk'
 import type { Asset, Balance, DecimalString, Market } from '@lifi/perps-types'
-import { SPOT_MARKET_ID } from '../constants.js'
+import { SPOT_CATEGORY_ID } from '@lifi/perps-types'
 import type { HlSpotBalance } from '../types/index.js'
 import { spotLogoURI } from './assetLogo.js'
 import { coinAsset } from './marketDisplay.js'
@@ -21,7 +22,7 @@ export const spotPriceById = (
 ): Map<string, DecimalString> => {
   const map = new Map<string, DecimalString>()
   for (const m of markets) {
-    if (m.categoryId === SPOT_MARKET_ID) {
+    if (isSpotCategory(m.categoryId)) {
       const price = priceByMarketId.get(m.id)
       map.set(m.baseAsset.id, isDecimalString(price) ? price : '0')
     }
@@ -61,7 +62,7 @@ export const spotBalance = (
 ): Balance => {
   const price = priceById.get(asset.id) ?? '0'
   return {
-    categoryId: SPOT_MARKET_ID,
+    categoryId: SPOT_CATEGORY_ID,
     asset,
     units: total,
     valueUsd: multiplyDecimalString(total, price),

package/src/utils/withdrawableBalances.ts

@@ -5,7 +5,8 @@ import {
   subtractDecimalString,
   unknownToDecimalString,
 } from '@lifi/perps-sdk'
-import { PROVIDER_KEY, SPOT_MARKET_ID } from '../constants.js'
+import { SPOT_CATEGORY_ID } from '@lifi/perps-types'
+import { PROVIDER_KEY } from '../constants.js'
 import type {
   HlAbstractionMode,
   HlClearinghouseState,
@@ -69,7 +70,7 @@ export const hyperliquidWithdrawableBalances = (
         const assetId = String(balance.token)
         const row = {
           assetId,
-          categoryId: SPOT_MARKET_ID,
+          categoryId: SPOT_CATEGORY_ID,
           available: spot,
           ...feeFor(assetId),
         }

package/src/websocket/HyperliquidWsProvider.ts

@@ -10,6 +10,7 @@ import {
   isActiveOrderStatus,
   isDecimalString,
   isDecimalStringZero,
+  isSpotCategory,
   type MarketRegistry,
   PerpsError,
   type PerpsSDKClient,
@@ -52,7 +53,6 @@ import {
   DEFAULT_HYPERLIQUID_API_URL,
   HYPERLIQUID_FEE_TIER_FALLBACK,
   PROVIDER_KEY,
-  SPOT_MARKET_ID,
 } from '../constants.js'
 import { requireAccountExists } from '../services/getAccountExists.js'
 import type {
@@ -81,6 +81,7 @@ import type {
   HlWsSpotStateData,
   HlWsTrade,
   HlWsUserFillsData,
+  HlWsUserTwapSliceFillsData,
 } from '../types/index.js'
 import { HlAbstractionMode } from '../types/index.js'
 import {
@@ -335,7 +336,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       const market = registry.requireActive(sub.marketId)
       if (
         sub.channel === 'availableToTrade' &&
-        market.categoryId === SPOT_MARKET_ID
+        isSpotCategory(market.categoryId)
       ) {
         const error = new PerpsError(
           PerpsErrorCode.ValidationError,
@@ -361,37 +362,17 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     // Markets context aggregates slower asset-context feeds with fast mid/mark
     // ticks from `fastAssetCtxs`.
     if (sub.channel === 'marketsContext') {
-      const epoch = this.spotWireEpoch
-      const entries = this.getMarketsContextSubEntries()
-      let acquired = 0
-      const release = () => {
-        if (epoch !== this.spotWireEpoch) {
-          return
-        }
-        for (let index = 0; index < acquired; index++) {
-          const { subKey, payload } = entries[index]
-          this.unregisterSub(subKey)
-          this.rws.send(
-            JSON.stringify({ method: 'unsubscribe', subscription: payload })
-          )
-        }
+      return this.openWireEntries(this.getMarketsContextSubEntries(), () => {
         this.perpCtxBySubDex.clear()
         this.spotCtxByMarketId = {}
         this.fastCtxByMarketId = {}
         this.marketsContextByMarketId = {}
-        acquired = 0
-      }
-      try {
-        for (const { subKey, payload } of entries) {
-          await this.registerSub(subKey, payload)
-          acquired++
-        }
-        await this.rws.ready()
-        return release
-      } catch (error) {
-        release()
-        throw error
-      }
+      })
+    }
+
+    // `fills` merges the regular and the TWAP slice fill feeds of one address.
+    if (sub.channel === 'fills') {
+      return this.openWireEntries(this.getFillsSubEntries(sub.address))
     }
 
     // The spot wire is shared between the public spotBalances channel and
@@ -529,6 +510,58 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
     ]
   }
 
+  /** Sub-key + payload pairs of the `fills` channel: regular and TWAP slice fills. */
+  private getFillsSubEntries(
+    address: string
+  ): Array<{ subKey: string; payload: object }> {
+    const user = normalizeHlAddress(address)
+    return [
+      { subKey: `userFills:${user}`, payload: { type: 'userFills', user } },
+      {
+        subKey: `userTwapSliceFills:${user}`,
+        payload: { type: 'userTwapSliceFills', user },
+      },
+    ]
+  }
+
+  /**
+   * Register each wire entry in order and return a release that unregisters
+   * the acquired ones. A failed register releases the acquired entries first.
+   * A release after `close()` sends no frame.
+   */
+  private async openWireEntries(
+    entries: Array<{ subKey: string; payload: object }>,
+    onRelease?: () => void
+  ): Promise<() => void> {
+    const epoch = this.spotWireEpoch
+    let acquired = 0
+    const release = () => {
+      if (epoch !== this.spotWireEpoch) {
+        return
+      }
+      for (let index = 0; index < acquired; index++) {
+        const { subKey, payload } = entries[index]
+        this.unregisterSub(subKey)
+        this.rws.send(
+          JSON.stringify({ method: 'unsubscribe', subscription: payload })
+        )
+      }
+      acquired = 0
+      onRelease?.()
+    }
+    try {
+      for (const { subKey, payload } of entries) {
+        await this.registerSub(subKey, payload)
+        acquired++
+      }
+      await this.rws.ready()
+      return release
+    } catch (error) {
+      release()
+      throw error
+    }
+  }
+
   private registerOrderbook(marketId: string, orderbookKey: string): void {
     let activeKeys = this.orderbookKeysByMarketId.get(marketId)
     if (activeKeys === undefined) {
@@ -603,7 +636,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       case 'orderUpdates':
         return `orderUpdates:${sub.address.toLowerCase()}`
       case 'fills':
-        return `userFills:${sub.address.toLowerCase()}`
+        return `fills:${sub.address.toLowerCase()}`
       case 'positions':
         return `positions:${sub.address.toLowerCase()}`
       case 'accountSummary':
@@ -683,6 +716,8 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
       case 'orderUpdates':
         return { type: 'orderUpdates', user: normalizeHlAddress(sub.address) }
       case 'fills':
+        // Handled via getFillsSubEntries in openChannel; never reaches
+        // toHlPayload, but TS requires an exhaustive switch.
         return { type: 'userFills', user: normalizeHlAddress(sub.address) }
       case 'positions':
       case 'accountSummary':
@@ -765,6 +800,9 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
         case 'userFills':
           this.handleUserFills(msg.data as HlWsUserFillsData)
           break
+        case 'userTwapSliceFills':
+          this.handleUserTwapSliceFills(msg.data as HlWsUserTwapSliceFillsData)
+          break
         case 'allDexsClearinghouseState':
           this.handleAllDexsClearinghouseState(
             msg.data as HlWsAllDexsClearinghouseStateData
@@ -850,7 +888,7 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
   private spotMarketIdBySacKey(): Map<string, string> {
     const map = new Map<string, string>()
     for (const market of this.registry?.activeMarkets ?? []) {
-      if (market.categoryId !== SPOT_MARKET_ID) {
+      if (!isSpotCategory(market.categoryId)) {
         continue
       }
       map.set(market.id, market.id)
@@ -1231,22 +1269,38 @@ export class HyperliquidWsProvider extends WsProviderBase<object> {
   }
 
   private handleUserFills(data: HlWsUserFillsData) {
+    this.emitFills(data.user, data.isSnapshot, data.fills)
+  }
+
+  private handleUserTwapSliceFills(data: HlWsUserTwapSliceFillsData) {
+    this.emitFills(
+      data.user,
+      data.isSnapshot,
+      data.twapSliceFills.map(({ fill }) => fill)
+    )
+  }
+
+  private emitFills(
+    user: string,
+    isSnapshot: boolean | undefined,
+    fills: HlUserFill[]
+  ) {
     // The snapshot frame carries up to ~2000 historical fills and is replayed
     // on every reconnect via `replaySubs`; emitting them would surface old
     // fills as live events on each network blip. Suppress it to an empty event
     // (fill history is available via REST `getFills`) so only live fills are
     // delivered as events.
-    const items = data.isSnapshot
+    const items = isSnapshot
       ? []
-      : data.fills.flatMap((f) => {
+      : fills.flatMap((f) => {
           if (assetIsOutcome(f.coin)) {
             return []
           }
           const market = this.registry?.get(f.coin)
-          const mapped = market && mapFill(f as HlUserFill, market, data.user)
+          const mapped = market && mapFill(f, market, user)
           return mapped ? [mapped] : []
         })
-    this.emit(`userFills:${data.user.toLowerCase()}`, {
+    this.emit(`fills:${user.toLowerCase()}`, {
       channel: 'fills',
       data: items,
     })
@@ -1924,6 +1978,8 @@ function isValidHlFrame(channel: string, data: unknown): boolean {
       return Array.isArray(data)
     case 'userFills':
       return typeof data.user === 'string' && Array.isArray(data.fills)
+    case 'userTwapSliceFills':
+      return typeof data.user === 'string' && Array.isArray(data.twapSliceFills)
     case 'allDexsClearinghouseState':
       return (
         typeof data.user === 'string' && Array.isArray(data.clearinghouseStates)