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

# Register on Hyperliquid

> Register a VOOI-managed agent wallet to trade on Hyperliquid through the VOOI API

Registration authorizes a VOOI-managed agent wallet to trade on Hyperliquid on your behalf. Your funds remain in your own Hyperliquid account. The agent is only allowed to submit orders.

<Info>
  This guide assumes that you already have an active VOOI API token. See [API Tokens](/docs/tokens) for how to obtain one.
</Info>

## Do you need to register?

Start by checking whether your VOOI account already has Hyperliquid credentials via [`GET /user-exchange`](/docs/api-reference/user-exchange/get-connected-exchanges):

<CodeGroup>
  ```bash Request theme={null}
  GET https://perps-api.vooi.io/user-exchange
  Authorization: Bearer <token>
  ```

  ```bash curl theme={null}
  curl https://perps-api.vooi.io/user-exchange \
    -H "Authorization: Bearer <token>"
  ```
</CodeGroup>

The response is an array of `{ exchange, valid }` objects, one per connected exchange.

* **An entry whose `exchange` is `hyperliquid` is present** (with its `valid` flag set to `true`) — your account is already connected. No action needed.
* **No entry whose `exchange` is `hyperliquid` is present** — check your deposit status on Hyperliquid via [`GET /user-exchange/{exchange}/register/status`](/docs/api-reference/user-exchange/check-registration-status):

<CodeGroup>
  ```bash Request theme={null}
  GET https://perps-api.vooi.io/user-exchange/hyperliquid/register/status?address=0xYourWalletAddress
  ```

  ```bash curl theme={null}
  curl "https://perps-api.vooi.io/user-exchange/hyperliquid/register/status?address=0xYourWalletAddress"
  ```
</CodeGroup>

* **`isRegistered: true`** — your wallet has funds on Hyperliquid and is eligible to register. Follow the steps below, or, if you already created an API wallet on Hyperliquid yourself, paste those credentials via [`POST /user-exchange/hyperliquid`](/docs/api-reference/user-exchange/connect-hyperliquid) (see [Use your own keys](/docs/exchanges)).
* **`isRegistered: false`** — your wallet has no deposit on Hyperliquid yet. Deposit first (step 1 below) and the flag will flip once Hyperliquid reflects the balance.

<Note>
  `isRegistered` reports "is this wallet known to Hyperliquid" — in practice, "has it ever deposited". It does **not** mean the wallet has an active VOOI-managed agent. A wallet that deposited directly through the Hyperliquid UI (not through [`GET /deposit`](/docs/api-reference/deposit/get-deposit-transactions-for-signing)) also flips the flag to `true` — the check reads Hyperliquid's own state, not VOOI's.
</Note>

## Prerequisites

* An EVM wallet
* An active VOOI API token
* USDC deposited to Hyperliquid from your wallet address

## 1. Deposit USDC to Hyperliquid

Your wallet address must have a balance on Hyperliquid before you can register a VOOI-managed agent wallet.

You can deposit through the Hyperliquid UI or use [`GET /deposit`](/docs/api-reference/deposit/get-deposit-transactions-for-signing) to receive ready-to-sign calldata.

### Using the deposit endpoint

<CodeGroup>
  ```bash Request theme={null}
  GET https://perps-api.vooi.io/deposit?exchange=hyperliquid&chainId=42161&amount=5&address=0xYourWalletAddress
  Authorization: Bearer <token>
  ```

  ```bash curl theme={null}
  curl "https://perps-api.vooi.io/deposit?exchange=hyperliquid&chainId=42161&amount=5&address=0xYourWalletAddress" \
    -H "Authorization: Bearer <token>"
  ```
</CodeGroup>

The response contains one or more transactions to sign and submit on Arbitrum One. Example:

```json theme={null}
{
  "transactions": [
    {
      "calldata": {
        "chainId": 42161,
        "data": "0xa9059cbb...",
        "to": "0xFd086bC7..."
      },
      "meta": { "amount": "5.0", "type": "transfer" }
    }
  ]
}
```

Sign and submit each transaction in the provided order using an EVM wallet such as MetaMask. If there are multiple transactions (e.g. an `approve` followed by a `transfer`), submit them one at a time and wait for each to confirm before sending the next.

Hyperliquid's Arbitrum bridge requires a minimum deposit of 5 USDC. Hyperliquid usually processes deposits within 1 to 3 minutes.

## 2. Prepare registration

Call [`POST /user-exchange/{exchange}/register/prepare`](/docs/api-reference/user-exchange/prepare-exchange-registration) with your wallet address to generate the registration data.

The optional `referralCode` field binds a referral code to the new account at registration. Omit it and the VOOI code is applied; it cannot be changed afterwards. See [Points & rewards](/docs/points#referral-code).

The endpoint creates a new agent wallet for the user and returns the following:

* a short-lived `registrationToken`
* an EIP-712 typed data object to sign

<CodeGroup>
  ```bash Request theme={null}
  POST https://perps-api.vooi.io/user-exchange/hyperliquid/register/prepare
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "address": "0xYourWalletAddress"
  }
  ```

  ```bash curl theme={null}
  curl -X POST https://perps-api.vooi.io/user-exchange/hyperliquid/register/prepare \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{"address": "0xYourWalletAddress"}'
  ```
</CodeGroup>

Response shape:

```json theme={null}
{
  "exchange": "hyperliquid",
  "registrationToken": "<opaque-token>",
  "signData": { /* EIP-712 typed data — see the API reference for the full schema */ }
}
```

`signData` has `domain`, `message`, `primaryType`, and `types` — pass it through to an EIP-712 signer (see step 3). The domain `chainId` is `42161` (Arbitrum One); the `message.nonce` is a millisecond timestamp.

The `registrationToken` expires in 10 minutes. If it expires before you complete registration, call this endpoint again to get a new token.

**Possible errors:**

| Status | Message | Cause |
| - | - | - |
| `409 Conflict` | `No deposits found for 0x.... Please deposit funds before registering.` | Your wallet has no balance on Hyperliquid. Complete step 1 first. |

## 3. Sign the ApproveAgent message

Sign the returned `signData` object using EIP-712 typed data signing.

`message.nonce` is a `uint64`. Some EIP-712 libraries require a large-integer type for `uint64` fields — the viem snippet below converts numbers to `BigInt` for that reason.

The `message.agentName` you sign is `VOOI_ULTRA` — the name shown for the authorized agent in your Hyperliquid account's API-agents list.

```typescript theme={null}
import { type Hex } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';

async function signApproveAgent(walletPrivateKey: Hex, signData: PrepareResponse['signData']): Promise<Hex> {
  const account = privateKeyToAccount(walletPrivateKey);

  // uint64 fields must be BigInt for EIP-712 signing
  const message = Object.fromEntries(
    Object.entries(signData.message).map(([key, value]) => [
      key,
      typeof value === 'number' ? BigInt(value) : value,
    ]),
  );

  return account.signTypedData({
    domain: {
      chainId: signData.domain.chainId,
      name: signData.domain.name,
      verifyingContract: signData.domain.verifyingContract as Hex,
      version: signData.domain.version,
    },
    message,
    primaryType: signData.primaryType,
    types: signData.types,
  });
}
```

This step returns a signature that will be used in the next request to complete registration.

## 4. Execute registration

Submit your wallet address, the `registrationToken`, and the signature (wrapped in a single-element `signatures` array) to [`POST /user-exchange/{exchange}/register/execute`](/docs/api-reference/user-exchange/execute-exchange-registration).

VOOI submits the signed `ApproveAgent` action to Hyperliquid on your behalf — you do **not** broadcast it yourself. The only on-chain transaction you sign is the USDC deposit in step 1.

<CodeGroup>
  ```bash Request theme={null}
  POST https://perps-api.vooi.io/user-exchange/hyperliquid/register/execute
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "address": "0xYourWalletAddress",
    "registrationToken": "<opaque-token>",
    "signatures": ["0x..."]
  }
  ```

  ```bash curl theme={null}
  curl -X POST https://perps-api.vooi.io/user-exchange/hyperliquid/register/execute \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{"address": "0xYourWalletAddress", "registrationToken": "<opaque-token>", "signatures": ["0x..."]}'
  ```
</CodeGroup>

Response on success:

```json theme={null}
{ "exchange": "hyperliquid", "valid": true }
```

**Possible errors:**

| Status | Message | Cause |
| - | - | - |
| `400 Bad Request` | `Registration token has expired` | The token from step 2 expired. Call the prepare endpoint again to get a new one. |
| `400 Bad Request` | `Agent approval failed: ...` | Hyperliquid rejected the signature. Ensure you signed the exact `signData` returned in step 2. |

Your wallet is now connected to Hyperliquid through VOOI. You can use the VOOI API to place orders, manage positions, and query account data on Hyperliquid.

## Next steps

<CardGroup cols={2}>
  <Card title="Start trading on Hyperliquid" icon="bolt" href="/docs/trading-orders">
    Place your first order
  </Card>

  <Card title="Connect your wallet to Lighter" icon="plug" href="/docs/register-lighter">
    Register on Lighter
  </Card>

  <Card title="Register on Extended" icon="plug" href="/docs/register-extended">
    Add another venue to your VOOI account
  </Card>

  <Card title="Earn Kinetiq kPoints" icon="award" href="/docs/points">
    Enable kPoints with your connected Hyperliquid wallet
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.