# Hyperliquid SDK (@bloxwap/hyperliquid)

> A fast, typed Hyperliquid SDK for TypeScript and JavaScript. Connect, trade, and subscribe with Bloxwap. `@bloxwap/hyperliquid` is an MIT-licensed, community-supported TypeScript client for the Hyperliquid exchange API, published on npm by Bloxwap, Inc.

It covers the whole public Hyperliquid API: the Info endpoint (market data and account state), the Exchange endpoint (signed trading and account actions), WebSocket subscriptions, and the Explorer endpoint. Requests and responses are fully typed and validated. It runs on Bun 1.3.3+, Node.js 22.12+, modern browsers, and React Native, on mainnet or testnet.

## When to use this

Use `@bloxwap/hyperliquid` when an agent or developer, working in TypeScript or JavaScript, needs to:

- Read Hyperliquid market data: mid prices, order books, candles, funding, asset metadata, and perp or spot contexts (`InfoClient`).
- Read a user's positions, open orders, fills, balances, vault equity, or portfolio history (`InfoClient`).
- Place, modify, or cancel orders; move funds; manage leverage, agent wallets, vaults, sub-accounts, or multi-sig accounts (`ExchangeClient`).
- Stream live prices, trades, order books, and account events over WebSocket with automatic reconnection and resubscription (`SubscriptionClient`).
- Look up blocks, transactions, and addresses (`ExplorerClient`).
- Sign Hyperliquid L1 and user-signed actions with a viem account, a browser wallet, or a raw private key (`@bloxwap/hyperliquid/signing`).
- Format prices and sizes to Hyperliquid's precision rules and map symbols to asset IDs (`@bloxwap/hyperliquid/utils`).

Do not use it for other exchanges, for languages other than TypeScript or JavaScript (use Hyperliquid's official Python SDK instead), or as a hosted trading service: it is a client library that runs in your code and never holds keys or funds for you.

## How to call it

Install with `npm i @bloxwap/hyperliquid` (or `bun add`, `pnpm add`, `yarn add`), then:

```ts
import { HttpTransport, InfoClient } from "@bloxwap/hyperliquid";

const info = new InfoClient({ transport: new HttpTransport() });
const mids = await info.allMids(); // { BTC: "…", ETH: "…", … }
```

Trading needs a wallet. Test with `new HttpTransport({ isTestnet: true })` before using a funded key:

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

const exchange = new ExchangeClient({ transport: new HttpTransport(), wallet: privateKeyToAccount("0x...") });
await exchange.order({
  orders: [{ a: 0, b: true, p: "50000", s: "0.01", r: false, t: { limit: { tif: "Gtc" } } }],
  grouping: "na",
});
```

Every client method takes the Hyperliquid API's own request fields and returns its typed response. Errors are typed classes (`ApiRequestError`, `HttpRequestError`, `WebSocketRequestError`, `ValidationError`); see Error handling below.

## Docs

Every documentation page also has a Markdown mirror: append `.md` to its path without the trailing slash (for example, `/hyperliquid/docs/clients/` becomes `/hyperliquid/docs/clients.md`).

- [Introduction](https://bloxwap.github.io/hyperliquid/docs/): Install the Hyperliquid TypeScript SDK and start reading market data, trading, and subscribing to updates.
- [Clients](https://bloxwap.github.io/hyperliquid/docs/clients/): Use the Info, Exchange, Subscription, and Explorer clients to work with the Hyperliquid API.
- [Error handling](https://bloxwap.github.io/hyperliquid/docs/error-handling/): Handle validation, signing, API, and transport errors with typed SDK error classes.
- [Guides](https://bloxwap.github.io/hyperliquid/docs/guides/): Practical guides for market orders, agent wallets, vaults, browser wallets, and smaller bundles.
- [Agent wallets and vaults](https://bloxwap.github.io/hyperliquid/docs/guides/agent-wallets-and-vaults/): Authorize agent wallets and trade on behalf of Hyperliquid vaults and subaccounts.
- [Browser wallets](https://bloxwap.github.io/hyperliquid/docs/guides/browser-wallets/): Connect browser wallets to ExchangeClient and understand signature prompts.
- [Market orders](https://bloxwap.github.io/hyperliquid/docs/guides/market-orders/): Place immediate-or-cancel orders with explicit slippage and valid price and size precision.
- [Tree-shaking](https://bloxwap.github.io/hyperliquid/docs/guides/tree-shaking/): Use narrow entry points and direct method imports to reduce SDK bundle size and startup work.
- [Reference](https://bloxwap.github.io/hyperliquid/docs/reference/): Track known differences between official Hyperliquid documentation and live API behavior.
- [Known documentation drift](https://bloxwap.github.io/hyperliquid/docs/reference/known-drift/): Verified differences between the official Hyperliquid documentation, live servers, and SDK types.
- [Signing](https://bloxwap.github.io/hyperliquid/docs/signing/): Sign Hyperliquid actions, manage nonces, support wallets, and configure optional signing accelerators.
- [Connect to Hyperliquid](https://bloxwap.github.io/hyperliquid/docs/transports/): Configure HTTP and WebSocket transports, rate limits, retries, and connection lifecycle.
- [Utilities](https://bloxwap.github.io/hyperliquid/docs/utilities/): Format valid prices and sizes and resolve Hyperliquid asset IDs with SymbolConverter.

## Optional

- [Full documentation as Markdown](https://bloxwap.github.io/hyperliquid/llms-full.txt): Every docs page above in one plain-text file.
- [Sitemap](https://bloxwap.github.io/hyperliquid/sitemap.xml): Every page on this site.
- [Source code](https://github.com/bloxwap/hyperliquid): MIT-licensed repository and issue tracker.
- [npm package](https://www.npmjs.com/package/@bloxwap/hyperliquid): Current version 0.5.0.
- [About Bloxwap](https://bloxwap.github.io/hyperliquid/about/): The company that maintains the SDK.
- [Contact](https://bloxwap.github.io/hyperliquid/contact/): support@bloxwap.com, GitHub issues, X, and Discord.
- [Privacy](https://bloxwap.github.io/hyperliquid/privacy/): No cookies or analytics on this site.