Register on Hyperliquid

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.

This guide assumes that you already have an active VOOI API token. See API Tokens for how to obtain one.

Do you need to register?

Start by checking whether your VOOI account already has Hyperliquid credentials via GET /user-exchange:

GET https://perps-api.vooi.io/user-exchange
Authorization: Bearer <token>

curl https://perps-api.vooi.io/user-exchange \
  -H "Authorization: Bearer <token>"

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:

GET https://perps-api.vooi.io/user-exchange/hyperliquid/register/status?address=0xYourWalletAddress

curl "https://perps-api.vooi.io/user-exchange/hyperliquid/register/status?address=0xYourWalletAddress"

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 (see Use your own keys).
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.

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) also flips the flag to true — the check reads Hyperliquid’s own state, not VOOI’s.

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 to receive ready-to-sign calldata.

Using the deposit endpoint

GET https://perps-api.vooi.io/deposit?exchange=hyperliquid&chainId=42161&amount=5&address=0xYourWalletAddress
Authorization: Bearer <token>

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

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

{
  "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 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. 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

POST https://perps-api.vooi.io/user-exchange/hyperliquid/register/prepare
Authorization: Bearer <token>
Content-Type: application/json

{
  "address": "0xYourWalletAddress"
}

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"}'

Response shape:

{
  "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.

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. 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.

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..."]
}

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..."]}'

Response on success:

{ "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.

Getting Started

Trading

Connect an Exchange

Points & rewards

Brokers

Do you need to register?

Prerequisites

1. Deposit USDC to Hyperliquid

Using the deposit endpoint

2. Prepare registration

3. Sign the ApproveAgent message

4. Execute registration

Next steps

Start trading on Hyperliquid

Connect your wallet to Lighter

Register on Extended

Earn Kinetiq kPoints

​Do you need to register?

​Prerequisites

​1. Deposit USDC to Hyperliquid

​Using the deposit endpoint

​2. Prepare registration

​3. Sign the ApproveAgent message

​4. Execute registration

​Next steps

Start trading on Hyperliquid

Connect your wallet to Lighter

Register on Extended

Earn Kinetiq kPoints

Do you need to register?

Prerequisites

1. Deposit USDC to Hyperliquid

Using the deposit endpoint

2. Prepare registration

3. Sign the ApproveAgent message

4. Execute registration

Next steps