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

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'

package/src/utils/infoClient.ts

@@ -1,6 +1,7 @@
 import {
   errorCodeFromStatus,
   fetchWithRetry,
+  isAbortError,
   PerpsError,
   type PerpsSDKClient,
   type ResolvedRetryPolicy,
@@ -57,7 +58,7 @@ export const HYPERLIQUID_RETRY_DEFAULTS: ResolvedRetryPolicy = {
 }
 
 /**
- * Transport options for a direct Hyperliquid `/info` request. `policy`
+ * Transport options for a direct Hyperliquid REST request. `policy`
  * controls retries, `signal` cancels the request, and `fetchImpl` overrides
  * the runtime's global `fetch` implementation.
  * @public
@@ -87,7 +88,7 @@ export const hlInfoOptions = (
 })
 
 /**
- * POST to the Hyperliquid `/info` endpoint and return the parsed JSON body.
+ * POST a JSON body to a Hyperliquid REST surface and return the parsed body.
  *
  * Direct-to-venue: no proxy, no AJV validation, no cache. The caller's type
  * parameter is trusted; consumers should treat the response shape as
@@ -97,20 +98,24 @@ export const hlInfoOptions = (
  * Non-2xx responses raise a {@link PerpsError} tagged with the Hyperliquid
  * provider key, carrying the code the status resolves to: `RateLimitExceeded`
  * for a 429, `Unauthorized` for a 401, `AgentUnauthorized` for a 403, and
- * `ThirdPartyError` for every other status.
- * @public
+ * `ThirdPartyError` for every other status. A transport failure and a 2xx body
+ * that is not JSON both raise `ServerError`, so every failure but a caller
+ * abort reaches the caller as a `PerpsError`. An abort rejects untouched.
+ *
+ * @param label - Names the surface in the error message, e.g. `info request`.
+ * @internal
  */
-export async function infoRequest<T>(
-  apiUrl: string,
+export async function hlPostJson<T>(
+  url: string,
+  label: string,
   body: Record<string, unknown>,
   options?: InfoRequestOptions
 ): Promise<T> {
   const policy = options?.policy ?? HYPERLIQUID_RETRY_DEFAULTS
 
-  let response: Response
   try {
-    response = await fetchWithRetry(
-      `${apiUrl}/info`,
+    const response = await fetchWithRetry(
+      url,
       {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -122,27 +127,44 @@ export async function infoRequest<T>(
         signal: options?.signal,
       }
     )
+
+    if (!response.ok) {
+      const err = new PerpsError(
+        errorCodeFromStatus(
+          response.status,
+          PerpsErrorCode.ThirdPartyError,
+          HYPERLIQUID_STATUS_ERROR_CODES
+        ),
+        `Hyperliquid ${label} failed: ${response.status}`
+      )
+      err.tool = PROVIDER_KEY
+      throw err
+    }
+
+    return (await response.json()) as T
   } catch (error) {
+    if (error instanceof PerpsError || isAbortError(error)) {
+      throw error
+    }
     const err = new PerpsError(
       PerpsErrorCode.ServerError,
-      error instanceof Error ? error.message : 'Hyperliquid info request failed'
-    )
-    err.tool = PROVIDER_KEY
-    throw err
-  }
-
-  if (!response.ok) {
-    const err = new PerpsError(
-      errorCodeFromStatus(
-        response.status,
-        PerpsErrorCode.ThirdPartyError,
-        HYPERLIQUID_STATUS_ERROR_CODES
-      ),
-      `Hyperliquid info request failed: ${response.status}`
+      error instanceof Error ? error.message : `Hyperliquid ${label} failed`
     )
     err.tool = PROVIDER_KEY
     throw err
   }
+}
 
-  return (await response.json()) as T
+/**
+ * POST to the Hyperliquid `/info` endpoint and return the parsed JSON body.
+ * See {@link hlPostJson} for the transport and error contract.
+ *
+ * @public
+ */
+export function infoRequest<T>(
+  apiUrl: string,
+  body: Record<string, unknown>,
+  options?: InfoRequestOptions
+): Promise<T> {
+  return hlPostJson<T>(`${apiUrl}/info`, 'info request', body, options)
 }