@lifi/perps-sdk-provider-hyperliquid 18.1.1 → 20.0.0

package/src/HyperliquidProvider.ts

@@ -30,6 +30,7 @@ import {
   type AccountConfigSetting,
   type AccountResponse,
   type AccountSummary,
+  type ActionResult,
   type ActionStep,
   ActionType,
   type ActivitiesResponse,
@@ -45,8 +46,8 @@ import {
   type PortfolioHistoryResponse,
   type Position,
   type PositionsResponse,
-  type ProviderAction,
   type Quote,
+  type SetupAction,
   type SignedActionStep,
   type SigningMethod,
 } from '@lifi/perps-types'
@@ -229,8 +230,6 @@ export function hyperliquidProvider(
   return {
     type: PROVIDER_KEY,
 
-    internalSetupActions: [ActionType.SET_REFERRAL],
-
     // REVOKE_AGENT stages a step only when every named agent slot is taken,
     // so `checkSetup` omits it from `ProviderSetup.checklist` instead of
     // rendering it as a satisfied step.
@@ -254,7 +253,7 @@ export function hyperliquidProvider(
     resolveActionRequest: async (
       action: ActionType,
       address: Address,
-      signers: PerpsSigner[]
+      signer: PerpsSigner
     ): Promise<ActionSignerContribution> => {
       // APPROVE_AGENT is user-signed: the user authorises the agent, so the
       // agent address rides as a param (not signerAddress). The agent is
@@ -264,10 +263,30 @@ export function hyperliquidProvider(
         const agentAddress = await resolveApproveAgentAddress(address)
         return { params: { agentAddress } }
       }
-      // SDK-signed actions (trades, account-mode) carry the agent as the
-      // on-wire signerAddress. User-signed actions (builder-fee, withdrawal)
-      // contribute nothing — core submits under the user's own address.
-      if (signers.includes(PerpsSigner.SDK)) {
+      // REVOKE_SESSION_AGENT targets the stored agent by address and never
+      // provisions one: with no stored agent there is nothing to revoke.
+      if (action === ActionType.REVOKE_SESSION_AGENT) {
+        try {
+          const agent = await agentStore.get(address)
+          return { params: { agentAddress: agent.address } }
+        } catch (error) {
+          if (
+            error instanceof PerpsError &&
+            error.message === PerpsErrorMessage.AgentNotFound
+          ) {
+            throw new PerpsError(
+              PerpsErrorCode.SDKError,
+              `Nothing to revoke for '${action}' on '${PROVIDER_KEY}': no session agent is stored for ${address}.`
+            )
+          }
+          throw error
+        }
+      }
+      // SDK-signed actions (trades) carry the agent as the on-wire
+      // signerAddress. User-signed actions (builder-fee, account mode,
+      // withdrawal) contribute nothing — core submits under the user's own
+      // address.
+      if (signer === PerpsSigner.SDK) {
         const agent = await agentStore.get(address)
         return { signerAddress: agent.address }
       }
@@ -282,6 +301,21 @@ export function hyperliquidProvider(
     ): Promise<SignedActionStep[]> =>
       hyperliquidSignActions(agentStore, method, steps, address, ctx),
 
+    // A confirmed session-agent revoke leaves the stored key unusable.
+    onExecuteResults: async (
+      address: Address,
+      results: ActionResult[]
+    ): Promise<void> => {
+      if (
+        results.some(
+          (result) =>
+            result.success && result.action === ActionType.REVOKE_SESSION_AGENT
+        )
+      ) {
+        await agentStore.remove(address)
+      }
+    },
+
     getAccount: (
       params: ProviderGetAccountParams,
       opts?: SDKRequestOptions
@@ -329,7 +363,7 @@ export function hyperliquidProvider(
     getMarketSettings: (
       params: ProviderGetMarketSettingsParams,
       opts?: SDKRequestOptions
-    ): Promise<MarketSettings | undefined> =>
+    ): Promise<MarketSettings> =>
       getMarketSettings(
         contextRef.require(),
         { address: params.address, market: params.market },
@@ -456,8 +490,7 @@ export function hyperliquidProvider(
 
     projectConfig: (
       config: AccountConfig,
-      setup: ProviderAction[],
-      options: ProviderAction[]
+      setup: SetupAction[]
     ): AccountConfigSetting[] => {
       if (config.provider !== PROVIDER_KEY) {
         throw new PerpsError(
@@ -466,7 +499,7 @@ export function hyperliquidProvider(
             `'${config.provider}'.`
         )
       }
-      return projectHyperliquidConfigSettings(config, setup, options)
+      return projectHyperliquidConfigSettings(config, setup)
     },
   }
 }

package/src/accountConfig.ts

@@ -1,10 +1,18 @@
-import { PerpsError } from '@lifi/perps-sdk'
+import { isSetupOptionFor, PerpsError } from '@lifi/perps-sdk'
 import type {
   AccountConfigSetting,
   HyperliquidAccountConfig,
-  ProviderAction,
+  SetupAction,
 } from '@lifi/perps-types'
 import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
+import { HlAbstractionMode } from './types/account.js'
+
+// `null`, `'default'` and `'disabled'` are the same off state; an option may
+// bind either spelling of it.
+const ABSTRACTION_OFF_VALUES: ReadonlySet<string> = new Set([
+  HlAbstractionMode.DEFAULT,
+  HlAbstractionMode.DISABLED,
+])
 
 function assertNever(value: never): never {
   throw new Error(
@@ -24,14 +32,14 @@ function assertNever(value: never): never {
  * | REVOKE_AGENT          | []                  (no parameters)
  * | APPROVE_BUILDER_FEE   | []                  (no parameters)
  * | SET_REFERRAL          | []                  (no parameters)
- * | ACCOUNT_MODE          | [{ name: 'mode', value: config.abstractionMode }]
+ * | ACCOUNT_MODE          | [{ name: 'mode', value: config.abstractionMode }] (off → bound off spelling)
  *
  * The switch is exhaustive over `ActionType` so enum additions force a
  * compile error in the `default` arm. ActionTypes that are not valid on
- * `Provider.setup` / `Provider.options` for Hyperliquid throw at runtime.
+ * `Provider.setup` for Hyperliquid throw at runtime.
  */
 function projectHyperliquidDescriptor(
-  descriptor: ProviderAction,
+  descriptor: SetupAction,
   config: HyperliquidAccountConfig
 ): AccountConfigSetting {
   switch (descriptor.type) {
@@ -41,11 +49,25 @@ function projectHyperliquidDescriptor(
     case ActionType.SET_REFERRAL:
       return { type: descriptor.type, values: [] }
 
-    case ActionType.ACCOUNT_MODE:
+    case ActionType.ACCOUNT_MODE: {
+      const mode = config.abstractionMode
+      const bound = (descriptor.options ?? []).flatMap((option) =>
+        isSetupOptionFor(option, ActionType.ACCOUNT_MODE)
+          ? [option.params.mode]
+          : []
+      )
+      // The off state projects as whichever off spelling an option binds, so
+      // the value always matches the option it is satisfied by.
+      const matched =
+        mode === null || ABSTRACTION_OFF_VALUES.has(mode)
+          ? bound.find((value) => ABSTRACTION_OFF_VALUES.has(value))
+          : bound.find((value) => value === mode)
       return {
         type: descriptor.type,
-        values: [{ name: 'mode', value: config.abstractionMode }],
+        values: [{ name: 'mode', value: matched ?? mode }],
+        satisfied: matched !== undefined,
       }
+    }
 
     case ActionType.APPROVE_INTEGRATOR:
     case ActionType.ACCOUNT_TYPE:
@@ -73,11 +95,14 @@ function projectHyperliquidDescriptor(
     case ActionType.META_ONBOARD:
     case ActionType.META_CREATE_REFERRAL_CODE:
     case ActionType.SYNC_FEE_ATTRIBUTION:
+    case ActionType.REVOKE_BUILDER_FEE:
+    case ActionType.REVOKE_SESSION_AGENT:
+    case ActionType.REVOKE_INTEGRATOR:
       throw new PerpsError(
         PerpsErrorCode.SDKError,
         `Hyperliquid account-config mapper has no projection for ` +
           `descriptor type '${descriptor.type}' — this ActionType is not ` +
-          `valid on Provider.setup / Provider.options for Hyperliquid.`
+          `valid on Provider.setup for Hyperliquid.`
       )
 
     default:
@@ -86,18 +111,17 @@ function projectHyperliquidDescriptor(
 }
 
 /**
- * Project the union of Hyperliquid setup + options descriptors against the
- * typed `HyperliquidAccountConfig`. Produces exactly one
- * `AccountConfigSetting` per descriptor, in `setup`-then-`options` order.
+ * Project the Hyperliquid setup descriptors against the typed
+ * `HyperliquidAccountConfig`. Produces exactly one `AccountConfigSetting` per
+ * descriptor, in `Provider.setup` order.
  *
  * @public
  */
 export function projectHyperliquidConfigSettings(
   config: HyperliquidAccountConfig,
-  setup: ProviderAction[],
-  options: ProviderAction[]
+  setup: SetupAction[]
 ): AccountConfigSetting[] {
-  return [...setup, ...options].map((descriptor) =>
+  return setup.map((descriptor) =>
     projectHyperliquidDescriptor(descriptor, config)
   )
 }

package/src/services/getAccount.ts

@@ -1,6 +1,8 @@
 import {
   getMarketRegistry,
   getMarketsContext,
+  maxOf,
+  minOf,
   type ProviderGetAccountParams,
   type SDKRequestOptions,
   stringToFloat,
@@ -14,7 +16,7 @@ import type {
   HyperliquidDexAccountState,
   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 type {
@@ -66,13 +68,6 @@ interface BalancePartition {
   collateralBalances: Balance[]
 }
 
-const transferableWithin = (venueFigure: Big, units: Big): string => {
-  if (venueFigure.lt(0)) {
-    return '0'
-  }
-  return (venueFigure.gt(units) ? units : venueFigure).toFixed()
-}
-
 const buildBalances = (
   abstraction: HlAbstractionMode | null,
   spotState: HlSpotClearinghouseState,
@@ -84,7 +79,19 @@ const buildBalances = (
   const { balances, collateralBalances } = partitionSpotBalances(
     spotState.balances
       .filter((b) => !assetIsOutcome(b.coin))
-      .map((b) => spotBalance(spotAssetFromToken(b), b.total, priceById)),
+      .map((b) => {
+        const total = toWireBig(b.total, 'spotClearinghouseState.total')
+        return {
+          ...spotBalance(spotAssetFromToken(b), b.total, priceById),
+          transferable: minOf(
+            maxOf(
+              total.minus(toWireBig(b.hold, 'spotClearinghouseState.hold')),
+              new Big(0)
+            ),
+            total
+          ).toFixed(),
+        }
+      }),
     quoteAssetIds
   )
 
@@ -107,10 +114,13 @@ const buildBalances = (
         units: value.toFixed(),
         valueUsd: value.toFixed(),
         price: '1',
-        transferable: transferableWithin(
-          toWireBig(state.withdrawable, 'clearinghouseState.withdrawable'),
+        transferable: minOf(
+          maxOf(
+            toWireBig(state.withdrawable, 'clearinghouseState.withdrawable'),
+            new Big(0)
+          ),
           value
-        ),
+        ).toFixed(),
       })
     }
   }

package/src/services/getActivity.ts

@@ -24,7 +24,9 @@ import type {
   HlUserNonFundingLedgerUpdates,
 } from '../types/index.js'
 import {
+  isBorrowLendDelta,
   isCollateralTransferDelta,
+  isCStakingTransferDelta,
   isDepositDelta,
   isLiquidationDelta,
   isSendAssetDelta,
@@ -130,7 +132,9 @@ const fetchActivityData = async (
             (isSpotTransferDelta(entry.delta) ||
               isSendAssetDelta(entry.delta) ||
               isCollateralTransferDelta(entry.delta) ||
-              isVaultTransferDelta(entry.delta))))
+              isVaultTransferDelta(entry.delta) ||
+              isCStakingTransferDelta(entry.delta) ||
+              isBorrowLendDelta(entry.delta))))
       ) {
         return []
       }

package/src/services/getMarketSettings.ts

@@ -1,11 +1,12 @@
-import type { SDKRequestOptions } from '@lifi/perps-sdk'
+import { PerpsError, type SDKRequestOptions } from '@lifi/perps-sdk'
 import {
   MarginMode,
   type MarketRef,
   type MarketSettings,
+  PerpsErrorCode,
 } from '@lifi/perps-types'
 import type { Address } from 'viem'
-import { SPOT_MARKET_ID } from '../constants.js'
+import { PROVIDER_KEY, SPOT_MARKET_ID } from '../constants.js'
 import type { HyperliquidContext } from '../context.js'
 import { fetchActiveAssetData } from './activeAssetData.js'
 
@@ -22,17 +23,23 @@ export interface GetMarketSettingsParams {
 /**
  * The user's venue-stored margin mode and leverage for one perps market,
  * read from `activeAssetData` — present whether or not a position is open.
- * @throws {PerpsError} On Hyperliquid REST error, network, or parsing failures.
+ * @throws {PerpsError} `ValidationError` for a spot market; `SDKError` when
+ *   the response carries no positive leverage; any other `PerpsError` on
+ *   Hyperliquid REST error, network, or parsing failures.
  * @public
  */
 export const getMarketSettings = async (
   context: HyperliquidContext,
   params: GetMarketSettingsParams,
   options?: SDKRequestOptions
-): Promise<MarketSettings | undefined> => {
-  // Spot markets carry no leverage state on the venue.
+): Promise<MarketSettings> => {
   if (params.market.categoryId === SPOT_MARKET_ID) {
-    return undefined
+    const error = new PerpsError(
+      PerpsErrorCode.ValidationError,
+      `Hyperliquid market '${params.market.marketId}' is a spot market and carries no leverage setting`
+    )
+    error.tool = PROVIDER_KEY
+    throw error
   }
   const data = await fetchActiveAssetData(
     context,
@@ -41,8 +48,13 @@ export const getMarketSettings = async (
     options
   )
   const leverage = data.leverage
-  if (!leverage) {
-    return undefined
+  if (!leverage || !(leverage.value > 0)) {
+    const error = new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Hyperliquid returned no leverage for market '${params.market.marketId}'`
+    )
+    error.tool = PROVIDER_KEY
+    throw error
   }
   return {
     marginMode:

package/src/signers/signActions.ts

@@ -39,9 +39,10 @@ export async function hyperliquidSignActions(
     )
   }
 
-  const sign = ctx?.signers?.includes(PerpsSigner.USER)
-    ? await userWalletSigner(ctx)
-    : await agentSigner(agentStore, address)
+  const sign =
+    ctx?.signer === PerpsSigner.USER
+      ? await userWalletSigner(ctx)
+      : await agentSigner(agentStore, address)
 
   return Promise.all(
     (steps as Eip712ActionStep[]).map(

package/src/types/ledger.ts

@@ -130,6 +130,38 @@ export type HlLiquidationDelta = {
   liquidatedPositions?: HlLiquidatedPosition[]
 }
 
+/**
+ * Hyperliquid `cStakingTransfer` ledger delta. Moves `token` between the
+ * account's spot balance and its staking balance; `isDeposit` is `true` for a
+ * move into staking. `amount` is unsigned. A completed unstake row carries the
+ * zero hash.
+ * @public
+ */
+export type HlCStakingTransferDelta = {
+  type: 'cStakingTransfer'
+  token: string
+  amount: string
+  isDeposit: boolean
+}
+
+/** Borrow-lend market action named by a `borrowLend` ledger delta. @public */
+export type HlBorrowLendOperation = 'supply' | 'withdraw' | 'borrow' | 'repay'
+
+/**
+ * Hyperliquid `borrowLend` ledger delta. Moves `token` between the account's
+ * spot balance and the borrow-lend market; `operation` gives the direction and
+ * `amount` is unsigned. `interestAmount` is the accrued interest that
+ * `amount` includes on a `withdraw` or `repay`, and `"0.0"` otherwise.
+ * @public
+ */
+export type HlBorrowLendDelta = {
+  type: 'borrowLend'
+  token: string
+  operation: HlBorrowLendOperation
+  amount: string
+  interestAmount: string
+}
+
 /**
  * Union of known Hyperliquid non-funding ledger deltas plus an open fallback
  * for endpoint variants the provider does not map.
@@ -143,6 +175,8 @@ export type HlLedgerDelta =
   | HlDepositDelta
   | HlWithdrawDelta
   | HlLiquidationDelta
+  | HlCStakingTransferDelta
+  | HlBorrowLendDelta
   | {
       type: string
       usdc?: string
@@ -202,6 +236,33 @@ export const isLiquidationDelta = (
   delta: HlLedgerDelta
 ): delta is HlLiquidationDelta => delta.type === 'liquidation'
 
+/**
+ * Type guard for `HlCStakingTransferDelta`. `isDeposit` is part of the guard:
+ * a row without a boolean `isDeposit` names no direction for the movement.
+ * @public
+ */
+export const isCStakingTransferDelta = (
+  delta: HlLedgerDelta
+): delta is HlCStakingTransferDelta =>
+  delta.type === 'cStakingTransfer' &&
+  'isDeposit' in delta &&
+  typeof delta.isDeposit === 'boolean'
+
+const HL_BORROW_LEND_OPERATIONS: ReadonlySet<unknown> =
+  new Set<HlBorrowLendOperation>(['supply', 'withdraw', 'borrow', 'repay'])
+
+/**
+ * Type guard for `HlBorrowLendDelta`. The operation is part of the guard: an
+ * unknown operation names no direction for the movement.
+ * @public
+ */
+export const isBorrowLendDelta = (
+  delta: HlLedgerDelta
+): delta is HlBorrowLendDelta =>
+  delta.type === 'borrowLend' &&
+  'operation' in delta &&
+  HL_BORROW_LEND_OPERATIONS.has(delta.operation)
+
 /**
  * One timestamped non-funding ledger update. `time` is milliseconds since
  * epoch and `hash` is the upstream transaction identifier.

package/src/utils/mapActivity.ts

@@ -17,13 +17,17 @@ import type {
 } from '@lifi/perps-types'
 import { ActivityType, PerpsErrorCode } from '@lifi/perps-types'
 import Big from 'big.js'
+import { zeroHash } from 'viem'
 import type {
+  HlBorrowLendOperation,
   HlFundingUpdate,
   HlLedgerUpdate,
   HlUserFill,
 } from '../types/index.js'
 import {
+  isBorrowLendDelta,
   isCollateralTransferDelta,
+  isCStakingTransferDelta,
   isDepositDelta,
   isLiquidationDelta,
   isSendAssetDelta,
@@ -47,6 +51,17 @@ const HL_NATIVE_TOKEN_SYMBOL = 'HYPE'
 // Hyperliquid reserves spot token index 0 for USDC.
 const HL_COLLATERAL_ASSET_ID = '0'
 
+/**
+ * Direction relative to the account's spot balance, the same frame as an
+ * outbound `vaultDeposit`.
+ */
+const BORROW_LEND_DIRECTION: Record<HlBorrowLendOperation, 'IN' | 'OUT'> = {
+  supply: 'OUT',
+  withdraw: 'IN',
+  borrow: 'IN',
+  repay: 'OUT',
+}
+
 /**
  * A ledger row moves a spot asset — a perp contract cannot be sent, received
  * or withdrawn — so the delta's token symbol resolves inside the spot asset
@@ -69,6 +84,7 @@ const resolveLedgerAsset = (symbol: string, registry: AssetRegistry): Asset => {
 
 /**
  * Map supported ledger entries; exclude same-account moves and unsupported types.
+ * Staking and borrow-lend moves map with the queried account as counterparty.
  * Missing assets throw; unresolved liquidation markets omit only those positions.
  * @public
  */
@@ -143,6 +159,46 @@ export const mapLedgerEntry = (
     } satisfies TransferActivity
   }
 
+  if (isCStakingTransferDelta(delta) || isBorrowLendDelta(delta)) {
+    // A completed unstake is a system event with the zero hash and no venue
+    // transaction, so the id is synthesized and no explorer link applies.
+    const hasTransaction = entry.hash !== zeroHash
+    const direction = isCStakingTransferDelta(delta)
+      ? delta.isDeposit
+        ? 'OUT'
+        : 'IN'
+      : BORROW_LEND_DIRECTION[delta.operation]
+    const action = isCStakingTransferDelta(delta) ? direction : delta.operation
+    return {
+      ...base,
+      ...(hasTransaction
+        ? {}
+        : {
+            id: `${delta.type}:${delta.token}:${action}:${delta.amount}:${base.timestamp}`,
+          }),
+      type: ActivityType.TRANSFER,
+      direction,
+      counterpartyAddress: queriedAddress.toLowerCase(),
+      asset: resolveLedgerAsset(delta.token, assetRegistry),
+      amount: delta.amount,
+      meta: isCStakingTransferDelta(delta)
+        ? { transferType: delta.type }
+        : {
+            transferType: delta.type,
+            operation: delta.operation,
+            interestAmount: delta.interestAmount,
+          },
+      ...(hasTransaction
+        ? {
+            explorerLink: explorerTxUrl(
+              ExplorerChainId.HYPERLIQUID,
+              entry.hash
+            ),
+          }
+        : {}),
+    } satisfies TransferActivity
+  }
+
   if (isVaultTransferDelta(delta)) {
     const queried = queriedAddress.toLowerCase()
     const vault = delta.vault.toLowerCase()

package/src/utils/withdrawableBalances.ts

@@ -17,7 +17,8 @@ import { toWireBig } from './decimal.js'
  *
  * @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.
+ *   quote-asset row. Hyperliquid deducts it from the requested amount. Absent
+ *   leaves every row without a fee.
  * @public
  */
 export const hyperliquidWithdrawableBalances = (
@@ -32,8 +33,12 @@ export const hyperliquidWithdrawableBalances = (
     withdrawalFee === undefined
       ? undefined
       : toWireBig(withdrawalFee, 'providers.withdrawalFeeUsd').toFixed()
-  const feeFor = (assetId: string) =>
-    fee === undefined || assetId !== quoteAssetId ? {} : { withdrawalFee: fee }
+  const feeFor = (
+    assetId: string
+  ): Pick<ProviderWithdrawableBalance, 'withdrawalFee' | 'isFeeDeducted'> =>
+    fee === undefined || assetId !== quoteAssetId
+      ? {}
+      : { withdrawalFee: fee, isFeeDeducted: true }
 
   if (isUnifiedAbstraction(abstraction)) {
     for (const balance of spotState.balances) {