@quicknode/hyperliquid-sdk

Hyperliquid SDK for TypeScript

The simplest way to trade on Hyperliquid. One line to place orders, zero ceremony.

import { HyperliquidSDK } from '@quicknode/hyperliquid-sdk';

const sdk = new HyperliquidSDK(endpoint);
const order = await sdk.marketBuy("BTC", { notional: 100 });  // Buy $100 of BTC

That's it. No build-sign-send ceremony. No manual hash signing. No nonce tracking. Just trading.

Community SDK — Not affiliated with Hyperliquid Foundation.

Installation

npm install @quicknode/hyperliquid-sdk
# or
yarn add @quicknode/hyperliquid-sdk

Everything is included: trading, market data, WebSocket streaming, gRPC streaming, HyperCore blocks, and EVM.

Quick Start

1. Set your private key

export PRIVATE_KEY="0xYOUR_PRIVATE_KEY"

2. Start trading

import { HyperliquidSDK } from '@quicknode/hyperliquid-sdk';

const sdk = new HyperliquidSDK(endpoint);

// Market orders
const order1 = await sdk.marketBuy("BTC", { size: 0.001 });
const order2 = await sdk.marketSell("ETH", { notional: 100 });  // $100 worth

// Limit orders
const order3 = await sdk.buy("BTC", { size: 0.001, price: 65000, tif: "gtc" });

// Check your order
console.log(order3.status);  // "filled" or "resting"
console.log(order3.oid);     // Order ID

Data APIs

All data APIs are accessed through the SDK instance.

Info API

50+ methods for account state, positions, market data, and metadata.

const sdk = new HyperliquidSDK(endpoint);

// Market data
await sdk.info.allMids();                          // All mid prices
await sdk.info.l2Book("BTC");                      // Order book
await sdk.info.recentTrades("BTC");                // Recent trades
await sdk.info.candles("BTC", "1h", start, end);   // OHLCV candles
await sdk.info.fundingHistory("BTC", start, end);  // Funding history
await sdk.info.predictedFundings();                // Predicted funding rates

// Metadata
await sdk.info.meta();                             // Exchange metadata
await sdk.info.spotMeta();                         // Spot metadata
await sdk.info.exchangeStatus();                   // Exchange status
await sdk.info.perpDexs();                         // Perpetual DEX info
await sdk.info.maxMarketOrderNtls();               // Max market order notionals

// User data
await sdk.info.clearinghouseState("0x...");        // Positions & margin
await sdk.info.spotClearinghouseState("0x...");    // Spot balances
await sdk.info.openOrders("0x...");                // Open orders
await sdk.info.frontendOpenOrders("0x...");        // Enhanced open orders
await sdk.info.orderStatus("0x...", oid);          // Specific order status
await sdk.info.historicalOrders("0x...");          // Order history
await sdk.info.userFills("0x...");                 // Trade history
await sdk.info.userFillsByTime("0x...", start);    // Fills by time range
await sdk.info.userFunding("0x...");               // Funding payments
await sdk.info.userFees("0x...");                  // Fee structure
await sdk.info.userRateLimit("0x...");             // Rate limit status
await sdk.info.userRole("0x...");                  // Account type
await sdk.info.portfolio("0x...");                 // Portfolio history
await sdk.info.subAccounts("0x...");               // Sub-accounts
await sdk.info.extraAgents("0x...");               // API keys/agents

// TWAP
await sdk.info.userTwapSliceFills("0x...");        // TWAP slice fills

// Batch queries
await sdk.info.batchClearinghouseStates(["0x...", "0x..."]);

// Vaults
await sdk.info.vaultSummaries();                   // All vault summaries
await sdk.info.vaultDetails("0x...");              // Specific vault
await sdk.info.userVaultEquities("0x...");         // User's vault equities
await sdk.info.leadingVaults("0x...");             // Vaults user leads

// Delegation/Staking
await sdk.info.delegations("0x...");               // Active delegations
await sdk.info.delegatorSummary("0x...");          // Delegation summary
await sdk.info.delegatorHistory("0x...");          // Delegation history
await sdk.info.delegatorRewards("0x...");          // Delegation rewards

// Tokens
await sdk.info.tokenDetails(tokenId);              // Token details
await sdk.info.spotDeployState("0x...");           // Spot deployment state

// Other
await sdk.info.referral("0x...");                  // Referral info
await sdk.info.maxBuilderFee("0x...", "0x...");    // Builder fee limits
await sdk.info.approvedBuilders("0x...");          // Approved builders
await sdk.info.liquidatable();                     // Liquidatable positions

HyperCore API

Block data, trading operations, and real-time data via JSON-RPC.

const sdk = new HyperliquidSDK(endpoint);

// Block data
await sdk.core.latestBlockNumber();                  // Latest block
await sdk.core.getBlock(12345);                      // Get specific block
await sdk.core.getBatchBlocks(100, 110);             // Get block range
await sdk.core.latestBlocks({ count: 10 });          // Latest blocks

// Recent data
await sdk.core.latestTrades({ count: 10 });          // Recent trades (all coins)
await sdk.core.latestTrades({ count: 10, coin: "BTC" }); // Recent BTC trades
await sdk.core.latestOrders({ count: 10 });          // Recent order events
await sdk.core.latestBookUpdates({ count: 10 });     // Recent book updates

// Discovery
await sdk.core.listDexes();                          // All DEXes
await sdk.core.listMarkets();                        // All markets
await sdk.core.listMarkets({ dex: "hyperliquidity" }); // Markets by DEX

// Order queries
await sdk.core.openOrders("0x...");                  // User's open orders
await sdk.core.orderStatus("0x...", oid);            // Specific order status
await sdk.core.preflight(...);                       // Validate order before signing

EVM (Ethereum JSON-RPC)

50+ Ethereum JSON-RPC methods for Hyperliquid's EVM chain (chain ID 999 mainnet, 998 testnet).

const sdk = new HyperliquidSDK(endpoint);

// Chain info
await sdk.evm.blockNumber();                       // Latest block
await sdk.evm.chainId();                           // 999 mainnet, 998 testnet
await sdk.evm.gasPrice();                          // Current gas price
await sdk.evm.maxPriorityFeePerGas();              // Priority fee
await sdk.evm.netVersion();                        // Network version
await sdk.evm.syncing();                           // Sync status

// Accounts
await sdk.evm.getBalance("0x...");                 // Account balance
await sdk.evm.getTransactionCount("0x...");        // Nonce
await sdk.evm.getCode("0x...");                    // Contract code
await sdk.evm.getStorageAt("0x...", position);     // Storage value

// Transactions
await sdk.evm.call({ to: "0x...", data: "0x..." });
await sdk.evm.estimateGas(tx);
await sdk.evm.sendRawTransaction(signedTx);
await sdk.evm.getTransactionByHash("0x...");
await sdk.evm.getTransactionReceipt("0x...");

// Blocks
await sdk.evm.getBlockByNumber(12345);
await sdk.evm.getBlockByHash("0x...");
await sdk.evm.getBlockReceipts(12345);
await sdk.evm.getBlockTransactionCountByNumber(12345);

// Logs
await sdk.evm.getLogs({ address: "0x...", topics: [...] });

// HyperEVM-specific
await sdk.evm.bigBlockGasPrice();                  // Big block gas price
await sdk.evm.usingBigBlocks();                    // Is using big blocks?
await sdk.evm.getSystemTxsByBlockNumber(12345);

// Debug/Trace
await sdk.evm.debugTraceTransaction("0x...", { tracer: "callTracer" });
await sdk.evm.debugTraceBlockByNumber(12345);
await sdk.evm.traceTransaction("0x...");
await sdk.evm.traceBlock(12345);

Real-Time Streaming

WebSocket Streaming

20+ subscription types for real-time data with automatic reconnection.

const sdk = new HyperliquidSDK(endpoint);

// Subscribe to trades
sdk.stream.trades(["BTC", "ETH"], (t) => console.log(`Trade: ${JSON.stringify(t)}`));

// Subscribe to book updates
sdk.stream.bookUpdates(["BTC"], (b) => console.log(`Book: ${JSON.stringify(b)}`));

// Subscribe to orders (your orders)
sdk.stream.orders(["BTC"], (o) => console.log(`Order: ${JSON.stringify(o)}`), { users: ["0x..."] });

// Start streaming
sdk.stream.start();

// ... do other work ...

// Stop streaming
sdk.stream.stop();

Available streams:

Market Data:

• trades(coins, callback) — Executed trades
• bookUpdates(coins, callback) — Order book changes
• l2Book(coin, callback) — L2 order book snapshots
• allMids(callback) — All mid price updates
• candle(coin, interval, callback) — Candlestick data
• bbo(coin, callback) — Best bid/offer updates
• activeAssetCtx(coin, callback) — Asset context (pricing, volume)

User Data:

• orders(coins, callback, options) — Order lifecycle events
• openOrders(user, callback) — User's open orders
• orderUpdates(user, callback) — Order status changes
• userEvents(user, callback) — All user events
• userFills(user, callback) — Trade fills
• userFundings(user, callback) — Funding payments
• userNonFundingLedger(user, callback) — Ledger changes
• clearinghouseState(user, callback) — Position updates
• activeAssetData(user, coin, callback) — Trading parameters

TWAP:

• twap(coins, callback) — TWAP execution
• twapStates(user, callback) — TWAP algorithm states
• userTwapSliceFills(user, callback) — TWAP slice fills
• userTwapHistory(user, callback) — TWAP history

System:

• events(callback) — System events (funding, liquidations)
• notification(user, callback) — User notifications
• webData3(user, callback) — Aggregate user info
• writerActions(user, callback) — Writer actions

gRPC Streaming (High Performance)

Lower latency streaming via gRPC for high-frequency applications.

const sdk = new HyperliquidSDK(endpoint);

// Subscribe to trades
sdk.grpc.trades(["BTC", "ETH"], (t) => console.log(`Trade: ${JSON.stringify(t)}`));

// Subscribe to L2 order book (aggregated by price level)
sdk.grpc.l2Book("BTC", (b) => console.log(`Book: ${JSON.stringify(b)}`), { nSigFigs: 5 });

// Subscribe to L4 order book (CRITICAL: individual orders with order IDs)
sdk.grpc.l4Book("BTC", (b) => console.log(`L4: ${JSON.stringify(b)}`));

// Subscribe to blocks
sdk.grpc.blocks((b) => console.log(`Block: ${JSON.stringify(b)}`));

// Start streaming
await sdk.grpc.start();

// ... do other work ...

sdk.grpc.stop();

Available gRPC Streams:

Method	Parameters	Description
trades(coins, callback)	coins: string[]	Executed trades with price, size, direction
orders(coins, callback, options)	coins: string[], users?: string[]	Order lifecycle events
bookUpdates(coins, callback)	coins: string[]	Order book changes (deltas)
l2Book(coin, callback, options)	coin: string, nSigFigs?: number	L2 order book (aggregated by price)
l4Book(coin, callback)	coin: string	L4 order book (individual orders)
blocks(callback)	-	Block data
twap(coins, callback)	coins: string[]	TWAP execution updates
events(callback)	-	System events (funding, liquidations)
writerActions(callback)	-	Writer actions

L4 Order Book (Critical for Trading)

L4 order book shows every individual order with its order ID. This is essential for:

• Market Making: Know your exact queue position
• Order Flow Analysis: Detect large orders and icebergs
• Optimal Execution: See exactly what you're crossing
• HFT: Lower latency than WebSocket

const sdk = new HyperliquidSDK(endpoint);

sdk.grpc.l4Book("BTC", (data) => {
  // L4 book data structure:
  // {
  //   "coin": "BTC",
  //   "bids": [[price, size, order_id], ...],
  //   "asks": [[price, size, order_id], ...]
  // }
  const bids = data.bids || [];
  for (const bid of bids.slice(0, 3)) {
    const [px, sz, oid] = bid;
    console.log(`Bid: $${Number(px).toLocaleString()} x ${sz} (order: ${oid})`);
  }
});

await sdk.grpc.start();

L2 vs L4 Comparison

Feature	L2 Book	L4 Book
Aggregation	By price level	Individual orders
Order IDs	No	Yes
Queue Position	Unknown	Visible
Bandwidth	Lower	Higher
Protocol	WebSocket or gRPC	gRPC only
Use Case	Price monitoring	Market making, HFT

Trading Features

One-Line Orders

// Market orders
await sdk.marketBuy("BTC", { size: 0.001 });
await sdk.marketSell("ETH", { notional: 100 });

// Limit orders
await sdk.buy("BTC", { size: 0.001, price: 65000 });
await sdk.sell("ETH", { size: 0.5, price: 4000, tif: "gtc" });

// Perp trader aliases
await sdk.long("BTC", { size: 0.001, price: 65000 });
await sdk.short("ETH", { notional: 500, tif: "ioc" });

Order Management

// Place, modify, cancel
const order = await sdk.buy("BTC", { size: 0.001, price: 60000, tif: "gtc" });
await order.modify({ price: 61000 });
await order.cancel();

// Cancel all
await sdk.cancelAll();
await sdk.cancelAll("BTC");  // Just BTC orders

// Dead-man's switch
await sdk.scheduleCancel(Date.now() + 60000);

Position Management

await sdk.closePosition("BTC");  // Close entire position

Leverage & Margin

// Update leverage
await sdk.updateLeverage("BTC", { leverage: 10, isCross: true });   // 10x cross
await sdk.updateLeverage("ETH", { leverage: 5, isCross: false });   // 5x isolated

// Isolated margin management
await sdk.updateIsolatedMargin("BTC", { amount: 100, isBuy: true });   // Add margin to long
await sdk.updateIsolatedMargin("ETH", { amount: -50, isBuy: false });  // Remove from short
await sdk.topUpIsolatedOnlyMargin("BTC", 100);                         // Special maintenance mode

Trigger Orders (Stop Loss / Take Profit)

import { Side } from '@quicknode/hyperliquid-sdk';

// Stop loss (market order when triggered)
await sdk.stopLoss("BTC", { size: 0.001, triggerPrice: 60000 });

// Stop loss (limit order when triggered)
await sdk.stopLoss("BTC", { size: 0.001, triggerPrice: 60000, limitPrice: 59500 });

// Take profit
await sdk.takeProfit("BTC", { size: 0.001, triggerPrice: 70000 });

// Buy-side (closing shorts)
await sdk.stopLoss("BTC", { size: 0.001, triggerPrice: 70000, side: Side.BUY });

TWAP Orders

// Time-weighted average price order
const result = await sdk.twapOrder("BTC", {
  size: 0.01,
  isBuy: true,
  durationMinutes: 60,
  randomize: true
});
const twapId = result.response.data.running.id;

// Cancel TWAP
await sdk.twapCancel("BTC", twapId);

Transfers

// Internal transfers
await sdk.transferSpotToPerp(100);
await sdk.transferPerpToSpot(100);

// External transfers
await sdk.transferUsd("0x...", 100);
await sdk.transferSpot("0x...", "PURR", 100);
await sdk.sendAsset("0x...", "USDC", 100);

// Withdraw to L1 (Arbitrum)
await sdk.withdraw("0x...", 100);

Vaults

const HLP_VAULT = "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303";
await sdk.vaultDeposit(HLP_VAULT, 100);
await sdk.vaultWithdraw(HLP_VAULT, 50);

Staking

// Stake/unstake HYPE
await sdk.stake(1000);
await sdk.unstake(500);  // 7-day queue

// Delegate to validators
await sdk.delegate("0x...", 500);
await sdk.undelegate("0x...", 250);

Fluent Order Builder

import { Order } from '@quicknode/hyperliquid-sdk';

const order = await sdk.order(
  Order.buy("BTC")
    .size(0.001)
    .price(65000)
    .gtc()
    .reduceOnly()
);

Error Handling

All errors inherit from HyperliquidError with a code and message.

import {
  HyperliquidError,
  ApprovalError,
  InsufficientMarginError,
  GeoBlockedError,
} from '@quicknode/hyperliquid-sdk';

try {
  const order = await sdk.buy("BTC", { size: 0.001, price: 65000 });
} catch (e) {
  if (e instanceof ApprovalError) {
    console.log(`Need approval: ${e.guidance}`);
  } else if (e instanceof InsufficientMarginError) {
    console.log(`Not enough margin: ${e.guidance}`);
  } else if (e instanceof GeoBlockedError) {
    console.log(`Geo-blocked: ${e.message}`);
  } else if (e instanceof HyperliquidError) {
    console.log(`Error [${e.code}]: ${e.message}`);
  }
}

Available error types:

• HyperliquidError — Base error
• BuildError — Order building failed
• SendError — Transaction send failed
• ApprovalError — Builder fee approval needed
• ValidationError — Invalid parameters
• SignatureError — Signature verification failed
• NoPositionError — No position to close
• OrderNotFoundError — Order not found
• GeoBlockedError — Region blocked
• InsufficientMarginError — Not enough margin
• LeverageError — Invalid leverage
• RateLimitError — Rate limited
• MaxOrdersError — Too many orders
• ReduceOnlyError — Reduce-only constraint
• DuplicateOrderError — Duplicate order
• UserNotFoundError — User not found
• MustDepositError — Deposit required
• InvalidNonceError — Invalid nonce

API Reference

HyperliquidSDK

new HyperliquidSDK(
  endpoint?: string,           // Endpoint URL
  options?: {
    privateKey?: string,       // Falls back to PRIVATE_KEY env var
    autoApprove?: boolean,     // Auto-approve builder fee (default: true)
    maxFee?: string,           // Max fee for auto-approval (default: "1%")
    slippage?: number,         // Default slippage for market orders (default: 0.03)
    timeout?: number,          // Request timeout in ms (default: 30000)
    testnet?: boolean,         // Use testnet (default: false)
  }
)

// Access sub-clients
sdk.info      // Info API (market data, user data, metadata)
sdk.core      // HyperCore (blocks, trades, orders)
sdk.evm       // EVM (Ethereum JSON-RPC)
sdk.stream    // WebSocket streaming
sdk.grpc      // gRPC streaming

Examples

See the examples directory for complete, runnable examples:

Trading:

• market_order.ts — Place market orders
• place_order.ts — Place limit orders
• modify_order.ts — Modify existing orders
• cancel_order.ts — Cancel orders
• cancel_by_cloid.ts — Cancel by client order ID
• cancel_all.ts — Cancel all orders
• close_position.ts — Close positions
• fluent_builder.ts — Fluent order builder
• roundtrip.ts — Buy and sell round trip
• hip3_order.ts — HIP-3 DEX orders

Trigger Orders:

• trigger_orders.ts — Stop loss and take profit orders

TWAP:

• twap.ts — Time-weighted average price orders

Leverage & Margin:

• leverage.ts — Update leverage
• isolated_margin.ts — Isolated margin management

Transfers & Withdrawals:

• transfers.ts — USD and spot transfers
• withdraw.ts — Withdraw to L1 (Arbitrum)

Vaults:

• vaults.ts — Vault deposits and withdrawals

Staking:

• staking.ts — Stake, unstake, and delegate

Approval:

• approve.ts — Builder fee approval
• builder_fee.ts — Check approval status

Market Info:

• markets.ts — List markets and mid prices
• open_orders.ts — Query open orders
• preflight.ts — Validate orders before sending

Data APIs:

• info_market_data.ts — Market data and order book
• info_user_data.ts — User positions and orders
• info_candles.ts — Candlestick data
• info_vaults.ts — Vault information
• info_batch_queries.ts — Batch queries
• hypercore_blocks.ts — Block and trade data
• evm_basics.ts — EVM chain interaction

Streaming:

• stream_trades.ts — WebSocket streaming basics
• stream_grpc.ts — gRPC streaming basics
• stream_l4_book.ts — L4 order book (individual orders)
• stream_l2_book.ts — L2 order book
• stream_orderbook.ts — L2 vs L4 comparison
• stream_websocket_all.ts — Complete WebSocket reference (20+ types)

Complete Demo:

• full_demo.ts — All features in one file

Disclaimer

This is an unofficial community SDK. It is not affiliated with Hyperliquid Foundation or Hyperliquid Labs.

Use at your own risk. Always review transactions before signing.

License

MIT License - see LICENSE for details.