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

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/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

@@ -11,6 +11,7 @@ import {
   LiquidityRole,
   OrderSide,
 } from '@lifi/perps-types'
+import { zeroHash } from 'viem'
 import { PROVIDER_KEY, SPOT_MARKET_ID } from '../constants.js'
 import type { HlFillLiquidation, HlUserFill } from '../types/index.js'
 import { rowTimestampToIsoStringOrUndefined } from './rowTimestamp.js'
@@ -95,7 +96,11 @@ export const mapFill = (
         ? undefined
         : { amount: fill.builderFee, asset: feeAsset },
     startPosition: fill.startPosition,
-    explorerLink: explorerTxUrl(ExplorerChainId.HYPERLIQUID, fill.hash),
+    // A TWAP slice fill carries the zero hash: no venue transaction to link.
+    explorerLink: explorerTxUrl(
+      ExplorerChainId.HYPERLIQUID,
+      fill.hash === zeroHash ? undefined : fill.hash
+    ),
     classification:
       market.categoryId === SPOT_MARKET_ID
         ? side === OrderSide.BUY

package/src/websocket/HyperliquidWsProvider.ts

@@ -81,6 +81,7 @@ import type {
   HlWsSpotStateData,
   HlWsTrade,
   HlWsUserFillsData,
+  HlWsUserTwapSliceFillsData,
 } from '../types/index.js'
 import { HlAbstractionMode } from '../types/index.js'
 import {
@@ -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
@@ -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)