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

package/src/HyperliquidProvider.ts

@@ -17,7 +17,6 @@ import {
   type ProviderGetPortfolioHistoryParams,
   type ProviderGetPositionsParams,
   type ProviderGetQuoteParams,
-  type ProviderGetRunningTwapsParams,
   resolveQuote,
   type SDKRequestOptions,
   type SignActionsContext,
@@ -46,7 +45,6 @@ import {
   type Quote,
   type SignedActionStep,
   type SigningMethod,
-  type TwapOrder,
 } from '@lifi/perps-types'
 import { type Address, type Hex, isAddress } from 'viem'
 import { projectHyperliquidConfigSettings } from './accountConfig.js'
@@ -67,7 +65,6 @@ import { getOrder } from './services/getOrder.js'
 import { getOrders } from './services/getOrders.js'
 import { getPortfolioHistory } from './services/getPortfolioHistory.js'
 import { getPositions } from './services/getPositions.js'
-import { getRunningTwaps } from './services/getRunningTwaps.js'
 import {
   type HyperliquidAgent,
   HyperliquidAgentStore,
@@ -331,22 +328,13 @@ export function hyperliquidProvider(
         contextRef.require(),
         {
           address: params.address,
+          statuses: params.statuses,
           marketId: params.marketId,
           limit: params.limit,
         },
         opts
       ),
 
-    getRunningTwaps: (
-      params: ProviderGetRunningTwapsParams,
-      opts?: SDKRequestOptions
-    ): Promise<TwapOrder[]> =>
-      getRunningTwaps(
-        contextRef.require(),
-        { address: params.address, marketId: params.marketId },
-        opts
-      ),
-
     getOrder: (
       params: ProviderGetOrderParams,
       opts?: SDKRequestOptions

package/src/constants.ts

@@ -15,6 +15,16 @@ export const PROVIDER_KEY = 'hyperliquid'
  */
 export const DEFAULT_HYPERLIQUID_API_URL = 'https://api.hyperliquid.xyz'
 
+/**
+ * Hyperliquid explorer RPC endpoint. It serves the `userDetails` transaction
+ * window from a host separate from the REST API, and it answers a browser
+ * cross-origin POST.
+ *
+ * @public
+ */
+export const HYPERLIQUID_EXPLORER_RPC_URL =
+  'https://rpc.hyperliquid.xyz/explorer'
+
 /**
  * Approximate published baseline maker/taker fee tier for Hyperliquid, used to
  * seed fee math before the live account `feeTier` resolves. Rates are fractions

package/src/index.ts

@@ -15,6 +15,7 @@ export { projectHyperliquidConfigSettings } from './accountConfig.js'
 export { getAccountSummary } from './accountSummary.js'
 export {
   DEFAULT_HYPERLIQUID_API_URL,
+  HYPERLIQUID_EXPLORER_RPC_URL,
   HYPERLIQUID_FEE_TIER_FALLBACK,
   PROVIDER_KEY as HYPERLIQUID_PROVIDER_KEY,
 } from './constants.js'
@@ -39,8 +40,6 @@ export type { GetPortfolioHistoryParams } from './services/getPortfolioHistory.j
 export { getPortfolioHistory } from './services/getPortfolioHistory.js'
 export type { GetPositionsParams } from './services/getPositions.js'
 export { getPositions } from './services/getPositions.js'
-export type { GetRunningTwapsParams } from './services/getRunningTwaps.js'
-export { getRunningTwaps } from './services/getRunningTwaps.js'
 export type { HyperliquidAgent } from './signers/HyperliquidAgentStore.js'
 export { HyperliquidAgentStore } from './signers/HyperliquidAgentStore.js'
 export * from './types/index.js'

package/src/services/getAccount.ts

@@ -13,7 +13,7 @@ import type {
   HyperliquidAccountConfig,
   Position,
 } from '@lifi/perps-types'
-import type Big from 'big.js'
+import Big from 'big.js'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import {
@@ -26,6 +26,7 @@ import {
 import { isUnifiedAbstraction } from '../utils/abstractionMode.js'
 import { toWireBig } from '../utils/decimal.js'
 import {
+  assetIsOutcome,
   partitionSpotBalances,
   perpsDexNames,
   spotAssetFromToken,
@@ -48,8 +49,11 @@ export type GetAccountParams = ProviderGetAccountParams
 const getAccountValue = (state: HlClearinghouseState): Big =>
   toWireBig(state.marginSummary.accountValue, 'marginSummary.accountValue')
 
-const getTotalMarginUsed = (state: HlClearinghouseState): number =>
-  Number.parseFloat(state.marginSummary.totalMarginUsed)
+const getTotalMarginUsed = (state: HlClearinghouseState): Big =>
+  toWireBig(
+    state.marginSummary.totalMarginUsed,
+    'marginSummary.totalMarginUsed'
+  )
 
 const getMarginUsed = (
   abstraction: HlAbstractionMode | null,
@@ -63,25 +67,26 @@ const getMarginUsed = (
     // Per HL docs, individual per-dex states are not meaningful for these
     // modes; derive total margin from the already-mapped positions.
     const total = positions.reduce(
-      (sum, p) => sum + Number.parseFloat(p.marginUsed),
-      0
+      (sum, position) =>
+        sum.plus(toWireBig(position.marginUsed, 'positions.marginUsed')),
+      new Big(0)
     )
-    return total.toString()
+    return total.toFixed()
   }
 
   if (abstraction === HlAbstractionMode.DEX_ABSTRACTION) {
-    let total = 0
+    let total = new Big(0)
     for (const [, state] of stateByDex) {
-      total += getTotalMarginUsed(state)
+      total = total.plus(getTotalMarginUsed(state))
     }
-    return total.toString()
+    return total.toFixed()
   }
 
   const mainState = stateByDex.get('')
   if (!mainState) {
     return '0'
   }
-  return getTotalMarginUsed(mainState).toString()
+  return getTotalMarginUsed(mainState).toFixed()
 }
 
 interface BalancePartition {
@@ -98,9 +103,9 @@ const buildBalances = (
   quoteAssetByCategory: Map<string, Asset>
 ): BalancePartition => {
   const { balances, collateralBalances } = partitionSpotBalances(
-    spotState.balances.map((b) =>
-      spotBalance(spotAssetFromToken(b), b.total, priceById)
-    ),
+    spotState.balances
+      .filter((b) => !assetIsOutcome(b.coin))
+      .map((b) => spotBalance(spotAssetFromToken(b), b.total, priceById)),
     quoteAssetIds,
     abstraction === HlAbstractionMode.PORTFOLIO_MARGIN
   )
@@ -123,6 +128,7 @@ const buildBalances = (
         asset: quoteAssetByCategory.get(categoryId)!,
         units: value.toFixed(),
         valueUsd: value.toFixed(),
+        price: '1',
       })
     }
   }
@@ -216,7 +222,9 @@ export const getAccount = async (
 
   const positions: Position[] = stateResults.flatMap((state) =>
     state.assetPositions
-      .filter(isOpenAssetPosition)
+      .filter(
+        (ap) => !assetIsOutcome(ap.position.coin) && isOpenAssetPosition(ap)
+      )
       .map((ap) =>
         mapPosition(
           ap,

package/src/services/getActivity.ts

@@ -1,4 +1,9 @@
-import { getMarketRegistry, type SDKRequestOptions } from '@lifi/perps-sdk'
+import {
+  type AssetRegistry,
+  getAssetRegistry,
+  getMarketRegistry,
+  type SDKRequestOptions,
+} from '@lifi/perps-sdk'
 import type {
   ActivitiesResponse,
   ActivityItem,
@@ -14,10 +19,24 @@ import {
 } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import type {
+  HlUserFills,
   HlUserFunding,
   HlUserNonFundingLedgerUpdates,
 } from '../types/index.js'
-import { mapFundingActivity, mapLedgerEntry } from '../utils/index.js'
+import {
+  isCollateralTransferDelta,
+  isDepositDelta,
+  isLiquidationDelta,
+  isSendAssetDelta,
+  isSpotTransferDelta,
+  isVaultTransferDelta,
+  isWithdrawDelta,
+} from '../types/index.js'
+import {
+  mapFundingActivity,
+  mapLedgerEntry,
+  mapLiquidationFills,
+} from '../utils/index.js'
 import {
   hlInfoOptions,
   type InfoRequestOptions,
@@ -48,6 +67,12 @@ const MARKET_BEARING_TYPES: ReadonlySet<ActivityType> = new Set([
   ActivityType.LIQUIDATION,
 ])
 
+const ASSET_BEARING_TYPES: ReadonlySet<ActivityType> = new Set([
+  ActivityType.DEPOSIT,
+  ActivityType.WITHDRAWAL,
+  ActivityType.TRANSFER,
+])
+
 const needsMarkets = (typeFilter: ActivityType[] | undefined): boolean =>
   !typeFilter || typeFilter.some((t) => MARKET_BEARING_TYPES.has(t))
 
@@ -55,14 +80,19 @@ const fetchActivityData = async (
   apiUrl: string,
   typeFilter: ActivityType[] | undefined,
   timeParams: { user: Address; startTime?: number; endTime?: number },
+  assetRegistry: AssetRegistry,
   resolveMarket: (coin: string) => MarketDisplay | undefined,
   options?: InfoRequestOptions
 ): Promise<ActivityItem[]> => {
   const needLedger =
     !typeFilter || typeFilter.some((t) => t !== ActivityType.FUNDING)
   const needFunding = !typeFilter || typeFilter.includes(ActivityType.FUNDING)
+  // A liquidation executed as a market order reaches the account as fills
+  // with a `liquidation` field and never as a ledger `liquidation` delta.
+  const needLiquidationFills =
+    !typeFilter || typeFilter.includes(ActivityType.LIQUIDATION)
 
-  const [ledgerUpdates, fundingUpdates] = await Promise.all([
+  const [ledgerUpdates, fundingUpdates, fills] = await Promise.all([
     needLedger
       ? infoRequest<HlUserNonFundingLedgerUpdates>(
           apiUrl,
@@ -77,14 +107,38 @@ const fetchActivityData = async (
           options
         )
       : Promise.resolve([] as HlUserFunding),
+    needLiquidationFills
+      ? infoRequest<HlUserFills>(
+          apiUrl,
+          timeParams.startTime === undefined
+            ? { type: 'userFills', user: timeParams.user }
+            : { type: 'userFillsByTime', ...timeParams },
+          options
+        )
+      : Promise.resolve([] as HlUserFills),
   ])
 
   const ledgerItems: ActivityItem[] = ledgerUpdates.flatMap(
     (entry): ActivityItem[] => {
+      if (
+        typeFilter !== undefined &&
+        ((isDepositDelta(entry.delta) &&
+          !typeFilter.includes(ActivityType.DEPOSIT)) ||
+          (isWithdrawDelta(entry.delta) &&
+            !typeFilter.includes(ActivityType.WITHDRAWAL)) ||
+          (!typeFilter.includes(ActivityType.TRANSFER) &&
+            (isSpotTransferDelta(entry.delta) ||
+              isSendAssetDelta(entry.delta) ||
+              isCollateralTransferDelta(entry.delta) ||
+              isVaultTransferDelta(entry.delta))))
+      ) {
+        return []
+      }
       const item = mapLedgerEntry(
         entry,
         PROVIDER_KEY,
         timeParams.user,
+        assetRegistry,
         resolveMarket
       )
       return item === null ? [] : [item]
@@ -98,7 +152,20 @@ const fetchActivityData = async (
     }
   )
 
-  const merged = [...ledgerItems, ...fundingItems].sort(
+  const ledgerLiquidationHashes = new Set(
+    ledgerUpdates
+      .filter((entry) => isLiquidationDelta(entry.delta))
+      .map((entry) => entry.hash)
+  )
+  const liquidationItems = mapLiquidationFills(
+    fills,
+    PROVIDER_KEY,
+    timeParams.user,
+    resolveMarket,
+    ledgerLiquidationHashes
+  )
+
+  const merged = [...ledgerItems, ...fundingItems, ...liquidationItems].sort(
     (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
   )
 
@@ -112,8 +179,8 @@ const fetchActivityData = async (
 /**
  * Fetch a chronological activity feed (deposits, withdrawals, transfers,
  * liquidations, funding) for `address`. Combines results from Hyperliquid's
- * `userNonFundingLedgerUpdates` and `userFunding` endpoints, sorted
- * newest-first.
+ * `userNonFundingLedgerUpdates`, `userFunding`, and `userFills` endpoints,
+ * sorted newest-first.
  *
  * Cursor-based pagination uses the ms-since-epoch timestamp of the last item
  * on the current page.
@@ -131,6 +198,13 @@ export const getActivity = async (
   if (needsMarkets(params.type)) {
     await registry.sync()
   }
+  const assetRegistry = getAssetRegistry(client, PROVIDER_KEY)
+  if (
+    params.type === undefined ||
+    params.type.some((type) => ASSET_BEARING_TYPES.has(type))
+  ) {
+    await assetRegistry.sync()
+  }
   const infoOpts = hlInfoOptions(client, options)
 
   const limit = Math.min(
@@ -152,6 +226,7 @@ export const getActivity = async (
     apiUrl,
     params.type,
     timeParams,
+    assetRegistry,
     (coin) => registry.get(coin),
     infoOpts
   )

package/src/services/getFills.ts

@@ -12,7 +12,7 @@ import type {
   HlUserFills,
   HlUserFillsByTime,
 } from '../types/index.js'
-import { mapFill } from '../utils/index.js'
+import { assetIsOutcome, mapFill } from '../utils/index.js'
 import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
 
 /**
@@ -112,6 +112,9 @@ export const getFills = async (
   // only its own row instead of rejecting the whole page. The registry warns
   // once per unresolved id. A delisted market still resolves, so its rows stay.
   const items = page.flatMap((f): Fill[] => {
+    if (assetIsOutcome(f.coin)) {
+      return []
+    }
     const market = registry.get(f.coin)
     return market === undefined ? [] : [mapFill(f, market)]
   })

package/src/services/getOrder.ts

@@ -8,8 +8,11 @@ import type { Order } from '@lifi/perps-types'
 import { PerpsErrorCode } from '@lifi/perps-types'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
-import type { HlOrderStatusResponse } from '../types/index.js'
-import { mapOrder } from '../utils/index.js'
+import type {
+  HlOrderStatusResponse,
+  HlTwapHistoryEntry,
+} from '../types/index.js'
+import { assetIsOutcome, mapOrder } from '../utils/index.js'
 import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
 
 /**
@@ -30,11 +33,15 @@ export const getOrder = async (
   params: GetOrderParams,
   options?: SDKRequestOptions
 ): Promise<Order> => {
-  const oid = Number.parseInt(params.id, 10)
-  if (Number.isNaN(oid)) {
+  const isClientId = /^0x[0-9a-fA-F]{32}$/.test(params.id)
+  const oid = isClientId ? params.id : Number(params.id)
+  if (
+    !isClientId &&
+    (!/^[0-9]+$/.test(params.id) || !Number.isSafeInteger(oid))
+  ) {
     const err = new PerpsError(
       PerpsErrorCode.ValidationError,
-      `Invalid order ID: ${params.id}. Must be a numeric oid.`
+      `Invalid order ID: ${params.id}. Expected a numeric oid or a 128-bit cloid.`
     )
     err.tool = PROVIDER_KEY
     throw err
@@ -47,6 +54,23 @@ export const getOrder = async (
   )
 
   if (status.status !== 'order') {
+    const history = await infoRequest<HlTwapHistoryEntry[]>(
+      apiUrl,
+      { type: 'twapHistory', user: params.address },
+      hlInfoOptions(client, options)
+    )
+    const twap = history.find(
+      (entry) =>
+        String(entry.twapId) === params.id && !assetIsOutcome(entry.state.coin)
+    )
+    if (twap !== undefined) {
+      const registry = getMarketRegistry(client, PROVIDER_KEY)
+      await registry.sync()
+      return mapOrder(twap, registry.require(twap.state.coin))
+    }
+  }
+
+  if (status.status !== 'order' || assetIsOutcome(status.order.order.coin)) {
     const err = new PerpsError(
       PerpsErrorCode.OrderNotFound,
       `Order not found: ${params.id}`