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: DEFAULT, DISABLED, UNIFIED_ACCOUNT, PORTFOLIO_MARGIN, DEX_ABSTRACTION).

Wire value	HlAbstractionMode key	Description	Action limit
disabled, default	DISABLED, DEFAULT	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 API does not offer it as a new selection; it stays in HlAbstractionMode and is still readable on existing accounts. 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. default is a second wire spelling of Standard mode. 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

accountMode is a choice step in the provider’s setup array. It is USER-signed. The options are disabled (shown as Manual), unifiedAccount (recommended), and portfolioMargin. The user explicitly chooses and authorizes every transition, and the SDK never applies the step on its own. An account that never set a mode reports abstractionMode: null and behaves as Standard mode. The deprecated dexAbstraction value remains readable for existing accounts but is not offered as a selection.

Read the available values from the params.mode of each option on the accountMode step (Provider.setup[].options[]). Hyperliquid enforces transition rules at execution time; the SDK does not silently migrate the account during setup. See Setup for the step descriptor.

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 perps.getAccount({
  provider: 'hyperliquid',
  address: userAddress,
});

if (account.config.provider === 'hyperliquid') {
  console.log(account.config);
  // {
  //   provider: "hyperliquid",
  //   abstractionMode: "unifiedAccount", // or null when never set
  //   agents: [...],
  //   dexStates: [...],
  //   availableAfterMaintenance: "1234.56", // unified / portfolioMargin only
  // }
}

Field	Type	Description
provider	"hyperliquid"	Discriminator
abstractionMode	string | null	Current abstraction mode: default, disabled, unifiedAccount, portfolioMargin, or dexAbstraction. null when abstraction has never been set.
agents	HyperliquidAgent[]	The venue’s raw extraAgents rows for this account (Record<string, unknown>[])
dexStates	HyperliquidDexAccountState[]	One entry per perps sub-dex with a live market: dex ('' is the main dex), marginSummary, crossMarginSummary, crossMaintenanceMarginUsed, withdrawable
availableAfterMaintenance	string?	Venue buying power. Present only under unifiedAccount and portfolioMargin

HyperliquidAccountConfig also declares an optional builderFeeApproval; the SDK’s Hyperliquid getAccount() never populates it.

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