Setup

Account setup required before trading on Hyperliquid

Before trading on Hyperliquid, users must complete the provider’s setup descriptors. The SDK provides methods to discover, build, sign, and submit these. Post-setup tuning is exposed via the provider’s options descriptors (e.g. accountMode) — these never gate trading.

The flow:

1. Check — checkSetup() returns the outstanding setup steps and whether the account is ready
2. Run each step — executeProviderSetupAction() signs and submits one step end-to-end, routing it to the correct signer by shape

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

if (!required.isReady) {
  // Sign and submit each outstanding step, in descriptor order
  for (const step of required.setup) {
    await perps.executeProviderSetupAction({
      provider: 'hyperliquid',
      address: userAddress,
      step,
    });
  }
}

Parameters for checkSetup:

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

Returns: ProviderSetup

Field	Type	Description
accountExists	boolean	Whether the address already has account state with the provider
setup	ActionStep[]	Outstanding setup steps, ordered by descriptor sequence
isReady	boolean	Whether all setup items are already satisfied

Parameters for executeProviderSetupAction:

Field	Type	Required	Description
provider	string	Yes	Provider identifier
address	string	Yes	User’s wallet address
step	ActionStep	Yes	A single step from checkSetup().setup

Returns: Promise<void> — resolves on success, throws PerpsError on venue rejection.

Setup descriptors

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

approveAgent

Authorizes an agent wallet to sign trading operations on the user’s behalf. This is the one-time wallet signature that enables agent-based trading — 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 provisioning an agent on this account, or when an existing agent approval has expired

setReferrer

Applies the LI.FI referral code to the account, enabling 4% off fees for the account’s first $25M of trading volume. The step is signed by the SDK-managed agent rather than the user’s wallet, so it is sequenced after approveAgent.

Signers	SDK
Params	{} (empty — the backend determines the referral code)
When needed	While the account has no referrer attached; skipped once one is set

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

Options descriptors

The following options actions are returned in the options array from GET /providers for Hyperliquid. These never gate trading — they are post-setup tuning controls rendered behind a cog icon in the widget. The accepted parameter values are enumerated on each descriptor’s params[].values array.

accountMode

Switches the account’s operating mode between supported Hyperliquid abstraction variants. Every transition is USER-signed: the agent-side operation can only initialize a never-set mode and cannot safely change an existing account.

Signers	USER
Params	AccountModeParams — { mode: string }
When needed	Switching abstraction mode (e.g. upgrading a new account to unifiedAccount)

Mode values: unifiedAccount (default), disabled (standard/manual mode), and portfolioMargin. The deprecated dexAbstraction value is no longer advertised; existing accounts using it remain readable.

For a full explanation of what each mode means — balance unification behaviour, capital efficiency, and signing requirements — see Account Abstraction.

Low-Level API

Using the low-level API directly:

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

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

// Sign and execute — APPROVE_AGENT is EIP-712, so each step carries `typedData`
const signedActions = await Promise.all(
  actions.map(async (a) => ({
    action: a.action,
    typedData: a.typedData,
    signature: await walletClient.signTypedData({ ...a.typedData }),
  })),
);

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