@lifi/perps-sdk-provider-hyperliquid 16.0.0 → 17.0.0

package/dist/types/utils/transferMargin.d.ts

@@ -1,14 +1,18 @@
-import { type Position, type PositionMarginConstraints } from '@lifi/perps-types';
+import { type Position } from '@lifi/perps-types';
 /**
- * Hyperliquid's exact documented transfer-margin requirement:
- * `max(initial_margin_required, 0.1 * total_position_value)`.
- *
- * Strict-isolated markets still return constraints because margin can be
- * added; their market capability prevents removal. Cross positions and
- * markets without individual margin adjustment return `undefined`.
+ * Hyperliquid removable isolated margin:
+ * `marginUsed − max(initial_margin_required, 0.1 × total_position_value)`.
+ * Hyperliquid isolated `marginUsed` already includes the unrealized PnL of
+ * the position, so the PnL is not added again, and it can reach zero or less
+ * before liquidation.
  *
+ * @returns `undefined` for cross positions and markets without individual
+ *   margin adjustment; `'0'` for add-only strict-isolated markets and when
+ *   nothing is removable.
+ * @throws {PerpsError} `ValidationError` when a required `Position` decimal
+ *   is malformed, or when a size, price or requirement is not positive.
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/trading/margining
  * @public
  */
-export declare function positionMarginConstraints(position: Position): PositionMarginConstraints | undefined;
+export declare function positionRemovableMargin(position: Position): string | undefined;
 //# sourceMappingURL=transferMargin.d.ts.map

package/dist/types/utils/transferMargin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transferMargin.d.ts","sourceRoot":"","sources":["../../../src/utils/transferMargin.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,yBAAyB,EAE/B,MAAM,mBAAmB,CAAA;AAyB1B;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,GACjB,yBAAyB,GAAG,SAAS,CAoBvC"}
+{"version":3,"file":"transferMargin.d.ts","sourceRoot":"","sources":["../../../src/utils/transferMargin.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,QAAQ,EAGd,MAAM,mBAAmB,CAAA;AA4B1B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,GACjB,MAAM,GAAG,SAAS,CAwBpB"}

package/dist/types/utils/withdrawableBalances.d.ts

@@ -8,7 +8,9 @@ import type { HlAbstractionMode, HlClearinghouseState, HlSpotClearinghouseState
  * per-asset venue minimum.
  *
  * @param quoteAssetId - `Asset.id` the perps-route row is keyed by.
+ * @param withdrawalFee - Flat venue fee in quote-asset units, set on every
+ *   quote-asset row. Absent leaves every row without a fee.
  * @public
  */
-export declare const hyperliquidWithdrawableBalances: (abstraction: HlAbstractionMode | null, state: HlClearinghouseState, spotState: HlSpotClearinghouseState, quoteAssetId: string) => ProviderWithdrawableBalance[];
+export declare const hyperliquidWithdrawableBalances: (abstraction: HlAbstractionMode | null, state: HlClearinghouseState, spotState: HlSpotClearinghouseState, quoteAssetId: string, withdrawalFee?: string) => ProviderWithdrawableBalance[];
 //# sourceMappingURL=withdrawableBalances.d.ts.map

package/dist/types/utils/withdrawableBalances.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withdrawableBalances.d.ts","sourceRoot":"","sources":["../../../src/utils/withdrawableBalances.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAA;AAClE,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,mBAAmB,CAAA;AAK1B;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,GAC1C,aAAa,iBAAiB,GAAG,IAAI,EACrC,OAAO,oBAAoB,EAC3B,WAAW,wBAAwB,EACnC,cAAc,MAAM,KACnB,2BAA2B,EA+B7B,CAAA"}
+{"version":3,"file":"withdrawableBalances.d.ts","sourceRoot":"","sources":["../../../src/utils/withdrawableBalances.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAA;AAClE,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,mBAAmB,CAAA;AAK1B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,+BAA+B,GAC1C,aAAa,iBAAiB,GAAG,IAAI,EACrC,OAAO,oBAAoB,EAC3B,WAAW,wBAAwB,EACnC,cAAc,MAAM,EACpB,gBAAgB,MAAM,KACrB,2BAA2B,EAwC7B,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk-provider-hyperliquid",
-  "version": "16.0.0",
+  "version": "17.0.0",
   "description": "Hyperliquid provider plugin for @lifi/perps-sdk",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -49,10 +49,10 @@
   "dependencies": {
     "big.js": "^7.0.1",
     "viem": "^2.55.18",
-    "@lifi/perps-types": "^15.0.0"
+    "@lifi/perps-types": "^16.0.0"
   },
   "peerDependencies": {
-    "@lifi/perps-sdk": "^16.0.0"
+    "@lifi/perps-sdk": "^17.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/HyperliquidProvider.ts

@@ -80,7 +80,7 @@ import type { HlExtraAgents } from './types/index.js'
 import { hlInfoOptions, infoRequest } from './utils/infoClient.js'
 import { calculateLiquidationPrice } from './utils/liquidation.js'
 import { formatOrderPrice, formatOrderSize } from './utils/orderFormatting.js'
-import { positionMarginConstraints } from './utils/transferMargin.js'
+import { positionRemovableMargin } from './utils/transferMargin.js'
 
 /**
  * Options for {@link hyperliquidProvider}.
@@ -452,7 +452,7 @@ export function hyperliquidProvider(
         market.maxLeverage
       ),
 
-    positionMarginConstraints,
+    positionRemovableMargin,
 
     projectConfig: (
       config: AccountConfig,

package/src/services/getOrder.ts

@@ -12,6 +12,7 @@ import type {
   HlOrderStatusResponse,
   HlTwapHistoryEntry,
 } from '../types/index.js'
+import { withExplorerLinks } from '../utils/explorer.js'
 import { assetIsOutcome, mapOrder } from '../utils/index.js'
 import { hlInfoOptions, infoRequest } from '../utils/infoClient.js'
 
@@ -47,17 +48,18 @@ export const getOrder = async (
     throw err
   }
 
+  const infoOpts = hlInfoOptions(client, options)
   const status = await infoRequest<HlOrderStatusResponse>(
     apiUrl,
     { type: 'orderStatus', user: params.address, oid },
-    hlInfoOptions(client, options)
+    infoOpts
   )
 
   if (status.status !== 'order') {
     const history = await infoRequest<HlTwapHistoryEntry[]>(
       apiUrl,
       { type: 'twapHistory', user: params.address },
-      hlInfoOptions(client, options)
+      infoOpts
     )
     const twap = history.find(
       (entry) =>
@@ -81,5 +83,10 @@ export const getOrder = async (
 
   const registry = getMarketRegistry(client, PROVIDER_KEY)
   await registry.sync()
-  return mapOrder(status.order, registry.require(status.order.order.coin))
+  const order = mapOrder(
+    status.order,
+    registry.require(status.order.order.coin)
+  )
+  const [linked] = await withExplorerLinks([order], params.address, infoOpts)
+  return linked
 }

package/src/services/getOrders.ts

@@ -1,8 +1,6 @@
 import {
   ACTIVE_ORDER_STATUSES,
   createWarnOnce,
-  ExplorerChainId,
-  explorerTxUrl,
   getMarketRegistry,
   isActiveOrderStatus,
   type MarketRegistry,
@@ -14,34 +12,21 @@ import type { MarketDisplay, Order, OrdersResponse } from '@lifi/perps-types'
 import { PROVIDER_KEY } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import type {
-  HlExplorerTx,
   HlFrontendOpenOrders,
   HlHistoricalOrders,
   HlTwapHistoryEntry,
 } from '../types/index.js'
-import {
-  assetIsOutcome,
-  fetchUserTransactions,
-  mapOrder,
-  matchOrderActionHash,
-  perpsDexNames,
-} from '../utils/index.js'
-import {
-  hlInfoOptions,
-  type InfoRequestOptions,
-  infoRequest,
-} from '../utils/infoClient.js'
+import { withExplorerLinks } from '../utils/explorer.js'
+import { assetIsOutcome, mapOrder, perpsDexNames } from '../utils/index.js'
+import { hlInfoOptions, 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}`}`
-  )
+const warnOnce = (key: string): void => {
+  warn(key, `[${PROVIDER_KEY}] ${key}`)
 }
 
 /**
@@ -73,42 +58,6 @@ const mapRow = (
   }
 }
 
-/**
- * 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,

package/src/services/getWithdrawableBalances.ts

@@ -1,5 +1,6 @@
 import {
   getMarketRegistry,
+  getProviders,
   PerpsError,
   type ProviderGetWithdrawableBalancesParams,
   type ProviderWithdrawableBalance,
@@ -27,13 +28,15 @@ export type GetWithdrawableBalancesParams =
 /**
  * The `(asset, route)` pairs `params.address` can withdraw from Hyperliquid,
  * read from the venue's own `withdrawable` and spot `total`/`hold` figures.
+ * Hyperliquid charges its flat withdrawal fee in USDC, so the backend's
+ * `withdrawalFeeUsd` is the fee in quote-asset units on every USDC row.
  *
  * Only the main perps dex is read: a withdrawal to L1 draws on that account,
  * and a sub-dex balance reaches it through a transfer first.
  *
- * @throws {PerpsError} On Hyperliquid REST error, network, or parsing
- * failures, and `SDKError` when the market registry carries no main perps
- * market to name the quote asset.
+ * @throws {PerpsError} On Hyperliquid REST or backend `/providers` error,
+ * network, or parsing failures, and `SDKError` when the market registry
+ * carries no main perps market to name the quote asset.
  * @public
  */
 export const getWithdrawableBalances = async (
@@ -44,24 +47,26 @@ export const getWithdrawableBalances = async (
   const registry = getMarketRegistry(client, PROVIDER_KEY)
   const infoOpts = hlInfoOptions(client, options)
 
-  const [markets, abstraction, state, spotState] = await Promise.all([
-    registry.sync(),
-    infoRequest<HlAbstractionMode | null>(
-      apiUrl,
-      { type: 'userAbstraction', user: params.address },
-      infoOpts
-    ),
-    infoRequest<HlClearinghouseState>(
-      apiUrl,
-      { type: 'clearinghouseState', user: params.address },
-      infoOpts
-    ),
-    infoRequest<HlSpotClearinghouseState>(
-      apiUrl,
-      { type: 'spotClearinghouseState', user: params.address },
-      infoOpts
-    ),
-  ])
+  const [{ providers }, markets, abstraction, state, spotState] =
+    await Promise.all([
+      getProviders(client, options),
+      registry.sync(),
+      infoRequest<HlAbstractionMode | null>(
+        apiUrl,
+        { type: 'userAbstraction', user: params.address },
+        infoOpts
+      ),
+      infoRequest<HlClearinghouseState>(
+        apiUrl,
+        { type: 'clearinghouseState', user: params.address },
+        infoOpts
+      ),
+      infoRequest<HlSpotClearinghouseState>(
+        apiUrl,
+        { type: 'spotClearinghouseState', user: params.address },
+        infoOpts
+      ),
+    ])
 
   const quoteAsset = markets.find(
     (market) => market.categoryId === MAIN_MARKET_ID
@@ -75,10 +80,15 @@ export const getWithdrawableBalances = async (
     throw error
   }
 
+  const feeUsd = providers.find(
+    (provider) => provider.key === PROVIDER_KEY
+  )?.withdrawalFeeUsd
+
   return hyperliquidWithdrawableBalances(
     abstraction,
     state,
     spotState,
-    quoteAsset.id
+    quoteAsset.id,
+    feeUsd === undefined ? undefined : String(feeUsd)
   )
 }

package/src/utils/explorer.ts

@@ -1,6 +1,12 @@
-import type { OrderBase } from '@lifi/perps-types'
+import {
+  createWarnOnce,
+  ExplorerChainId,
+  explorerTxUrl,
+  PerpsError,
+} from '@lifi/perps-sdk'
+import type { Order, OrderBase } from '@lifi/perps-types'
 import { isHex } from 'viem'
-import { HYPERLIQUID_EXPLORER_RPC_URL } from '../constants.js'
+import { HYPERLIQUID_EXPLORER_RPC_URL, PROVIDER_KEY } from '../constants.js'
 import { type HlExplorerTx, isHlExplorerTx } from '../types/explorer.js'
 import { hlPostJson, type InfoRequestOptions } from './infoClient.js'
 
@@ -91,3 +97,46 @@ export const matchOrderActionHash = (
   )
   return match?.hash
 }
+
+const warn = createWarnOnce()
+
+/**
+ * Set `explorerLink` on each order whose placement transaction the explorer
+ * window still holds. One explorer read serves every order, and it is skipped
+ * when no order carries a client order id to match on. The link is
+ * supplementary, so an explorer failure warns and leaves the orders unlinked
+ * instead of failing the order read. A caller cancellation still rejects.
+ */
+export 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) {
+    // `hlPostJson` wraps a signal timeout as a `ServerError`, so the signal,
+    // not the error type, tells a caller cancellation from an explorer failure.
+    if (!(error instanceof PerpsError) || options.signal?.aborted) {
+      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.
+    warn(
+      'explorer link lookup failed',
+      `[${PROVIDER_KEY}] 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 }
+  })
+}

package/src/utils/index.ts

@@ -56,7 +56,7 @@ export {
   spotPriceById,
 } from './spotBalance.js'
 export { partitionSpotBalances, type SpotPartition } from './spotCollateral.js'
-export { positionMarginConstraints } from './transferMargin.js'
+export { positionRemovableMargin } from './transferMargin.js'
 export {
   type DexMarginSummary,
   perpsTotals,

package/src/utils/transferMargin.ts

@@ -2,24 +2,27 @@ import { PerpsError } from '@lifi/perps-sdk'
 import {
   PerpsErrorCode,
   type Position,
-  type PositionMarginConstraints,
   positionSupportsMarginAdjustment,
+  positionSupportsMarginRemoval,
 } from '@lifi/perps-types'
 import Big from 'big.js'
 
 const NOTIONAL_FLOOR_RATIO = '0.1'
-const AMOUNT_INCREMENT = '0.000001'
+const AMOUNT_DECIMALS = 6
 
-function positivePositionAmount(value: string, field: string): Big {
-  let amount: Big
+function positionAmount(value: string, field: string): Big {
   try {
-    amount = new Big(value)
+    return new Big(value)
   } catch {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
       `Invalid decimal string on Position.${field}: '${value}'`
     )
   }
+}
+
+function positivePositionAmount(value: string, field: string): Big {
+  const amount = positionAmount(value, field)
   if (amount.lte(0)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
@@ -30,36 +33,44 @@ function positivePositionAmount(value: string, field: string): Big {
 }
 
 /**
- * Hyperliquid's exact documented transfer-margin requirement:
- * `max(initial_margin_required, 0.1 * total_position_value)`.
- *
- * Strict-isolated markets still return constraints because margin can be
- * added; their market capability prevents removal. Cross positions and
- * markets without individual margin adjustment return `undefined`.
+ * Hyperliquid removable isolated margin:
+ * `marginUsed − max(initial_margin_required, 0.1 × total_position_value)`.
+ * Hyperliquid isolated `marginUsed` already includes the unrealized PnL of
+ * the position, so the PnL is not added again, and it can reach zero or less
+ * before liquidation.
  *
+ * @returns `undefined` for cross positions and markets without individual
+ *   margin adjustment; `'0'` for add-only strict-isolated markets and when
+ *   nothing is removable.
+ * @throws {PerpsError} `ValidationError` when a required `Position` decimal
+ *   is malformed, or when a size, price or requirement is not positive.
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/trading/margining
  * @public
  */
-export function positionMarginConstraints(
+export function positionRemovableMargin(
   position: Position
-): PositionMarginConstraints | undefined {
+): string | undefined {
   if (!positionSupportsMarginAdjustment(position)) {
     return undefined
   }
+  if (!positionSupportsMarginRemoval(position)) {
+    return '0'
+  }
+  const marginUsed = positionAmount(position.marginUsed, 'marginUsed')
   const initialMargin = positivePositionAmount(
     position.initialMarginRequirement,
     'initialMarginRequirement'
   )
-  const notional = positivePositionAmount(position.size, 'size').times(
-    positivePositionAmount(position.markPrice, 'markPrice')
-  )
-  const notionalFloor = notional.times(NOTIONAL_FLOOR_RATIO)
+  const notionalFloor = positivePositionAmount(position.size, 'size')
+    .times(positivePositionAmount(position.markPrice, 'markPrice'))
+    .times(NOTIONAL_FLOOR_RATIO)
   const minimumMargin = initialMargin.gt(notionalFloor)
     ? initialMargin
     : notionalFloor
 
-  return {
-    minimumMarginRequirement: minimumMargin.toFixed(),
-    amountIncrement: AMOUNT_INCREMENT,
+  const removable = marginUsed.minus(minimumMargin)
+  if (removable.lte(0)) {
+    return '0'
   }
+  return removable.round(AMOUNT_DECIMALS, Big.roundDown).toFixed()
 }

package/src/utils/withdrawableBalances.ts

@@ -16,15 +16,24 @@ import { toWireBig } from './decimal.js'
  * per-asset venue minimum.
  *
  * @param quoteAssetId - `Asset.id` the perps-route row is keyed by.
+ * @param withdrawalFee - Flat venue fee in quote-asset units, set on every
+ *   quote-asset row. Absent leaves every row without a fee.
  * @public
  */
 export const hyperliquidWithdrawableBalances = (
   abstraction: HlAbstractionMode | null,
   state: HlClearinghouseState,
   spotState: HlSpotClearinghouseState,
-  quoteAssetId: string
+  quoteAssetId: string,
+  withdrawalFee?: string
 ): ProviderWithdrawableBalance[] => {
   const rows: ProviderWithdrawableBalance[] = []
+  const fee =
+    withdrawalFee === undefined
+      ? undefined
+      : toWireBig(withdrawalFee, 'providers.withdrawalFeeUsd').toFixed()
+  const feeFor = (assetId: string) =>
+    fee === undefined || assetId !== quoteAssetId ? {} : { withdrawalFee: fee }
 
   if (isUnifiedAbstraction(abstraction)) {
     for (const balance of spotState.balances) {
@@ -35,10 +44,12 @@ export const hyperliquidWithdrawableBalances = (
         toWireBig(balance.hold, 'spotBalance.hold')
       )
       if (spot.gt(0)) {
+        const assetId = String(balance.token)
         rows.push({
-          assetId: String(balance.token),
+          assetId,
           route: 'spot',
           available: spot.toFixed(),
+          ...feeFor(assetId),
         })
       }
     }
@@ -50,6 +61,7 @@ export const hyperliquidWithdrawableBalances = (
       assetId: quoteAssetId,
       route: 'perps',
       available: perps.toFixed(),
+      ...feeFor(quoteAssetId),
     })
   }