@lifi/perps-sdk-provider-hyperliquid 13.0.0 → 14.0.0

package/src/services/getOrders.ts

@@ -1,102 +1,217 @@
-import { getMarketRegistry, type SDKRequestOptions } from '@lifi/perps-sdk'
-import type { OpenOrder, OrdersResponse, TriggerOrder } from '@lifi/perps-types'
-import type { Address } from 'viem'
+import {
+  ACTIVE_ORDER_STATUSES,
+  createWarnOnce,
+  ExplorerChainId,
+  explorerTxUrl,
+  getMarketRegistry,
+  isActiveOrderStatus,
+  type MarketRegistry,
+  PerpsError,
+  type ProviderGetOrdersParams,
+  type SDKRequestOptions,
+} from '@lifi/perps-sdk'
+import type { MarketDisplay, Order, OrdersResponse } from '@lifi/perps-types'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import type {
-  HlFrontendOpenOrder,
+  HlExplorerTx,
   HlFrontendOpenOrders,
+  HlHistoricalOrders,
+  HlTwapHistoryEntry,
 } from '../types/index.js'
 import {
-  isTriggerOrder,
-  mapOpenOrder,
-  mapTriggerOrder,
+  assetIsOutcome,
+  fetchUserTransactions,
+  mapOrder,
+  matchOrderActionHash,
   perpsDexNames,
 } from '../utils/index.js'
-import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
+import {
+  hlInfoOptions,
+  type InfoRequestOptions,
+  infoRequest,
+} from '../utils/infoClient.js'
+
+/** Parameters for a lifecycle-filtered Hyperliquid order read. */
+export type GetOrdersParams = ProviderGetOrdersParams
+
+const warn = createWarnOnce()
+
+const warnOnce = (key: string, detail?: string): void => {
+  warn(
+    key,
+    `[${PROVIDER_KEY}] ${detail === undefined ? key : `${key}: ${detail}`}`
+  )
+}
 
 /**
- * Parameters for {@link getOrders}.
- *
- * @public
+ * Map one venue row, or drop it. An outcome market identity, a coin the backend
+ * market list does not hold, and a row the mapper rejects each drop only their
+ * own row instead of rejecting the whole page; each distinct mapper message
+ * warns once.
  */
-export interface GetOrdersParams {
-  address: Address
-  /** Optional filter using the normalized opaque `Market.id`. */
-  marketId?: string
-  /** Page-size hint; Hyperliquid returns all open orders in one response. */
-  limit?: number
+const mapRow = (
+  coin: string,
+  registry: MarketRegistry,
+  map: (market: MarketDisplay) => Order
+): Order | undefined => {
+  if (assetIsOutcome(coin)) {
+    return undefined
+  }
+  const market = registry.get(coin)
+  if (market === undefined) {
+    return undefined
+  }
+  try {
+    return map(market)
+  } catch (error) {
+    if (!(error instanceof PerpsError)) {
+      throw error
+    }
+    warnOnce(`dropped order row: ${error.message}`)
+    return undefined
+  }
 }
 
 /**
- * Fetch open + trigger orders across every supported perps sub-dex for
- * `address`, normalised into `OrdersResponse`. Trigger orders that appear as
- * children of a parent limit order (Hyperliquid's `normalTpsl` flow) are
- * extracted and surfaced alongside top-level trigger orders. The backend's
- * enriched asset list supplies the sub-dex fan-out and display fields; only
- * `frontendOpenOrders` is read direct.
- * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
- * @public
+ * Set `explorerLink` on each row whose placement transaction the explorer
+ * window still holds. One explorer read serves the whole page, and it is
+ * skipped when no row carries a client order id to match on. The link is
+ * supplementary, so an explorer failure warns and leaves the rows unlinked
+ * instead of failing the order read.
  */
+const withExplorerLinks = async (
+  orders: Order[],
+  address: string,
+  options: InfoRequestOptions
+): Promise<Order[]> => {
+  if (!orders.some((order) => order.clientOrderId !== undefined)) {
+    return orders
+  }
+  let txs: HlExplorerTx[]
+  try {
+    txs = await fetchUserTransactions(address, options)
+  } catch (error) {
+    if (!(error instanceof PerpsError)) {
+      throw error
+    }
+    // The message stays out of the key: a transport failure names hosts and
+    // ports, so keying on it would let the dedupe set grow without bound.
+    warnOnce('explorer link lookup failed', error.message)
+    return orders
+  }
+  return orders.map((order) => {
+    const explorerLink = explorerTxUrl(
+      ExplorerChainId.HYPERLIQUID,
+      matchOrderActionHash(txs, order)
+    )
+    return explorerLink === undefined ? order : { ...order, explorerLink }
+  })
+}
+
+/** Read regular, trigger, and TWAP orders from the requested lifecycle feeds. */
 export const getOrders = async (
   { client, apiUrl }: HyperliquidContext,
   params: GetOrdersParams,
   options?: SDKRequestOptions
 ): Promise<OrdersResponse> => {
+  const statuses = params.statuses ?? [...ACTIVE_ORDER_STATUSES]
+  if (statuses.length === 0) {
+    return {
+      provider: PROVIDER_KEY,
+      orders: [],
+      pagination: { limit: params.limit ?? 0, hasMore: false },
+    }
+  }
   const registry = getMarketRegistry(client, PROVIDER_KEY)
   const markets = await registry.sync()
   const infoOpts = hlInfoOptions(client, options)
-
-  const ordersResults = await Promise.all(
-    perpsDexNames(markets).map((name) =>
-      infoRequest<HlFrontendOpenOrders>(
-        apiUrl,
-        {
-          type: 'frontendOpenOrders',
-          user: params.address,
-          ...(name ? { dex: name } : {}),
-        },
-        infoOpts
-      )
+  const active = statuses.some(isActiveOrderStatus)
+  const terminal = statuses.some((status) => !isActiveOrderStatus(status))
+  const [open, historical, twaps] = await Promise.all([
+    active
+      ? Promise.all(
+          perpsDexNames(markets).map((name) =>
+            infoRequest<HlFrontendOpenOrders>(
+              apiUrl,
+              {
+                type: 'frontendOpenOrders',
+                user: params.address,
+                ...(name ? { dex: name } : {}),
+              },
+              infoOpts
+            )
+          )
+        )
+      : [],
+    terminal
+      ? infoRequest<HlHistoricalOrders>(
+          apiUrl,
+          { type: 'historicalOrders', user: params.address },
+          infoOpts
+        )
+      : [],
+    infoRequest<HlTwapHistoryEntry[]>(
+      apiUrl,
+      { type: 'twapHistory', user: params.address },
+      infoOpts
+    ),
+  ])
+  const rows = new Map<string, Order>()
+  const keep = (key: string, order: Order | undefined): void => {
+    if (order !== undefined) {
+      rows.set(key, order)
+    }
+  }
+  for (const detail of historical) {
+    const key = String(detail.order.oid)
+    // The feed carries one row per lifecycle transition, newest first, and a
+    // terminal row shares its timestamp with the `open` row beneath it, so
+    // only the first row of an id states that order's current status.
+    if (rows.has(key)) {
+      continue
+    }
+    keep(
+      key,
+      mapRow(detail.order.coin, registry, (market) => mapOrder(detail, market))
     )
+  }
+  const raw = open.flat()
+  const childIds = new Set(
+    raw.flatMap((order) => (order.children ?? []).map((child) => child.oid))
   )
-
-  const raw: HlFrontendOpenOrder[] = ordersResults.flat()
-
-  const childOids = new Set<number>()
-  for (const o of raw) {
-    for (const child of o.children ?? []) {
-      childOids.add(child.oid)
+  for (const order of raw) {
+    if (!childIds.has(order.oid)) {
+      keep(
+        String(order.oid),
+        mapRow(order.coin, registry, (market) => mapOrder(order, market))
+      )
+    }
+    for (const child of order.children ?? []) {
+      keep(
+        String(child.oid),
+        mapRow(child.coin, registry, (market) =>
+          mapOrder(child, market, String(order.oid))
+        )
+      )
     }
   }
-
-  const nonChild = raw.filter((o) => !childOids.has(o.oid))
-
-  let openOrders: OpenOrder[] = nonChild
-    .filter((o) => !isTriggerOrder(o))
-    .map((o) => mapOpenOrder(o, registry.require(o.coin)))
-
-  let triggerOrders: TriggerOrder[] = [
-    ...nonChild
-      .filter((o) => isTriggerOrder(o))
-      .map((o) => mapTriggerOrder(o, registry.require(o.coin))),
-    ...raw
-      .filter((o) => childOids.has(o.oid))
-      .map((o) => mapTriggerOrder(o, registry.require(o.coin))),
-  ]
-
-  if (params.marketId !== undefined) {
-    openOrders = openOrders.filter((o) => o.market.id === params.marketId)
-    triggerOrders = triggerOrders.filter((o) => o.market.id === params.marketId)
+  // TWAP ids and regular order ids occupy separate venue namespaces.
+  for (const twap of twaps) {
+    keep(
+      `twap:${twap.twapId}`,
+      mapRow(twap.state.coin, registry, (market) => mapOrder(twap, market))
+    )
   }
-
+  const matching = [...rows.values()].filter(
+    (order) =>
+      statuses.includes(order.status) &&
+      (params.marketId === undefined || order.market.id === params.marketId)
+  )
+  const orders = await withExplorerLinks(matching, params.address, infoOpts)
   return {
     provider: PROVIDER_KEY,
-    openOrders,
-    triggerOrders,
-    pagination: {
-      limit: params.limit ?? openOrders.length + triggerOrders.length,
-      hasMore: false,
-    },
+    orders,
+    pagination: { limit: params.limit ?? orders.length, hasMore: false },
   }
 }

package/src/services/getPositions.ts

@@ -9,6 +9,7 @@ import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import type { HlClearinghouseState } from '../types/index.js'
 import {
+  assetIsOutcome,
   isOpenAssetPosition,
   mapPosition,
   perpsDexNames,
@@ -61,7 +62,9 @@ export const getPositions = async (
 
   let positions = stateResults.flatMap((state) =>
     state.assetPositions
-      .filter(isOpenAssetPosition)
+      .filter(
+        (ap) => !assetIsOutcome(ap.position.coin) && isOpenAssetPosition(ap)
+      )
       .map((ap) =>
         mapPosition(
           ap,

package/src/types/explorer.ts

@@ -0,0 +1,39 @@
+/**
+ * One HyperCore transaction as the explorer `userDetails` RPC reports it.
+ *
+ * @public
+ */
+export interface HlExplorerTx {
+  time: number
+  user: string
+  /**
+   * The action body HyperCore received. Untyped because the shape varies by
+   * action type; read it through `getClientOrderIds`, not by field name.
+   */
+  action: unknown
+  block: number
+  hash: string
+  /** `null` on a tx the engine applied, a message on one it landed but refused. */
+  error: string | null
+}
+
+/**
+ * Whether one `userDetails` entry carries every field this package reads. The
+ * explorer RPC is undocumented, so entries are checked one at a time and a
+ * drifted entry drops on its own instead of failing the whole window.
+ *
+ * @public
+ */
+export const isHlExplorerTx = (value: unknown): value is HlExplorerTx =>
+  typeof value === 'object' &&
+  value !== null &&
+  'time' in value &&
+  typeof value.time === 'number' &&
+  'user' in value &&
+  typeof value.user === 'string' &&
+  'block' in value &&
+  typeof value.block === 'number' &&
+  'hash' in value &&
+  typeof value.hash === 'string' &&
+  'error' in value &&
+  (value.error === null || typeof value.error === 'string')

package/src/types/fill.ts

@@ -34,6 +34,18 @@ export type HlUserFill = {
   crossed: boolean
   time: number
   startPosition: string
+  /**
+   * Present on both sides of a liquidation fill. `liquidatedUser` names the
+   * account that was liquidated; the other party is the liquidator.
+   */
+  liquidation?: HlFillLiquidation
+}
+
+/** Liquidation detail Hyperliquid attaches to a fill. @public */
+export type HlFillLiquidation = {
+  liquidatedUser: string
+  markPx: string
+  method: string
 }
 
 /** All fills returned by the unbounded `userFills` query. @public */

package/src/types/index.ts

@@ -5,6 +5,7 @@
 export * from './account.js'
 export * from './action.js'
 export * from './asset.js'
+export * from './explorer.js'
 export * from './fill.js'
 export * from './ledger.js'
 export * from './order.js'

package/src/types/ledger.ts

@@ -50,6 +50,41 @@ export type HlSendAssetDelta = {
   feeToken: string
 }
 
+/** USDC transfers between Hyperliquid accounts, including subaccounts. @public */
+export type HlCollateralTransferDelta = {
+  type: 'internalTransfer' | 'subAccountTransfer'
+  usdc: string
+  user: Address
+  destination: Address
+  fee?: string
+}
+
+/** Narrow the USDC account-transfer ledger variants. @public */
+export const isCollateralTransferDelta = (
+  delta: HlLedgerDelta
+): delta is HlCollateralTransferDelta =>
+  delta.type === 'internalTransfer' || delta.type === 'subAccountTransfer'
+
+/** USDC movements into or out of a vault, including withdrawal accounting. @public */
+export type HlVaultTransferDelta =
+  | { type: 'vaultDeposit'; vault: Address; usdc: string }
+  | {
+      type: 'vaultWithdraw'
+      vault: Address
+      user: Address
+      requestedUsd: string
+      commission: string
+      closingCost: string
+      basis: string
+      netWithdrawnUsd: string
+    }
+
+/** Narrow the vault fund-movement ledger variants. @public */
+export const isVaultTransferDelta = (
+  delta: HlLedgerDelta
+): delta is HlVaultTransferDelta =>
+  delta.type === 'vaultDeposit' || delta.type === 'vaultWithdraw'
+
 /**
  * Hyperliquid `deposit` ledger delta. Perp-collateral deposits are always
  * USDC-denominated, which is why the amount arrives in a field named `usdc`.
@@ -103,6 +138,8 @@ export type HlLiquidationDelta = {
 export type HlLedgerDelta =
   | HlSpotTransferDelta
   | HlSendAssetDelta
+  | HlCollateralTransferDelta
+  | HlVaultTransferDelta
   | HlDepositDelta
   | HlWithdrawDelta
   | HlLiquidationDelta

package/src/types/order.ts

@@ -17,6 +17,7 @@ export type HlFrontendOpenOrder = {
   reduceOnly: boolean
   timestamp: number
   isTrigger: boolean
+  tpsl?: 'tp' | 'sl'
   isPositionTpsl: boolean
   triggerCondition: string
   triggerPx: string
@@ -49,6 +50,10 @@ export type HlOrderDetail = {
     cloid: string | null
     triggerCondition: string
     triggerPx: string | null
+    isTrigger?: boolean
+    tpsl?: 'tp' | 'sl'
+    children?: HlFrontendOpenOrder[]
+    isPositionTpsl?: boolean
   }
   status: string
   statusTimestamp: number
@@ -68,3 +73,23 @@ export type HlOrderStatusFound = {
 export type HlOrderStatusResponse =
   | HlOrderStatusFound
   | { status: 'unknownOid' }
+
+/** Rows returned by the `historicalOrders` info query. */
+export type HlHistoricalOrders = HlOrderDetail[]
+
+/** TWAP execution state returned by `twapHistory`; time uses epoch seconds. */
+export interface HlTwapHistoryEntry {
+  state: {
+    coin: string
+    executedNtl: string
+    executedSz: string
+    minutes: number
+    side: string
+    sz: string
+    timestamp: number
+    reduceOnly: boolean
+  }
+  status: { status: string; description?: string }
+  time: number
+  twapId?: number
+}

package/src/types/ws.ts

@@ -6,6 +6,22 @@ import type { HlUserFill } from './fill.js'
 
 type HlWsNumberString = string | number
 
+/** Sparse order update returned by the `orderUpdates` WebSocket subscription. */
+export interface HlWsOrder {
+  order: {
+    coin: string
+    side: string
+    limitPx: string
+    sz: string
+    oid: number
+    timestamp: number
+    origSz: string
+    cloid?: string
+  }
+  status: string
+  statusTimestamp: number
+}
+
 /**
  * Perp asset context as carried on the `allDexsAssetCtxs` WS feed. Extends the
  * REST `/info` `HlAssetCtx` shape with the wire-only `coin` tag, the order-book

package/src/utils/assetId.ts

@@ -5,6 +5,22 @@
  */
 export const assetIsSpot = (assetId: string): boolean => assetId.startsWith('@')
 
+/** Lowest numeric asset ID Hyperliquid assigns to an outcome market. */
+const OUTCOME_ASSET_ID_BASE = 100_000_000
+
+/**
+ * Return whether a Hyperliquid asset identity belongs to an HIP-4 outcome
+ * market: spot coin `#<encoding>`, token name `+<encoding>`, or numeric asset
+ * ID `100000000 + encoding`. LI.FI supports no outcome market, and the backend
+ * market list holds none, so the provider skips every such identity.
+ * @param assetId - Raw Hyperliquid coin, token name, or numeric asset ID.
+ * @public
+ */
+export const assetIsOutcome = (assetId: string | number): boolean =>
+  typeof assetId === 'number'
+    ? assetId >= OUTCOME_ASSET_ID_BASE
+    : assetId.startsWith('#') || assetId.startsWith('+')
+
 /**
  * Calculate Hyperliquid's numeric asset ID from a perp DEX index and the
  * asset's zero-based index within that DEX. The main DEX uses the index

package/src/utils/explorer.ts

@@ -0,0 +1,93 @@
+import type { OrderBase } from '@lifi/perps-types'
+import { isHex } from 'viem'
+import { HYPERLIQUID_EXPLORER_RPC_URL } from '../constants.js'
+import { type HlExplorerTx, isHlExplorerTx } from '../types/explorer.js'
+import { hlPostJson, type InfoRequestOptions } from './infoClient.js'
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null
+
+/**
+ * Read the address's recent HyperCore transactions from the explorer RPC.
+ *
+ * The surface is undocumented, so it is read defensively: an address the
+ * explorer has never indexed answers `200` with no `txs` array, and each entry
+ * is checked on its own so one drifted entry cannot drop the rest.
+ *
+ * @throws {PerpsError} On a non-2xx status or a transport failure.
+ * @public
+ */
+export const fetchUserTransactions = async (
+  address: string,
+  options?: InfoRequestOptions
+): Promise<HlExplorerTx[]> => {
+  const body = await hlPostJson<{ txs?: unknown } | null>(
+    HYPERLIQUID_EXPLORER_RPC_URL,
+    'explorer userDetails',
+    { type: 'userDetails', user: address },
+    options
+  )
+  const txs = body?.txs
+  return Array.isArray(txs) ? txs.filter(isHlExplorerTx) : []
+}
+
+/**
+ * Every client order id an action names: `orders[].c` on a placement, `order.c`
+ * on a single modify, and `modifies[].order.c` on a batch modify. A batched
+ * placement names one id per leg, so every id is returned, not just the first.
+ *
+ * @public
+ */
+export const getClientOrderIds = (
+  action: Record<string, unknown>
+): string[] => {
+  const wires: unknown[] = [
+    ...(Array.isArray(action.orders) ? action.orders : []),
+    ...(Array.isArray(action.modifies)
+      ? action.modifies.map((modify) =>
+          isRecord(modify) ? modify.order : undefined
+        )
+      : []),
+    action.order,
+  ]
+  const ids: string[] = []
+  for (const wire of wires) {
+    if (!isRecord(wire)) {
+      continue
+    }
+    const cloid = wire.c
+    if (
+      typeof cloid === 'string' &&
+      cloid !== '0x' &&
+      isHex(cloid, { strict: true })
+    ) {
+      ids.push(cloid)
+    }
+  }
+  return ids
+}
+
+/**
+ * The hash of the transaction whose action names the order's client order id.
+ *
+ * @returns The transaction hash, or `undefined` when the order carries no
+ *   client order id or no transaction in the window names it.
+ * @public
+ */
+export const matchOrderActionHash = (
+  txs: HlExplorerTx[],
+  order: Pick<OrderBase, 'clientOrderId'>
+): string | undefined => {
+  const { clientOrderId } = order
+  if (clientOrderId === undefined) {
+    return undefined
+  }
+  // A client order id is hex, so the venue may echo a case the placer did not send.
+  const wanted = clientOrderId.toLowerCase()
+  const match = txs.find(
+    (tx) =>
+      isRecord(tx.action) &&
+      getClientOrderIds(tx.action).some((id) => id.toLowerCase() === wanted)
+  )
+  return match?.hash
+}

package/src/utils/index.ts

@@ -2,7 +2,12 @@
 // for the package's utility surface. Internal modules import per-file paths
 // (e.g. `./assetId.js`, `./mapFill.js`) directly.
 
-export { assetIsSpot, calculateAssetId, getProviderIndex } from './assetId.js'
+export {
+  assetIsOutcome,
+  assetIsSpot,
+  calculateAssetId,
+  getProviderIndex,
+} from './assetId.js'
 export {
   applyLogoOverride,
   spotLogoURI,
@@ -12,26 +17,30 @@ export {
   decodeCompressedJson,
   decodeFastAssetCtxs,
 } from './decodeFastAssetCtxs.js'
+export {
+  fetchUserTransactions,
+  getClientOrderIds,
+  matchOrderActionHash,
+} from './explorer.js'
 export type { InfoRequestOptions } from './infoClient.js'
 export { hlInfoOptions, infoRequest } from './infoClient.js'
 export {
   calculateLiquidationPrice,
   calculateMaintenanceMarginRate,
 } from './liquidation.js'
-export { mapFundingActivity, mapLedgerEntry } from './mapActivity.js'
+export {
+  mapFundingActivity,
+  mapLedgerEntry,
+  mapLiquidationFills,
+} from './mapActivity.js'
 export { classifyFillFromPosition, mapFill } from './mapFill.js'
 export { mapMarket } from './mapMarket.js'
 export { mapMarketContext } from './mapMarketContext.js'
 export {
   type HlOrderLike,
-  isTriggerOrder,
-  isTriggerType,
-  mapOpenOrder,
   mapOrder,
   mapOrderStatus,
   mapOrderType,
-  mapStatusReason,
-  mapTriggerOrder,
 } from './mapOrder.js'
 export { isOpenAssetPosition, mapPosition } from './mapPosition.js'
 export { coinAsset, perpsDexNames } from './marketDisplay.js'