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 { createPerpsClient, PerpsWsClient } from '@lifi/perps-sdk';
import {
  hyperliquidProvider,
  hyperliquidWsProvider,
} from '@lifi/perps-sdk-provider-hyperliquid';

const sdk = createPerpsClient({
  apiKey: 'your-api-key',
  providers: [hyperliquidProvider()],
});

const ws = new PerpsWsClient(sdk, {
  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 — 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
• Trading — All account setup and trading 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

• Default margin mode: CROSS — applied when marginMode is omitted on placeOrder or updateLeverage. 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 order.
• Withdrawals & sendAsset: signed by the user’s L1 wallet every time; agents cannot move funds.

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 route. Under unifiedAccount and portfolioMargin, it also reads each spot token’s total minus hold for the spot route. See Withdrawals for the full per-route 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 / Available Markets 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 -> sign -> execute pattern for all operations
• LI.FI Docs — Cross-chain swap and bridge for deposits