Overview

Hyperliquid provider — signing model, account abstraction, and configuration

This section covers Hyperliquid-specific behavior that goes beyond the generic SDK documentation. For general concepts, see the Concepts section.

import { PerpsClient, PerpsWsClient } from '@lifi/perps-sdk';
import {
  hyperliquidProvider,
  hyperliquidWsProvider,
} from '@lifi/perps-sdk-provider-hyperliquid';

const perps = new PerpsClient({
  apiKey: 'your-api-key',
  providers: [hyperliquidProvider()],
});

const ws = new PerpsWsClient(perps.client, {
  wsProviders: { hyperliquid: hyperliquidWsProvider() },
});

hyperliquidProvider(options) accepts apiUrl (defaults to https://api.hyperliquid.xyz) and storage (a StorageAdapter for the agent keypair; defaults to encrypted browser localStorage — see Signing Model).

​

Topics

• Signing Model — User and agent signatures, phantom-agent signing, and the SDK-managed agent
• Deposits — Funding your Hyperliquid account via LI.FI or the Arbitrum bridge
• Setup — One-time account setup before trading, the account mode choice, and the revocable approvals
• Trading — All trading and revoke actions with parameters
• Withdrawals — Withdrawing USDC to Arbitrum
• Account Abstraction — Account types, unified accounts, and configuration
• WebSocket Protocol — Native WebSocket protocol, channel mapping, and rate limits

​

Defaults & assumptions

• Margin mode: marginMode has no default. When it is omitted on updateLeverage, or on placeOrder together with leverage, Hyperliquid receives isolated. Always pass marginMode explicitly (CROSS or ISOLATED). On placeOrder without leverage, the asset’s existing margin mode applies. For markets where cross margin is unavailable, check onlyIsolated on PerpsMarket before presenting a margin mode toggle in your UI.
• Trade signing: trading actions are signed by the SDK-managed agent — no per-trade wallet popup.
• Order fields: type and price are required on every placeOrder, including market orders and spot orders.
• Withdrawals & sendAsset: signed by the user’s L1 wallet every time; agents cannot move funds.

​

Account boundary

A Hyperliquid account exists only after its first deposit. accountExists returns false before then. Account-scoped HTTP reads — getAccount, getWithdrawableBalances, getAvailableToTrade, getMarketSettings, getPositions, getOrders, getOrder, getFills, getActivity, and getPortfolioHistory — throw AccountNotFound for that wallet. The orderUpdates, fills, positions, spotBalances, accountSummary, and availableToTrade WebSocket subscriptions reject with the same error before opening a venue channel.

Public market reads and the deposit flow remain available before account creation. Existing accounts receive the normal empty collections when they have no positions, orders, fills, or activity. getOrder still throws OrderNotFound for an unknown order ID.

​

Account figures

PerpsClient.getAccountSummary() builds the AccountSummary totals for Hyperliquid from these venue fields:

AccountSummary field	Venue source
portfolioValue	Sum of every priced balance in account.balances and account.collateralBalances
availableMargin	marginSummary.accountValue minus marginSummary.totalMarginUsed, summed across dexStates. Under unifiedAccount or portfolioMargin, the venue’s tokenToAvailableAfterMaintenance quote-asset entry replaces this figure.
marginUsed	marginSummary.totalMarginUsed, summed across dexStates
unrealizedPnl	Sum of unrealizedPnl across open positions

Under unifiedAccount and portfolioMargin, the venue reports all balances and holds in the spot clearinghouse state — see Account Abstraction.

getAvailableToTrade() reads the venue’s activeAssetData.availableToTrade for the requested market and returns its buy and sell amounts directly.

getWithdrawableBalances() reads the venue’s withdrawable figure for the perps category. Under unifiedAccount and portfolioMargin, it also reads each spot token’s total minus hold for the spot category. See Withdrawals for the full per-category breakdown.

​

Candle intervals

The provider supports these OHLCV intervals: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, 1M.

​

Notes

• Multiple quote assets are supported across HIP-3 venues (USDC, USDH, USDE, USDT0). See Trading / categories for the current list.

​

Related Pages

• Concepts — The action pattern, streaming, and multi-provider support
• SDK / Streaming — Subscribe to live market data and user events via WebSocket
• SDK / Account — Fetch account balances, positions, and fills
• SDK / Trading — Place orders, cancel orders, and query order status
• SDK / Actions — The create -> authorize -> execute pattern for all operations
• LI.FI Docs — Cross-chain swap and bridge for deposits