Hyperliquid Setup Guide

Enables your agent to place and cancel orders, check positions, read orderbooks, and transfer funds on Hyperliquid perpetual futures.

Overview

Hyperliquid is a decentralized perpetual futures exchange with its own L1 chain. Authentication is done via EIP-712 message signing with an Ethereum wallet private key — there are no traditional API keys. Every order is cryptographically signed by the wallet, and the enclave handles this signing inside the Confidential VM.

Prerequisites

• An Ethereum wallet with a private key
• USDC deposited on Hyperliquid (bridged from Arbitrum)
• A dedicated wallet is strongly recommended — do not use your main wallet's private key

Step 1: Create a Dedicated Trading Wallet

Using a dedicated wallet limits exposure if anything goes wrong.

1. Create a new wallet in MetaMask (or any Ethereum wallet):
   • MetaMask: Click account icon > Create Account
   • Export the private key: Account Details > Show Private Key
2. Or use any method to generate a standard Ethereum keypair
3. Save the private key securely — 64 hex characters (with or without 0x prefix)

Step 2: Fund the Wallet on Hyperliquid

1. Go to app.hyperliquid.xyz
2. Connect with the wallet you created in Step 1
3. Click Deposit — this bridges USDC from Arbitrum to Hyperliquid
4. You'll need USDC on Arbitrum first. If you don't have any, bridge from Ethereum mainnet to Arbitrum via the Arbitrum Bridge
5. Confirm the deposit and wait for the bridge transaction to complete

Step 3: (Optional) Set Up a Vault for Sub-Account Trading

Vaults are Hyperliquid's sub-account mechanism. If you want the agent to trade from a vault rather than the main wallet:

1. In the Hyperliquid UI, go to Vaults
2. Create a new vault
3. Copy the vault's contract address
4. The wallet from Step 1 must be the vault's manager (the wallet that created it)

Step 4: Connect in Carapace

1. Go to Dashboard > Connections
2. Find Hyperliquid and click Connect
3. Fill in:
   • Private Key — the 64 hex character private key from Step 1
   • Vault Address — (optional) the vault contract address from Step 3
4. Click Save Credentials

Credential Fields Reference

Gotchas

Use a dedicated wallet: The private key provided to Carapace has full signing authority over the wallet. Use a wallet dedicated to agent trading with only the funds you're willing to risk. Never use your primary wallet.

Vault address vs wallet address: The vault_address is the vault's contract address, not the controller wallet's address. The controller wallet (whose private_key you provide) must be the vault manager.

Funds are on Hyperliquid L1, not Arbitrum: After depositing, your USDC lives on Hyperliquid's chain. The Arbitrum balance and Hyperliquid balance are separate. If position checks show zero balance, verify the deposit completed.

API wallet concept: Hyperliquid supports creating "API wallets" — limited-permission wallets that can trade but not withdraw. For additional security, consider generating an API wallet in the Hyperliquid UI and using that private key instead of the main wallet's key.

EIP-712 signing is local: All order signing happens inside the Carapace enclave. The private key never leaves the Confidential VM's memory and is never transmitted over the network.

Troubleshooting

"Insufficient margin" errors

Your Hyperliquid account doesn't have enough deposited USDC. Deposit more via the Hyperliquid UI, or reduce your order size.

Orders not executing

Hyperliquid uses a central limit order book. Limit orders only execute when the market price crosses your order price. Use market orders for immediate execution.

"Invalid signature" errors

Verify the private key is exactly 64 hex characters and corresponds to the wallet address that has funds on Hyperliquid. A mismatched key will produce valid EIP-712 signatures for the wrong address.

See Also

• Hyperliquid documentation
• Hyperliquid app
• Arbitrum Bridge