@nktkas/hyperliquid 0.19.2 → 0.21.0

package/README.md

@@ -20,21 +20,23 @@ runtimes, written in TypeScript and provided with tests.
 
 ## Installation
 
+> [!NOTE]
+> While this library is in TypeScript, it can also be used in JavaScript and there is support for ESM/CommonJS.
+
+### Node.js (choose your package manager)
+
 ```
-# npm
 npm i @nktkas/hyperliquid
 
-# deno
-deno add jsr:@nktkas/hyperliquid
+pnpm add @nktkas/hyperliquid
 
-# pnpm >=10.9.0
-pnpm i jsr:@nktkas/hyperliquid
+yarn add @nktkas/hyperliquid
+```
 
-# yarn >=4.9.0
-yarn add jsr:@nktkas/hyperliquid
+### Deno
 
-# bun
-bun i @nktkas/hyperliquid
+```
+deno add jsr:@nktkas/hyperliquid
 ```
 
 ## Quick Start
@@ -43,9 +45,9 @@ bun i @nktkas/hyperliquid
 import * as hl from "@nktkas/hyperliquid";
 
 const transport = new hl.HttpTransport();
-const client = new hl.PublicClient({ transport });
+const infoClient = new hl.InfoClient({ transport });
 
-const openOrders = await client.openOrders({ user: "0x..." }); // Change to your address
+const openOrders = await infoClient.openOrders({ user: "0x..." }); // Change to your address
 ```
 
 ```ts
@@ -55,9 +57,9 @@ import { privateKeyToAccount } from "viem/accounts";
 const wallet = privateKeyToAccount("0x..."); // Your private key
 
 const transport = new hl.HttpTransport();
-const client = new hl.WalletClient({ wallet, transport });
+const exchClient = new hl.ExchangeClient({ wallet, transport });
 
-const result = await client.order({
+const result = await exchClient.order({
     orders: [{
         a: 0, // Asset index
         b: true, // Buy order
@@ -78,11 +80,9 @@ const result = await client.order({
 import * as hl from "@nktkas/hyperliquid";
 
 const transport = new hl.WebSocketTransport();
-const client = new hl.EventClient({ transport });
+const subsClient = new hl.SubscriptionClient({ transport });
 
-// Subscribe to events
-const sub = await client.allMids((event) => {
-    // Handle the event
+const sub = await subsClient.allMids((event) => {
     console.log(event);
 });
 
@@ -96,7 +96,7 @@ await sub.unsubscribe(); // Unsubscribe from the event
 First, choose and configure your transport layer (more details in the [API Reference](#transports)):
 
 ```ts
-import * as hl from "@nktkas/hyperliquid"; // support ESM & Common.js
+import * as hl from "@nktkas/hyperliquid";
 
 // HTTP Transport
 const httpTransport = new hl.HttpTransport(); // Accepts optional parameters
@@ -109,19 +109,19 @@ const wsTransport = new hl.WebSocketTransport(); // Accepts optional parameters
 
 Next, initialize a client with the transport layer (more details in the [API Reference](#clients)):
 
-#### Create PublicClient
+#### Create InfoClient
 
 ```ts
-import * as hl from "@nktkas/hyperliquid"; // support ESM & Common.js
+import * as hl from "@nktkas/hyperliquid";
 
 const transport = new hl.HttpTransport(); // or WebSocketTransport
-const client = new hl.PublicClient({ transport });
+const infoClient = new hl.InfoClient({ transport });
 ```
 
-#### Create WalletClient
+#### Create ExchangeClient
 
 ```ts
-import * as hl from "@nktkas/hyperliquid"; // support ESM & Common.js
+import * as hl from "@nktkas/hyperliquid";
 import { createWalletClient, custom } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { ethers } from "ethers";
@@ -130,53 +130,53 @@ const transport = new hl.HttpTransport(); // or WebSocketTransport
 
 // 1. Using Viem with private key
 const viemAccount = privateKeyToAccount("0x...");
-const viemClient = new hl.WalletClient({ wallet: viemAccount, transport });
+const ExchangeClient_Viem = new hl.ExchangeClient({ wallet: viemAccount, transport });
 
 // 2. Using Ethers (or Ethers V5) with private key
 const ethersWallet = new ethers.Wallet("0x...");
-const ethersClient = new hl.WalletClient({ wallet: ethersWallet, transport });
+const ExchangeClient_Ethers = new hl.ExchangeClient({ wallet: ethersWallet, transport });
 
 // 3. Using external wallet (e.g. MetaMask) via Viem
 const [account] = await window.ethereum.request({ method: "eth_requestAccounts" });
 const externalWallet = createWalletClient({ account, transport: custom(window.ethereum) });
-const viemMetamaskClient = new hl.WalletClient({ wallet: externalWallet, transport });
+const ExchangeClient_ViemMetamask = new hl.ExchangeClient({ wallet: externalWallet, transport });
 
 // 4. Using external wallet (e.g. MetaMask) via `window.ethereum` directly
-const windowMetamaskClient = new hl.WalletClient({ wallet: window.ethereum, transport });
+const ExchangeClient_WindowMetamask = new hl.ExchangeClient({ wallet: window.ethereum, transport });
 ```
 
-#### Create EventClient
+#### Create SubscriptionClient
 
 ```ts
-import * as hl from "@nktkas/hyperliquid"; // support ESM & Common.js
+import * as hl from "@nktkas/hyperliquid";
 
 const transport = new hl.WebSocketTransport(); // only WebSocketTransport
-const client = new hl.EventClient({ transport });
+const subsClient = new hl.SubscriptionClient({ transport });
 ```
 
 ### 3) Use Client
 
 Finally, use client methods to interact with the Hyperliquid API (more details in the [API Reference](#clients)):
 
-#### Example of using a public client
+#### Example of using an InfoClient
 
 ```ts
 import * as hl from "@nktkas/hyperliquid";
 
 const transport = new hl.HttpTransport();
-const client = new hl.PublicClient({ transport });
+const infoClient = new hl.InfoClient({ transport });
 
 // L2 Book
-const l2Book = await client.l2Book({ coin: "BTC" });
+const l2Book = await infoClient.l2Book({ coin: "BTC" });
 
 // Account clearinghouse state
-const clearinghouseState = await client.clearinghouseState({ user: "0x..." });
+const clearinghouseState = await infoClient.clearinghouseState({ user: "0x..." });
 
 // Open orders
-const openOrders = await client.openOrders({ user: "0x..." });
+const openOrders = await infoClient.openOrders({ user: "0x..." });
 ```
 
-#### Example of using a wallet client
+#### Example of using an ExchangeClient
 
 ```ts
 import * as hl from "@nktkas/hyperliquid";
@@ -184,10 +184,10 @@ import { privateKeyToAccount } from "viem/accounts";
 
 const account = privateKeyToAccount("0x...");
 const transport = new hl.HttpTransport();
-const client = new hl.WalletClient({ wallet: account, transport });
+const exchClient = new hl.ExchangeClient({ wallet: account, transport });
 
 // Place an orders
-const result = await client.order({
+const result = await exchClient.order({
     orders: [{
         a: 0,
         b: true,
@@ -204,43 +204,40 @@ const result = await client.order({
 });
 
 // Approve an agent
-const result = await client.approveAgent({
+const result = await exchClient.approveAgent({
     agentAddress: "0x...",
     agentName: "agentName",
 });
 
 // Withdraw funds
-const result = await client.withdraw3({
+const result = await exchClient.withdraw3({
     destination: account.address,
     amount: "100",
 });
 ```
 
-#### Example of using an event client
+#### Example of using a SubscriptionClient
 
 ```ts
 import * as hl from "@nktkas/hyperliquid";
 
 const transport = new hl.WebSocketTransport();
-const client = new hl.EventClient({ transport });
+const subsClient = new hl.SubscriptionClient({ transport });
 
 // L2 Book updates
-const sub = await client.l2Book({ coin: "BTC" }, (data) => {
+await client.l2Book({ coin: "BTC" }, (data) => {
     console.log(data);
 });
-await sub.unsubscribe();
 
 // User fills
-const sub = await client.userFills({ user: "0x..." }, (data) => {
+await client.userFills({ user: "0x..." }, (data) => {
     console.log(data);
 });
-await sub.unsubscribe();
 
 // Explorer block updates
-const sub = await client.explorerBlock((data) => {
+await client.explorerBlock((data) => {
     console.log(data);
 });
-await sub.unsubscribe();
 ```
 
 ## API Reference
@@ -249,16 +246,16 @@ await sub.unsubscribe();
 
 A Client provides access to the Hyperliquid API endpoints.
 
-#### Public Client
+#### Info Client
 
-A Public Client which provides access to
+An Info Client which provides access to
 [Info API](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint) and Explorer API, such as
 `l2Book` and `clearinghouseState`.
 
-The Public Client class sets up with a given [Transport](#transports).
+The Info Client class sets up with a given [Transport](#transports).
 
 ```ts
-class PublicClient {
+class InfoClient {
     constructor(args: {
         transport: HttpTransport | WebSocketTransport;
     });
@@ -270,6 +267,7 @@ class PublicClient {
     l2Book(args: L2BookParameters): Promise<Book>;
     meta(): Promise<PerpsMeta>;
     metaAndAssetCtxs(): Promise<PerpsMetaAndAssetCtxs>;
+    perpDeployAuctionStatus(): Promise<DeployAuctionStatus>;
     perpDexs(): Promise<(PerpDex | null)[]>;
     perpsAtOpenInterestCap(): Promise<string[]>;
     predictedFundings(): Promise<PredictedFunding[]>;
@@ -326,18 +324,18 @@ class PublicClient {
 }
 ```
 
-#### Wallet Client
+#### Exchange Client
 
-A Wallet Client which provides access to
+An Exchange Client which provides access to
 [Exchange API](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint), such as `order`
 and `withdraw3`.
 
-The Wallet Client class sets up with a given [Transport](#transports) and a wallet instance, which can be a
+The Exchange Client class sets up with a given [Transport](#transports) and a wallet instance, which can be a
 [viem](https://viem.sh/docs/clients/wallet), [ethers.js](https://docs.ethers.org/v6/api/providers/#Signer) or other
 wallet libraries.
 
 ```ts
-class WalletClient {
+class ExchangeClient {
     constructor(args: {
         transport: HttpTransport | WebSocketTransport;
         wallet:
@@ -410,17 +408,17 @@ class WalletClient {
 }
 ```
 
-#### Event Client
+#### Subscription Client
 
-A Event Client which provides access to
+A Subscription Client which provides access to
 [Subscriptions API](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions), such as
 real-time updates for `l2Book` and `userFills`.
 
-The Event Client class sets up with a given [WebSocket Transport](#websocket-transport).
+The Subscription Client class sets up with a given [WebSocket Transport](#websocket-transport).
 
 <!-- deno-fmt-ignore-start -->
 ```ts
-class EventClient {
+class SubscriptionClient {
     constructor(args: {
         transport: WebSocketTransport;
     });
@@ -471,13 +469,10 @@ class HttpTransport {
     constructor(options?: {
         isTestnet?: boolean; // Whether to use testnet url (default: false)
         timeout?: number; // Request timeout in ms (default: 10_000)
-        server?: "api" | "api2" | "api-ui"; // Server URL (default: "api" = "https://api.hyperliquid.xyz")
         fetchOptions?: RequestInit; // A custom fetch options
         onRequest?: (request: Request) => MaybePromise<Request | void | null | undefined>; // A callback before request is sent
         onResponse?: (response: Response) => MaybePromise<Response | void | null | undefined>; // A callback after response is received
     });
-
-    request(endpoint: "info" | "exchange" | "explorer", payload: unknown, signal?: AbortSignal): Promise<unknown>;
 }
 ```
 
@@ -492,7 +487,8 @@ class WebSocketTransport {
         url?: string | URL; // WebSocket URL (default: "wss://api.hyperliquid.xyz/ws")
         timeout?: number; // Request timeout in ms (default: 10_000)
         keepAlive?: { // Keep-alive configuration
-            interval?: number; // Ping interval in ms (default: 20_000)
+            interval?: number; // Ping interval in ms (default: 30_000)
+            timeout?: number; // Pong timeout in ms (default: same as `timeout` for requests)
         };
         reconnect?: { // Reconnection policy configuration for closed connections
             maxRetries?: number; // Maximum number of reconnection attempts (default: 3)
@@ -501,16 +497,8 @@ class WebSocketTransport {
             shouldReconnect?: (event: CloseEvent) => boolean | Promise<boolean>; // Custom reconnection logic (default: Always reconnect)
             messageBuffer?: MessageBufferStrategy; // Message buffering strategy between reconnection (default: FIFO buffer)
         };
+        autoResubscribe?: boolean; // Whether to automatically resubscribe to events after reconnection (default: true)
     });
-
-    request(endpoint: "info" | "exchange", payload: unknown, signal?: AbortSignal): Promise<unknown>;
-    subscribe(
-        channel: string,
-        payload: unknown,
-        listener: (data: CustomEvent) => void,
-        signal?: AbortSignal,
-    ): Promise<Subscription>;
-
     ready(signal?: AbortSignal): Promise<void>;
     close(signal?: AbortSignal): Promise<void>;
 }
@@ -518,21 +506,15 @@ class WebSocketTransport {
 
 ## Additional Import Points
 
-The SDK exports additional import points to access internal functions.
-
 ### `/types`
 
 The import point gives access to all Hyperliquid-related types, including the base types on which class methods are
 based.
 
-Useful if you want to get all Hyperliquid types.
-
 ### `/signing`
 
 The import point gives access to functions that generate signatures for Hyperliquid transactions.
 
-Useful if you want to sign a Hyperliquid transaction yourself.
-
 ### Examples
 
 #### Cancel an order without a client

package/esm/mod.d.ts

@@ -1,8 +1,9 @@
 export * from "./src/base.js";
+export * from "./src/transports/base.js";
 export type { AbstractEthersSigner, AbstractEthersV5Signer, AbstractExtendedViemWalletClient, AbstractViemWalletClient, AbstractWindowEthereum, } from "./src/signing.js";
-export * from "./src/clients/event.js";
-export * from "./src/clients/public.js";
-export * from "./src/clients/wallet.js";
+export * from "./src/clients/subscription.js";
+export * from "./src/clients/info.js";
+export * from "./src/clients/exchange.js";
 export * from "./src/transports/http/http_transport.js";
 export * from "./src/transports/websocket/websocket_transport.js";
 export type * from "./src/types/exchange/responses.js";
@@ -10,6 +11,7 @@ export type * from "./src/types/explorer/responses.js";
 export type * from "./src/types/info/accounts.js";
 export type * from "./src/types/info/assets.js";
 export type * from "./src/types/info/delegations.js";
+export type * from "./src/types/info/markets.js";
 export type * from "./src/types/info/orders.js";
 export type * from "./src/types/info/vaults.js";
 export type * from "./src/types/subscriptions/responses.js";

package/esm/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC;AAG9B,YAAY,EACR,oBAAoB,EACpB,sBAAsB,EACtB,gCAAgC,EAChC,wBAAwB,EACxB,sBAAsB,GACzB,MAAM,kBAAkB,CAAC;AAG1B,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AAGxC,cAAc,yCAAyC,CAAC;AACxD,cAAc,mDAAmD,CAAC;AAGlE,mBAAmB,mCAAmC,CAAC;AACvD,mBAAmB,mCAAmC,CAAC;AACvD,mBAAmB,8BAA8B,CAAC;AAClD,mBAAmB,4BAA4B,CAAC;AAChD,mBAAmB,iCAAiC,CAAC;AACrD,mBAAmB,4BAA4B,CAAC;AAChD,mBAAmB,4BAA4B,CAAC;AAChD,mBAAmB,wCAAwC,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AAGzC,YAAY,EACR,oBAAoB,EACpB,sBAAsB,EACtB,gCAAgC,EAChC,wBAAwB,EACxB,sBAAsB,GACzB,MAAM,kBAAkB,CAAC;AAG1B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,mDAAmD,CAAC;AAGlE,mBAAmB,mCAAmC,CAAC;AACvD,mBAAmB,mCAAmC,CAAC;AACvD,mBAAmB,8BAA8B,CAAC;AAClD,mBAAmB,4BAA4B,CAAC;AAChD,mBAAmB,iCAAiC,CAAC;AACrD,mBAAmB,6BAA6B,CAAC;AACjD,mBAAmB,4BAA4B,CAAC;AAChD,mBAAmB,4BAA4B,CAAC;AAChD,mBAAmB,wCAAwC,CAAC"}

package/esm/mod.js

@@ -1,9 +1,10 @@
 // Base interfaces
 export * from "./src/base.js";
+export * from "./src/transports/base.js";
 // Clients
-export * from "./src/clients/event.js";
-export * from "./src/clients/public.js";
-export * from "./src/clients/wallet.js";
+export * from "./src/clients/subscription.js";
+export * from "./src/clients/info.js";
+export * from "./src/clients/exchange.js";
 // Transports
 export * from "./src/transports/http/http_transport.js";
 export * from "./src/transports/websocket/websocket_transport.js";

package/esm/src/base.d.ts

@@ -1,53 +1,7 @@
-/** Hexadecimal string starting with `0x`. */
 export type Hex = `0x${string}`;
 export type MaybePromise<T> = T | Promise<T>;
-/**
- * Interface representing a REST transport.
- * Handles communication with Hyperliquid API endpoints.
- * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint | Info endpoint}
- * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint | Exchange endpoint}
- * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests | Websocket post requests}
- */
-export interface IRequestTransport extends Partial<AsyncDisposable> {
-    /**
-     * Sends a request to the Hyperliquid API.
-     * @param endpoint - The API endpoint to send the request to.
-     * @param payload - The payload to send with the request.
-     * @param signal - An ptional abort signal.
-     * @returns A promise that resolves with parsed JSON response body.
-     */
-    request(endpoint: "info" | "exchange" | "explorer", payload: unknown, signal?: AbortSignal): Promise<unknown>;
-}
-/**
- * Interface representing an event subscription transport.
- * Handles WebSocket subscriptions for real-time updates.
- * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions | Websocket subscriptions}
- */
-export interface ISubscriptionTransport extends Partial<AsyncDisposable> {
-    /**
-     * Subscribes to a Hyperliquid event channel.
-     * @param channel - The event channel to listen to.
-     * @param payload - The payload to send with the subscription request.
-     * @param listener - The function to call when the event is dispatched.
-     * @param signal - An optional abort signal for canceling the subscription request.
-     * @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
-     */
-    subscribe(channel: string, payload: unknown, listener: (data: CustomEvent) => void, signal?: AbortSignal): Promise<Subscription>;
-}
-/** Controls event subscription lifecycle. */
-export interface Subscription {
-    /**
-     * Unsubscribes from the event and sends an unsubscribe request to the server.
-     * @param signal - An optional abort signal for canceling the unsubscribe request.
-     */
-    unsubscribe(signal?: AbortSignal): Promise<void>;
-}
-/** Base class for all Hyperliquid SDK errors. */
+/** Base error class for all SDK errors. */
 export declare class HyperliquidError extends Error {
     constructor(message?: string);
 }
-/** Base class for all transport-related errors. */
-export declare class TransportError extends HyperliquidError {
-    constructor(message?: string);
-}
 //# sourceMappingURL=base.d.ts.map

package/esm/src/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/src/base.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,MAAM,MAAM,GAAG,GAAG,KAAK,MAAM,EAAE,CAAC;AAEhC,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,WAAW,iBAAkB,SAAQ,OAAO,CAAC,eAAe,CAAC;IAC/D;;;;;;OAMG;IACH,OAAO,CACH,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,EAC1C,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAuB,SAAQ,OAAO,CAAC,eAAe,CAAC;IACpE;;;;;;;OAOG;IACH,SAAS,CACL,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,EACrC,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5B;AAED,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,iDAAiD;AACjD,qBAAa,gBAAiB,SAAQ,KAAK;gBAC3B,OAAO,CAAC,EAAE,MAAM;CAI/B;AAED,mDAAmD;AACnD,qBAAa,cAAe,SAAQ,gBAAgB;gBACpC,OAAO,CAAC,EAAE,MAAM;CAI/B"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/src/base.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG,GAAG,KAAK,MAAM,EAAE,CAAC;AAEhC,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C,2CAA2C;AAC3C,qBAAa,gBAAiB,SAAQ,KAAK;gBAC3B,OAAO,CAAC,EAAE,MAAM;CAI/B"}

package/esm/src/base.js

@@ -1,14 +1,7 @@
-/** Base class for all Hyperliquid SDK errors. */
+/** Base error class for all SDK errors. */
 export class HyperliquidError extends Error {
     constructor(message) {
         super(message);
         this.name = "HyperliquidError";
     }
 }
-/** Base class for all transport-related errors. */
-export class TransportError extends HyperliquidError {
-    constructor(message) {
-        super(message);
-        this.name = "TransportError";
-    }
-}