Hyperliquid SDK

Blazing fast TypeScript SDK for Hyperliquid. Try the docs.

Features

• Typed. Source code is 100% TypeScript with comprehensive type safety.
• Minimal dependencies. A few small, trusted dependencies keep the bundle lean.
• Cross-environment support. Compatible with Bun, Node.js, React Native, and all major JavaScript runtimes.
• Easy integration. Works seamlessly with viem accounts, local private keys or JSON-RPC browser wallets.
• Tested. Offline and online test suites run in CI.

Installation

Bun 1.3.3+

bun add @bloxwap/hyperliquid

Node.js 22.12+ / React Native 0.86+

npm i @bloxwap/hyperliquid

pnpm

pnpm add @bloxwap/hyperliquid

Yarn

yarn add @bloxwap/hyperliquid

React Native needs polyfills for the fastAssetCtxs subscription and for versions below 0.86. See the documentation.

Release status

0.7.0 is an early developer preview; expect breaking changes before 1.0.

Usage

Read

// Import module
import { HttpTransport, InfoClient } from "@bloxwap/hyperliquid";

// Set up client with transport
const transport = new HttpTransport();
const info = new InfoClient({ transport });

// Query data

// Retrieve mids for all coins
const mids = await info.allMids();

// Retrieve a user's open orders
const openOrders = await info.openOrders({ user: "0x..." });

// L2 book snapshot
const book = await info.l2Book({ coin: "BTC" });

Trade

// Import modules
import { ExchangeClient, HttpTransport } from "@bloxwap/hyperliquid";
import { privateKeyToAccount } from "viem/accounts";

// Set up client with wallet and transport
const wallet = privateKeyToAccount("0x...");

const transport = new HttpTransport();
const exchange = new ExchangeClient({ transport, wallet });

// Execute an action

// Place an order
const result = await exchange.order({
  orders: [{
    a: 0,
    b: true,
    p: "95000",
    s: "0.01",
    r: false,
    t: { limit: { tif: "Gtc" } },
  }],
  grouping: "na",
});

// Update leverage
await exchange.updateLeverage({ asset: 0, isCross: true, leverage: 5 });

// Initiate a withdrawal request
await exchange.withdraw3({ destination: "0x...", amount: "1" });

For low-latency bots, pass the raw private key string as wallet: the client then signs with WASM secp256k1 by default, with a pure-JS fallback where WASM cannot load (~274 to ~104 µs per order on Node 24, ~155 to ~102 µs on Bun 1.4, measured on a Linux box). Also batch many orders into one exchange.order({ orders: [...] }) call: ~161 µs down to ~3.2 µs per order when 100 orders share one call. Details in the low-latency recipe.

Subscribe

// Import module
import { SubscriptionClient, WebSocketTransport } from "@bloxwap/hyperliquid";

// Set up client with transport
const transport = new WebSocketTransport();
const subs = new SubscriptionClient({ transport });

// Subscribe to events

// Subscribe to mids for all coins
await subs.allMids((data) => {
  console.log(data);
});

// Subscribe to user's open orders
await subs.openOrders({ user: "0x..." }, (data) => {
  console.log(data);
});

// Subscribe to L2 book snapshot
await subs.l2Book({ coin: "ETH" }, (data) => {
  console.log(data);
});

Documentation

Browse the SDK documentation for installation, clients, transports, signing, utilities, and guides.

The documentation uses Fumadocs and is hosted on GitHub Pages. Its Markdown source lives in apps/docs/content/docs/.

Development

This repository is a Bun workspace with one install and one root bun.lock:

Workspace	Purpose
packages/hyperliquid	Published @bloxwap/hyperliquid SDK, source, tests, and package tooling
apps/docs	Fumadocs application, Markdown content, and GitHub Pages export

The root package is private and coordinates development. The SDK builds to packages/hyperliquid/dist; the docs app exports static files to apps/docs/out. Only the SDK's generated package is published to npm.

Run these commands from the repository root:

bun install --frozen-lockfile
bun run check
bun run test:offline
bun run build

Type-checking and declaration emit use tsrs, the Rust port of the TypeScript 7 compiler, which ships native binaries for macOS arm64 and Linux x64/arm64. On other platforms, or to compare against TypeScript 5, run bun run typecheck:tsc and build with HL_TSC=tsc bun run build. TypeScript 5.9 stays installed for the build's JS-API tooling and for the published-consumer check.

To develop the documentation, run bun run docs:dev and open http://localhost:3901. See the documentation app guide for content checks, production builds, and GitHub Pages deployment.

Coverage target is 100% line, branch, and function coverage.

Security

This SDK handles private keys and wallet operations. Never hardcode private keys in source or commit them to git. Load them from environment variables or a secret store (Bun auto-loads a local .env, which is gitignored in this repo).

For trading bots, prefer a Hyperliquid agent wallet (API wallet) over the master account key: an agent key can trade but cannot withdraw, and it can be revoked without rotating the master key.

See Signing for how wallets, signatures, and nonces work.

License

MIT