This page covers Hyperliquid-specific behavior that goes beyond the generic SDK documentation. For general concepts, see the Concepts section.
Deposits
Deposits to Hyperliquid are made using the LI.FI swap and bridge functionality. USDC Spot and USDC Perps are available as Hyperliquid L1 protocol targets in LI.FI — deposits are routed directly to Hyperliquid Core, they do not need to go through Arbitrum.
If the user already has USDC on Arbitrum, they can deposit directly via the Hyperliquid bridge with a normal transfer.
Funds can be deposited to either destination:
| Deposit Destination | Description |
|---|
| USDC Spot | Lands in the user’s Hyperliquid spot balance |
| USDC Perps | Lands directly in the user’s perps margin balance |
Under unifiedAccount abstraction mode (which the LI.FI Perps API automatically enables), both spot and perps USDC balances are available for perps trading across the default ('') and HIP-3 ('xyz') sub-dexes. It does not matter which destination you deposit to — both are usable as margin.
Withdrawals
Withdrawals are submitted via a user-signed EIP-712 payload using the SDK withdrawal flow. Agents cannot initiate withdrawals — the user’s wallet must sign directly regardless of signing mode.
On Hyperliquid, withdrawals always send USDC to the user’s address on Arbitrum via the Hyperliquid L1 → Arbitrum bridge. Processing typically takes 3–4 minutes.
Under unifiedAccount abstraction mode, withdrawals are drawn from the user’s spot USDC balance. Ensure sufficient spot USDC is available before initiating a withdrawal — perps margin must be freed (by closing positions or reducing margin) and transferred to spot first if needed.
Signing Model
Phantom Agent Signing
Hyperliquid requires all order operations (place, cancel, trigger) to use an agent-based signing scheme at the protocol level. Even when the user signs directly, a temporary “phantom” agent is created per operation. This is a Hyperliquid protocol requirement, not an SDK limitation.
USER Mode
In USER mode, every trading operation requires the user’s wallet to sign a phantom agent approval. In a browser context this means a wallet popup for each action; with an ethers/viem signer it means a direct signature per action. This makes USER mode functional but impractical for active trading on Hyperliquid.
await perps.setSigningMode(userAddress, 'hyperliquid', 'USER');
// Every placeOrder, cancelOrder, and TP/SL requires a user signature
USER_AGENT Mode (Recommended)
USER_AGENT mode is strongly recommended for Hyperliquid. It requires a one-time agent approval, after which all trading operations are signed seamlessly by the SDK.
await perps.setSigningMode(userAddress, 'hyperliquid', 'USER_AGENT');
// One-time agent approval, then no more user signatures for trading
localStorage, scoped per user + DEX pair. Approved agents are visible in the account’s config.agents array (see Account Configuration below).
UX Comparison
| Operation | USER mode | USER_AGENT mode |
|---|
| First-time setup | None | One-time agent approval |
| Place order | User signature (phantom agent) | Signed by SDK |
| Cancel order | User signature (phantom agent) | Signed by SDK |
| TP/SL | User signature per trigger | Signed by SDK |
| Withdrawal | User signature (always) | User signature (always) |
Account Abstraction
Account Types
Hyperliquid supports multiple account types that determine how margin and balances are managed:
| Account Type | Description |
|---|
standard | Isolated quote assets per DEX operator. Each HIP-3 DEX maintains a separate balance. |
dexAbstraction | Like-for-like quote assets are unified across HIP-3 DEXes. For example, the default DEX ('') and a HIP-3 DEX ('xyz') both use USDC, so a single USDC perps balance covers both. |
unifiedAccount | Spot and perps balances are further unified per quote asset across like-asset HIP-3 DEXes. Spot USDC can be used for perps on both '' and 'xyz'. Same applies to other quote assets like USDH or USDN. |
portfolioMargin | Portfolio margin with cross-asset margining. |
Backend Behavior
The LI.FI Perps API automatically upgrades accounts from standard or dexAbstraction to unifiedAccount during authorization. portfolioMargin accounts are left as-is.
Account Configuration
The config object returned by getAccount() contains Hyperliquid-specific account state:
const account = await getAccount(client, {
dex: 'hyperliquid',
address: userAddress,
});
console.log(account.config);
// {
// abstractionStatus: "unifiedAccount",
// agents: [...],
// builderFeeApproval: {
// builderAddress: "0x...",
// maxFeeRate: "0.001",
// approved: true,
// },
// }
| Config Key | Fields | Description |
|---|
abstractionStatus | string | Current abstraction mode (unifiedAccount, portfolioMargin, dexAbstraction, or null) |
agents | array | Approved extra agents for this account |
builderFeeApproval | builderAddress, maxFeeRate, approved | Builder fee approval status (required for placing orders via LI.FI) |
The SDK validates all config requirements automatically. These fields are useful for displaying account status in your UI.
WebSocket Protocol
Hyperliquid exposes a native WebSocket endpoint at wss://api.hyperliquid.xyz/ws. The SDK discovers this URL from the wsUrl field in the GET /dexes response. If you’re using the SDK, see Streaming instead.
For the full WebSocket protocol specification (message format, keepalive, and subscription channels), see the Hyperliquid WebSocket documentation.
SDK Channel Mapping
The SDK maps between normalized channel names and Hyperliquid-native channels:
| SDK channel | HL subscription type | SDK event type |
|---|
prices | allMids | PricesResponse |
orderbook | l2Book | OrderbookResponse |
trades | trades | HistoryItem[] |
candle | candle | Candle |
orderUpdates | orderUpdates | Order[] |
fills | userFills | HistoryItem[] |
positions | webData2 | Position[] |
Rate Limits
Hyperliquid enforces per-connection limits:
- 1000 total subscriptions per WebSocket connection
- 10 user-specific subscriptions per connection (orderUpdates, userFills, webData2)
Additional Notes
- Currently, only the default Hyperliquid venue and HIP-3 perps venues that use USDC as the quote asset are supported (e.g.
'', 'xyz').
- Only isolated margin is available for now.
Related Pages