Prerequisites

Account setup required before trading on Hyperliquid

Before trading on Hyperliquid, users must complete the provider’s prepareAccountActions. The SDK provides methods to discover, build, sign, and submit these.

The flow:

1. Check — checkPrerequisites() returns what’s needed and whether the account is ready
2. Sign — User signs any userPrerequisites with their wallet
3. Execute — executePrerequisites() submits user-signed + auto-signs agent prerequisites

// Check what's needed
const required = await perps.checkPrerequisites({
  provider: 'hyperliquid',
  address: userAddress,
});

if (!required.isReady) {
  // Sign user prerequisites with wallet
  const signedActions = await Promise.all(
    required.userPrerequisites.map(async (a) => ({
      action: a.action,
      typedData: a.typedData,
      signature: await walletClient.signTypedData({ ...a.typedData }),
    }))
  );

  // Execute all prerequisites (user + agent)
  await perps.executePrerequisites({
    provider: 'hyperliquid',
    address: userAddress,
    required,
    userSignedActions: signedActions,
  });
}

Parameters for checkPrerequisites:

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address

Returns: PrerequisitesResult

Field	Type	Description
userPrerequisites	ActionStep[]	Actions requiring user wallet signature
agentPrerequisites	ActionStep[]	Actions the SDK auto-signs with the agent
isReady	boolean	Whether all prerequisites are satisfied

Parameters for executePrerequisites:

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address
required	PrerequisitesResult	Yes	Result from checkPrerequisites()
userSignedActions	SignedActionStep[]	Yes	User-signed actions

Returns: ExecutePrerequisitesResult

Field	Type	Description
userResults	ExecuteActionResponse	Results from user-signed submissions
agentResults	ExecuteActionResponse	Results from agent-signed submissions (if any)

prepareAccountActions

The following actions are returned in the prepareAccountActions array from GET /providers for Hyperliquid. The SDK executes them automatically during the prerequisites flow.

approveAgent

Authorizes an agent wallet to sign trading operations on the user’s behalf. This is the core enabler of USER_AGENT mode — once approved, the SDK-managed agent can place, cancel, and modify orders without wallet popups.

Signers	USER
Params	ApproveAgentParams — { agentAddress, agentTtlMs? }
When needed	First time using USER_AGENT mode, or when agent approval has expired

approveBuilderFee

Approves the LI.FI builder fee on the user’s Hyperliquid account. Hyperliquid requires explicit builder fee approval before orders can be routed through third-party builders like LI.FI.

Signers	USER
Params	{} (empty — the backend determines the builder address and fee rate)
When needed	First time trading through LI.FI on this Hyperliquid account

userSetAbstraction

Enables or upgrades the user’s account abstraction mode (e.g., to unifiedAccount). This user-signed action sets the abstraction level on the main account, unifying spot and perps balances across sub-exchanges that share the same quote asset.

Signers	USER
Params	SetAbstractionParams — { abstraction? }
When needed	Account is in standard or dexAbstraction mode and needs upgrading

agentSetAbstraction

Sets the account abstraction mode using the agent’s signature. This is the agent-side counterpart to userSetAbstraction — both are needed to complete the abstraction upgrade. The SDK auto-signs this during executePrerequisites().

Signers	AGENT
Params	SetAbstractionParams — { abstraction? }
When needed	Paired with userSetAbstraction during the prerequisites flow

Low-Level API

Using the low-level API directly:

import { createAction, executeAction } from '@lifi/perps-sdk';

// Build prerequisite payloads
const { actions } = await createAction(client, {
  provider: 'hyperliquid',
  address: userAddress,
  action: 'approveAgent',
  params: { agentAddress: '0x...' },
});

// Sign and execute
const signedActions = actions.map(a => ({
  ...a,
  signature: await walletClient.signTypedData({ ...a.typedData }),
}));

await executeAction(client, {
  provider: 'hyperliquid',
  address: userAddress,
  action: 'approveAgent',
  actions: signedActions,
});