Account Abstraction

Account types, unified accounts, and account configuration on Hyperliquid

Account Types

Hyperliquid supports multiple account types that determine how margin and balances are managed. The wire-level values reported by the userAbstraction info endpoint and exposed via account.config.abstractionMode are the camelCase strings below; the SDK exports them as the HlAbstractionMode constant from @lifi/perps-sdk-provider-hyperliquid (keys: DISABLED, UNIFIED_ACCOUNT, PORTFOLIO_MARGIN, DEX_ABSTRACTION).

Wire value	HlAbstractionMode key	Description	Action limit
disabled	DISABLED	Manual / Standard mode (recommended for market makers, high-volume automated users, and deployers/builders). Spot and perps balances are separate, and each DEX maintains its own balance. Cross margin applies to each DEX separately.	None
unifiedAccount	UNIFIED_ACCOUNT	Recommended for most users. A single balance per asset collateralizes all cross-margin positions in that asset and is unified with the spot balance in that asset. For example, USDC is the single source for validator-operated perps, HIP-3 (xyz) perps, and USDC-quoted spot.	50,000 / day
portfolioMargin	PORTFOLIO_MARGIN	Most capital efficient. A single portfolio unifying all eligible assets (currently HYPE, BTC, USDC, USDT) with cross-asset margining.	50,000 / day
dexAbstraction	DEX_ABSTRACTION	⚠️ To be discontinued — Hyperliquid recommends interfaces deprecate support going forward; the SDK does not expose it. USDC balances default to the perps balance, all other collateral defaults to spot. Cross margin on HIP-3 DEXs does not behave intuitively in this mode.	None

unifiedAccount and portfolioMargin are subject to a protocol-level cap of 50,000 user actions per day. This includes orders, cancellations, and modifications. disabled (Standard) mode has no such limit. High-frequency and automated strategies should use disabled mode.

Builder fees: builder-code addresses must be in disabled (Standard) mode to accrue builder fees. API consumers: in unifiedAccount and portfolioMargin, all balances and holds are reported in the spot clearinghouse state — individual perp-DEX user states are not meaningful.

Backend Behavior

The SDK orchestrates an upgrade from disabled or dexAbstraction to unifiedAccount during the setup flow (via the accountMode action). portfolioMargin accounts are left as-is.

This ensures all SDK users get the latest Hyperliquid account features (unified USDC balance). The upgrade is a one-way operation — it cannot be reverted.

Account Configuration

The config object returned by getAccount() is a discriminated union over provider. For provider: 'hyperliquid' it carries the following Hyperliquid-specific state:

const account = await getAccount(client, {
  provider: 'hyperliquid',
  address: userAddress,
});

if (account.config.provider === 'hyperliquid') {
  console.log(account.config);
  // {
  //   provider: "hyperliquid",
  //   abstractionMode: "unifiedAccount", // or null when never set
  //   agents: [...],
  //   builderFeeApproval: {
  //     builderAddress: "0x...",
  //     maxFeeRate: "0.001",
  //     approved: true,
  //   },
  // }
}

Field	Type	Description
provider	"hyperliquid"	Discriminator
abstractionMode	string | null	Current abstraction mode: disabled, unifiedAccount, portfolioMargin, or dexAbstraction. null when abstraction has never been set.
agents	HyperliquidAgent[]	Approved extra agents for this account
builderFeeApproval	HyperliquidBuilderFeeApproval?	Builder fee approval status (required for placing orders via LI.FI). Absent when no builder is configured.

The SDK validates all config requirements automatically. These fields are useful for displaying account status in your UI.