Clients

A client uses a transport to call a specific part of the Hyperliquid API:

• Info: market data, account state, blockchain explorer

• Exchange: trading, fund management, account configuration

• Subscription: real-time updates via WebSocket

Read data

InfoClient gives read-only access to the Info endpoint. Works with any transport.

import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";

const transport = new HttpTransport();
const client = new InfoClient({ transport });

const mids = await client.allMids();
const book = await client.l2Book({ coin: "ETH" });

Trading

ExchangeClient executes actions on the Exchange endpoint: trading, fund management, and account configuration. Requires a wallet for signing and works with any transport.

viem

import { ExchangeClient, HttpTransport } from "@nktkas/hyperliquid";
import { privateKeyToAccount } from "viem/accounts";

const transport = new HttpTransport();
const client = new ExchangeClient({
  transport,
  wallet: privateKeyToAccount("0x..."),
});

ethers

Browser (viem)

Browser (ethers)

Custom

Place an order:

await client.order({
  orders: [{
    a: 0, // asset index
    b: true, // buy
    p: "50000", // price
    s: "0.01", // size
    r: false, // not reduce-only
    t: { limit: { tif: "Gtc" } }, // Good 'til Cancelled
  }],
  grouping: "na",
});

Multi-sig

Multi-signature accounts require multiple authorized signers to approve every action. The leader (first signer in the array) collects all signatures and submits the final transaction — only the leader's nonce is validated by the server.

import { ExchangeClient, HttpTransport } from "@nktkas/hyperliquid";
import { privateKeyToAccount } from "viem/accounts";

const transport = new HttpTransport();
const client = new ExchangeClient({
  transport,
  signers: [
    privateKeyToAccount("0x..."), // leader — submits the transaction
    privateKeyToAccount("0x..."),
  ],
  multiSigUser: "0x...", // the multi-sig account address
});

Vault and sub-account trading

To trade on behalf of a vault or sub-account, set a default or pass vaultAddress per-request:

const client = new ExchangeClient({
  transport,
  wallet,
  defaultVaultAddress: "0x...",
});

await client.order({ orders: [/* ... */], grouping: "na" }, {
  vaultAddress: "0x...",
});

Expiration

A server-side guard. The API rejects the action after this timestamp (milliseconds). See Expires After.

const client = new ExchangeClient({
  transport,
  wallet,
  defaultExpiresAfter: () => Date.now() + 60_000, // function - recomputed per request
});

const client = new ExchangeClient({
  transport,
  wallet,
  defaultExpiresAfter: Date.now() + 60_000, // static - fixed at construction time
});

await client.order({ orders: [/* ... */], grouping: "na" }, {
  expiresAfter: Date.now() + 60_000, // per-request override
});

Signature chain ID

Sets the EIP-712 domain chainId for user-signed actions. Defaults to the wallet's provider chain ID. Local wallets without a provider (e.g., privateKeyToAccount, new Wallet()) fall back to 0x1 (Ethereum mainnet). Override to set the correct chain:

const client = new ExchangeClient({
  transport,
  wallet,
  signatureChainId: "0xa4b1", // static - fixed chain ID
});

const client = new ExchangeClient({
  transport,
  wallet,
  signatureChainId: () => "0xa4b1", // function - recomputed per request
});

Nonce manager

The SDK generates nonces automatically using timestamps with auto-increment. Replace it if you need custom logic:

const client = new ExchangeClient({
  transport,
  wallet,
  nonceManager: (address) => Date.now(), // function - recomputed per request
});

Real-time updates

SubscriptionClient streams live data via WebSocket subscriptions. Requires WebSocketTransport.

import { SubscriptionClient, WebSocketTransport } from "@nktkas/hyperliquid";

const transport = new WebSocketTransport();
const client = new SubscriptionClient({ transport });

const subscription = await client.allMids((data) => {
  console.log(data.mids);
});

Unsubscribe

A single connection supports up to 1000 active subscriptions and 10 unique users. Call unsubscribe() to remove a listener and free these slots:

const subscription = await client.allMids((data) => {
  console.log(data.mids);
});

// Later
await subscription.unsubscribe();

Subscribing to the same channel multiple times reuses one underlying subscription. Each unsubscribe() removes only its listener — the channel stays open until the last one is removed:

const sub1 = await client.allMids((data) => console.log("A:", data.mids));
const sub2 = await client.allMids((data) => console.log("B:", data.mids));

await sub1.unsubscribe(); // removes listener A, subscription stays active
await sub2.unsubscribe(); // removes listener B, channel closed

Handle failures

When the WebSocket reconnects, the SDK automatically resubscribes to all active channels. If resubscription fails for a channel, its failureSignal aborts with the error:

const subscription = await client.allMids((data) => {
  console.log(data.mids);
});

subscription.failureSignal.addEventListener("abort", () => {
  console.error("Resubscription failed:", subscription.failureSignal.reason);
  // Create a new subscription or explore the error...
});

Common options

Cancellation

InfoClient methods accept an optional AbortSignal as the last argument:

const controller = new AbortController();
const mids = await client.allMids(controller.signal);

ExchangeClient methods accept it inside the options object (also last argument). Unlike Expiration, which is a server-side guard, cancellation aborts the request on the client side before or during delivery:

const controller = new AbortController();
await client.order({ orders: [/* ... */], grouping: "na" }, {
  signal: controller.signal,
});