Setup

Account setup required before trading on Hyperliquid

Before trading on Hyperliquid, users must complete the provider’s setup steps. The SDK provides methods to discover, build, sign, and submit them. Every user choice, such as the account mode, is also a setup step. It carries its own options.

An unfunded account reports accountExists: false with no setup steps. Deposit first (the first deposit pays Hyperliquid’s one-time account creation fee), then run checkSetup().

The flow:

1. Check — checkSetup() returns the outstanding setup steps, the checklist, and whether the account is ready
2. Run each step — executeProviderSetupAction() signs and submits one staged step end-to-end
3. Apply each choice — executeProviderOption() executes the option the user picked for a choice step

const provider = 'hyperliquid';
let required = await perps.checkSetup({ provider, address: userAddress });

// An unfunded account has no setup steps yet: deposit first, then call checkSetup() again.
while (required.accountExists && !required.isReady) {
  // The checklist is in sequence order. Handle its first unsatisfied item.
  const item = required.checklist.find((entry) => !entry.satisfied);
  if (!item) break;

  const { options } = item.descriptor;
  if (options !== null) {
    // Show the options and let the user choose. This example takes the recommended one.
    const option = options.find((o) => o.default === true) ?? options[0];
    await perps.executeProviderOption({
      provider,
      address: userAddress,
      option,
    });
  } else {
    const step = required.setup.find((s) => s.action === item.descriptor.type);
    if (!step) break;
    await perps.executeProviderSetupAction({
      provider,
      address: userAddress,
      step,
      checklist: required.checklist,
    });
  }

  // The checklist is a snapshot. Read it again after each step.
  required = await perps.checkSetup({ provider, address: userAddress });
}

A choice step is never in required.setup. It appears on required.checklist with its current selected option, and it keeps isReady false until it is satisfied. A choice can also block the steps after it, because executeProviderSetupAction() refuses a step while a lower sequence step on the checklist is unsatisfied. The snippet therefore handles the checklist one item at a time. The SDK never applies a choice for the user: the snippet takes the recommended option only to keep the example short. See How checkSetup() treats each step and Account Mode.

If you call the API without the SDK, see Integrating without the SDK.

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. For Hyperliquid this is false until the first deposit, and setup is empty while it is false
setup	ActionStep[]	Outstanding staged steps, ordered by descriptor sequence. Only USER-signed non-choice steps are staged.
isReady	boolean	true only when nothing is staged and every choice on checklist is satisfied
checklist	SetupChecklistItem[]	The user-facing steps, each paired with its state: { descriptor: SetupAction; satisfied: boolean; selected: SetupOption | null; currentValue: string | null }. It lists every choice step and every USER-signed step. A not-yet-applicable conditional step (see revokeAgent below) is omitted rather than shown unsatisfied. See selectUserSetupActions for the account-free projection of the same filter.

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
checklist	SetupChecklistItem[]	Yes	The checklist from the same checkSetup() result. The SDK refuses a step while a lower sequence step on it is unsatisfied. The checklist does not change when a step runs, so call checkSetup() again after each step.

Returns: Promise<ExecuteActionResponse>. Read results[i].status: a refusal is a Failed result, not an exception. PerpsError covers a step that cannot be signed or submitted before any result is known.

​

Steps in sequence order

Sequence	Step	Type	signer	relay	revoke
5	revokeAgent (conditional)	Action	USER	API	none
10	approveAgent	Action	USER	API	revokeSessionAgent
12	accountMode	Choice	USER	API	none
15	setReferrer	Action	SDK	API	none
20	approveBuilderFee	Action	USER	API	revokeBuilderFee

Every step uses the eip712 signing method. relay: API means the signed step goes to POST /executeAction. Hyperliquid has no relay: CLIENT step.

​

Setup descriptors

​

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.

Signer	USER
Relay	API
Params	ApproveAgentParams — { agentAddress, agentTtlMs? }
Revoke	revokeSessionAgent — removes the session agent the SDK holds. It takes agentAddress, which the SDK fills from its stored agent.
Docs	Hyperliquid nonces and API wallets
When needed	First time provisioning an agent on this account, or when an existing agent approval has expired

​

revokeAgent (conditional)

Deregisters an existing agent to free one of the account’s agent slots. Hyperliquid performs this through the same approveAgent typed-data primitive with a matching name, so it carries no distinct primary type on the wire. Marked as a conditional setup step: checkSetup() stages it only when every named agent slot on the account is already taken, and omits it from checklist otherwise — it never renders as a satisfied step for an account with a free slot.

Signer	USER
Relay	API
Params	{} (empty). The backend picks the named agent to remove: LI.FI’s own leftover agent first, otherwise the agent that expires soonest. The user only confirms it with a signature.
When needed	Provisioning a new agent while the account already holds 3 named agents

​

accountMode

A choice of how Hyperliquid combines the spot and perps balances of the account. It is USER-signed: the agent-side operation can only initialize a never-set mode and cannot safely change an existing account, so every transition needs a user signature. The SDK never applies this step for the user.

Signer	USER
Relay	API
Sequence	12
Options	Manual ({ mode: 'disabled' }), Unified Account ({ mode: 'unifiedAccount' }), Portfolio Margin ({ mode: 'portfolioMargin' })
Revoke	none
Docs	Hyperliquid account abstraction modes

The Unified Account option carries default: true. This marks it as the recommended option for a UI. It is a hint only. Nothing is changed until the user picks an option and the client executes it with executeProviderOption(). An account that has never set a mode reads as Manual.

dexAbstraction is not supported. The provider does not advertise it. An existing account that uses it stays readable, and it has no matching option, so the step reads as unsatisfied for such an account.

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

​

setReferrer

Applies the LI.FI referral code to the account. The step is signed by the SDK-managed agent, not the user’s wallet, so it is sequenced after approveAgent, and checkSetup() applies it without a separate wallet prompt. Tell your users that a referral code is applied. The provider does not advertise it when no referral code is configured.

Signer	SDK
Relay	API
Params	{} (empty — the backend determines the referral code)
When needed	The account exists, has no referrer, and has not yet traded
Sequence	15

​

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.

Signer	USER
Relay	API
Params	{} (empty — the backend determines the builder address and fee rate)
Revoke	revokeBuilderFee
Docs	Hyperliquid builder codes
When needed	First time trading through LI.FI on this Hyperliquid account, and again when LI.FI’s fee configuration changes

Approves LI.FI’s Hyperliquid builder wallet at the configured maximum rate. If the venue confirms the account has no approval, placeOrder fails with a setup-required error.

The step is revocable. Its revoke points at revokeBuilderFee, an entry in actions with signer: USER and relay: API. It takes no params. It approves the builder fee again at a 0% maximum rate. After the revoke, the step is unsatisfied and checkSetup() stages it again.

import { ActionType } from '@lifi/perps-types';

const item = required.checklist.find(
  (entry) => entry.descriptor.type === ActionType.APPROVE_BUILDER_FEE,
);

if (item?.satisfied && item.descriptor.revoke !== null) {
  await perps.executeProviderRevoke({
    provider: 'hyperliquid',
    address: userAddress,
    step: item.descriptor,
  });
}

​

Low-Level API

Using the low-level API directly. agentAddress must be the address of an agent keypair stored by the provider (see Signing Model); the user’s wallet signs on chain 42161.

import {
  ActionType,
  createAction,
  executeAction,
  type Eip712ActionStep,
} from '@lifi/perps-sdk';
import type { Address } from 'viem';

declare const agentAddress: Address; // address of the stored agent keypair

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

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

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