> ## Documentation Index
> Fetch the complete documentation index at: https://public-perps-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={null}
// 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](/providers/hyperliquid/account-abstraction).

## Low-Level API

Using the low-level API directly:

```typescript theme={null}
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,
});
```