@nktkas/hyperliquid 0.22.2 → 0.23.1

package/README.md

@@ -1,9 +1,9 @@
 # Hyperliquid API TypeScript SDK
 
-[![NPM](https://img.shields.io/npm/v/@nktkas/hyperliquid?style=flat-square&color=blue)](https://www.npmjs.com/package/@nktkas/hyperliquid)
-[![JSR](https://img.shields.io/jsr/v/@nktkas/hyperliquid?style=flat-square&color=blue)](https://jsr.io/@nktkas/hyperliquid)
-[![Coveralls](https://img.shields.io/coverallsCoverage/github/nktkas/hyperliquid?style=flat-square)](https://coveralls.io/github/nktkas/hyperliquid)
-[![bundlejs](https://img.shields.io/bundlejs/size/@nktkas/hyperliquid?style=flat-square)](https://bundlejs.com/?q=@nktkas/hyperliquid)
+[![npm](https://img.shields.io/npm/v/@nktkas/hyperliquid?style=flat-square&color=blue)](https://www.npmjs.com/package/@nktkas/hyperliquid)
+[![jsr](https://img.shields.io/jsr/v/@nktkas/hyperliquid?style=flat-square&color=blue)](https://jsr.io/@nktkas/hyperliquid)
+[![coveralls](https://img.shields.io/coverallsCoverage/github/nktkas/hyperliquid?style=flat-square)](https://coveralls.io/github/nktkas/hyperliquid)
+[![bundlephobia](https://img.shields.io/bundlephobia/minzip/@nktkas/hyperliquid?style=flat-square)](https://bundlephobia.com/package/@nktkas/hyperliquid)
 
 Unofficial [Hyperliquid API](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api) SDK for all major JS
 runtimes, written in TypeScript and provided with tests.
@@ -44,17 +44,19 @@ deno add jsr:@nktkas/hyperliquid
 ```html
 <script type="module">
     import * as hl from "https://esm.sh/jsr/@nktkas/hyperliquid";
-    // Use hl.InfoClient, hl.ExchangeClient, etc.
 </script>
 ```
 
 ### React Native
 
 <details>
-<summary>For React Native, you need to import several polyfills before importing the SDK:</summary>
+<summary>For React Native, you need to import polyfills before importing the SDK:</summary>
 
 ```js
-// React Native 0.76.3
+// React Native 0.76.3 / Expo v52
+// Issues:
+// - signing: does not support private keys directly, use viem or ethers
+
 import { Event, EventTarget } from "event-target-shim";
 
 if (!globalThis.EventTarget || !globalThis.Event) {
@@ -89,21 +91,6 @@ if (!Promise.withResolvers) {
         return { promise, resolve, reject };
     };
 }
-
-if (!ArrayBuffer.prototype.transfer) {
-    ArrayBuffer.prototype.transfer = function (newByteLength) {
-        const length = newByteLength ?? this.byteLength;
-        const newBuffer = new ArrayBuffer(length);
-        const oldView = new Uint8Array(this);
-        const newView = new Uint8Array(newBuffer);
-
-        newView.set(oldView.subarray(0, Math.min(oldView.length, length)));
-
-        Object.defineProperty(this, "byteLength", { value: 0 });
-
-        return newBuffer;
-    };
-}
 ```
 
 </details>
@@ -174,16 +161,15 @@ const signers = [
 ] as const;
 
 const transport = new hl.HttpTransport();
-const multiSignClient = new hl.MultiSignClient({ transport, multiSignAddress, signers }); // extends ExchangeClient
+const multiSignClient = new hl.MultiSignClient({ transport, multiSignAddress, signers }); // extends `ExchangeClient`
 
-const data = await multiSignClient.approveAgent({ // same API as ExchangeClient
+const data = await multiSignClient.approveAgent({ // same API as `ExchangeClient`
     agentAddress: "0x...",
     agentName: "agentName",
 });
 ```
 
-<details>
-<summary><h2>Usage</h2></summary>
+## Usage
 
 ### 1) Initialize Transport
 
@@ -192,11 +178,11 @@ First, choose and configure your transport layer (more details in the [API Refer
 ```ts
 import * as hl from "@nktkas/hyperliquid";
 
-// HTTP Transport
-const httpTransport = new hl.HttpTransport(); // Accepts optional parameters
+// 1. HTTP Transport: suitable for one-time requests or serverless environments
+const httpTransport = new hl.HttpTransport(); // Accepts optional parameters (e.g. isTestnet, timeout, etc.)
 
-// WebSocket Transport
-const wsTransport = new hl.WebSocketTransport(); // Accepts optional parameters
+// 2. WebSocket Transport: has better network latency than HTTP transport
+const wsTransport = new hl.WebSocketTransport(); // Accepts optional parameters (e.g. url, timeout, reconnect, etc.)
 ```
 
 ### 2) Initialize Client
@@ -208,7 +194,7 @@ Next, initialize a client with the transport layer (more details in the [API Ref
 ```ts
 import * as hl from "@nktkas/hyperliquid";
 
-const transport = new hl.HttpTransport(); // or WebSocketTransport
+const transport = new hl.HttpTransport(); // or `WebSocketTransport`
 const infoClient = new hl.InfoClient({ transport });
 ```
 
@@ -220,17 +206,17 @@ import { createWalletClient, custom } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { ethers } from "ethers";
 
-const transport = new hl.HttpTransport(); // or WebSocketTransport
+const transport = new hl.HttpTransport(); // or `WebSocketTransport`
 
-// 1. Using private key
+// 1. Using private key directly
 const privateKey = "0x...";
 const exchClient_privateKey = new hl.ExchangeClient({ wallet: privateKey, transport });
 
-// 2. Using Viem with private key
+// 2. Using Viem
 const viemAccount = privateKeyToAccount("0x...");
 const exchClient_viem = new hl.ExchangeClient({ wallet: viemAccount, transport });
 
-// 3. Using Ethers (or Ethers V5) with private key
+// 3. Using Ethers (or Ethers V5)
 const ethersWallet = new ethers.Wallet("0x...");
 const exchClient_ethers = new hl.ExchangeClient({ wallet: ethersWallet, transport });
 
@@ -239,7 +225,7 @@ const [account] = await window.ethereum.request({ method: "eth_requestAccounts"
 const externalWallet = createWalletClient({ account, transport: custom(window.ethereum) });
 const exchClient_viemMetamask = new hl.ExchangeClient({ wallet: externalWallet, transport });
 
-// 5. Using external wallet (e.g. MetaMask) via `window.ethereum` (EIP-1193)
+// 5. Using external wallet (e.g. MetaMask) via `window.ethereum`
 const exchClient_windowMetamask = new hl.ExchangeClient({ wallet: window.ethereum, transport });
 ```
 
@@ -248,7 +234,7 @@ const exchClient_windowMetamask = new hl.ExchangeClient({ wallet: window.ethereu
 ```ts
 import * as hl from "@nktkas/hyperliquid";
 
-const transport = new hl.WebSocketTransport(); // only WebSocketTransport
+const transport = new hl.WebSocketTransport(); // only `WebSocketTransport`
 const subsClient = new hl.SubscriptionClient({ transport });
 ```
 
@@ -264,7 +250,7 @@ const signers = [
     privateKeyToAccount("0x..."), // first is leader for multi-sign transaction, must contain own address
     new ethers.Wallet("0x..."),
     { // can be a custom async wallet
-        signTypedData(params: {
+        async signTypedData(params: {
             domain: {
                 name: string;
                 version: string;
@@ -281,14 +267,14 @@ const signers = [
             message: Record<string, unknown>;
         }): Promise<Hex> {
             // Custom signer logic
-            return "0x..."; // return signature
+            return "0x..."; // return hex signature
         },
     },
     "0x...", // private key directly
 ];
 
 const transport = new hl.HttpTransport();
-const multiSignClient = new hl.MultiSignClient({ transport, multiSignAddress, signers }); // extends ExchangeClient
+const multiSignClient = new hl.MultiSignClient({ transport, multiSignAddress, signers }); // extends `ExchangeClient`
 ```
 
 ### 3) Use Client
@@ -390,7 +376,7 @@ const signers = [
 const transport = new hl.HttpTransport();
 const multiSignClient = new hl.MultiSignClient({ transport, multiSignAddress, signers });
 
-// Interaction is the same as with ExchangeClient
+// Interaction is the same as with `ExchangeClient`
 
 // Place an orders
 const result = await multiSignClient.order({
@@ -422,10 +408,7 @@ const result = await multiSignClient.withdraw3({
 });
 ```
 
-</details>
-
-<details>
-<summary><h2>API Reference</h2></summary>
+## API Reference
 
 ### Clients
 
@@ -447,6 +430,9 @@ class InfoClient {
     candleSnapshot(args: CandleSnapshotParameters): Promise<Candle[]>;
     fundingHistory(args: FundingHistoryParameters): Promise<FundingHistory[]>;
     l2Book(args: L2BookParameters): Promise<Book>;
+    liquidatable(): Promise<unknown[]>;
+    marginTable(args: MarginTableParameters): Promise<MarginTable>;
+    maxMarketOrderNtls(): Promise<[number, string][]>;
     meta(): Promise<PerpsMeta>;
     metaAndAssetCtxs(): Promise<PerpsMetaAndAssetCtxs>;
     perpDeployAuctionStatus(): Promise<DeployAuctionStatus>;
@@ -487,18 +473,23 @@ class InfoClient {
     userTwapSliceFills(args: UserTwapSliceFillsParameters): Promise<TwapSliceFill[]>;
     userTwapSliceFillsByTime(args: UserTwapSliceFillsByTimeParameters): Promise<TwapSliceFill[]>;
 
-    // Staking
+    // Validator
     delegations(args: DelegationsParameters): Promise<Delegation[]>;
     delegatorHistory(args: DelegatorHistoryParameters): Promise<DelegatorUpdate[]>;
     delegatorRewards(args: DelegatorRewardsParameters): Promise<DelegatorReward[]>;
     delegatorSummary(args: DelegatorSummaryParameters): Promise<DelegatorSummary>;
+    validatorL1Votes(): Promise<unknown[]>;
     validatorSummaries(): Promise<ValidatorSummary[]>;
 
     // Vault
+    leadingVaults(args: LeadingVaultsParameters): Promise<VaultLeading[]>;
     userVaultEquities(args: UserVaultEquitiesParameters): Promise<VaultEquity[]>;
     vaultDetails(args: VaultDetailsParameters): Promise<VaultDetails | null>;
     vaultSummaries(): Promise<VaultSummary[]>;
 
+    // Server
+    exchangeStatus(): Promise<ExchangeStatus>;
+
     // Explorer (RPC endpoint)
     blockDetails(args: BlockDetailsParameters): Promise<BlockDetails>;
     txDetails(args: TxDetailsParameters): Promise<TxDetails>;
@@ -513,14 +504,15 @@ class ExchangeClient {
     constructor(args: {
         transport: HttpTransport | WebSocketTransport;
         wallet:
+            | Hex // Private key directly
             | AbstractViemWalletClient // viem
             | AbstractEthersSigner // ethers
             | AbstractEthersV5Signer // ethers v5
             | AbstractWindowEthereum; // window.ethereum (EIP-1193)
         isTestnet?: boolean; // Whether to use testnet (default: false)
         defaultVaultAddress?: Hex; // Vault address used by default if not provided in method call
-        signatureChainId?: Hex | (() => MaybePromise<Hex>); // Chain ID used for signing (default: trying to guess based on wallet and isTestnet)
-        nonceManager?: () => MaybePromise<number>; // Function to get the next nonce (default: auto-incrementing Date.now())
+        signatureChainId?: Hex | (() => MaybePromise<Hex>); // Chain ID used for signing (default: trying to guess based on wallet and `isTestnet`)
+        nonceManager?: () => MaybePromise<number>; // Function to get the next nonce (default: auto-incrementing `Date.now()`)
     });
 
     // Order
@@ -539,7 +531,6 @@ class ExchangeClient {
     approveAgent(args: ApproveAgentParameters): Promise<SuccessResponse>;
     approveBuilderFee(args: ApproveBuilderFeeParameters): Promise<SuccessResponse>;
     claimRewards(): Promise<SuccessResponse>;
-    convertToMultiSigUser(args: ConvertToMultiSigUserParameters): Promise<SuccessResponse>;
     createSubAccount(args: CreateSubAccountParameters): Promise<CreateSubAccountResponse>;
     evmUserModify(args: EvmUserModifyParameters): Promise<SuccessResponse>;
     registerReferrer(args: RegisterReferrerParameters): Promise<SuccessResponse>;
@@ -550,6 +541,7 @@ class ExchangeClient {
 
     // Transfer
     perpDexClassTransfer(args: PerpDexClassTransferParameters): Promise<SuccessResponse>;
+    perpDexTransfer(args: PerpDexTransferParameters): Promise<SuccessResponse>;
     spotSend(args: SpotSendParameters): Promise<SuccessResponse>;
     subAccountSpotTransfer(args: SubAccountSpotTransferParameters): Promise<SuccessResponse>;
     subAccountTransfer(args: SubAccountTransferParameters): Promise<SuccessResponse>;
@@ -573,6 +565,7 @@ class ExchangeClient {
     vaultTransfer(args: VaultTransferParameters): Promise<SuccessResponse>;
 
     // Multi-Sign
+    convertToMultiSigUser(args: ConvertToMultiSigUserParameters): Promise<SuccessResponse>;
     multiSig(args: MultiSigParameters): Promise<BaseExchangeResponse>;
 
     // Validator
@@ -635,16 +628,18 @@ class MultiSignClient extends ExchangeClient {
             },
     );
 
-    // Same methods as ExchangeClient
+    // Same methods as `ExchangeClient`
 }
 ```
 
 ### Transports
 
-Transport acts as a layer between the class and Hyperliquid servers.
+Transport acts as a layer between class requests and Hyperliquid servers.
 
 #### HTTP Transport
 
+HTTP transport is suitable for one-off requests or serverless environments.
+
 ```ts
 class HttpTransport {
     constructor(options?: {
@@ -663,6 +658,8 @@ class HttpTransport {
 
 #### WebSocket Transport
 
+WebSocket transport has better network latency than HTTP transport.
+
 ```ts
 class WebSocketTransport {
     constructor(options?: {
@@ -686,10 +683,7 @@ class WebSocketTransport {
 }
 ```
 
-</details>
-
-<details>
-<summary><h2>Additional Import Points</h2></summary>
+## Additional Import Points
 
 ### `/types`
 
@@ -709,22 +703,22 @@ import { actionSorter, signL1Action } from "@nktkas/hyperliquid/signing";
 
 const privateKey = "0x..."; // or `viem`, `ethers`
 
+const nonce = Date.now();
 const action = {
     type: "cancel",
     cancels: [
         { a: 0, o: 12345 },
     ],
-};
-const nonce = Date.now();
+} as const;
 
 const signature = await signL1Action({
     wallet: privateKey,
-    action: actionSorter[action.type](action), // key order affects signature
+    action: actionSorter[action.type](action),
     nonce,
-    isTestnet: true, // change to `false` for mainnet
 });
 
-const response = await fetch("https://api.hyperliquid-testnet.xyz/exchange", {
+// Send the signed action to the Hyperliquid API
+const response = await fetch("https://api.hyperliquid.xyz/exchange", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ action, signature, nonce }),
@@ -741,21 +735,21 @@ const privateKey = "0x..."; // or `viem`, `ethers`
 
 const action = {
     type: "approveAgent",
-    signatureChainId: "0x66eee", // must match the current wallet network
-    hyperliquidChain: "Testnet", // Mainnet | Testnet
+    signatureChainId: "0x66eee",
+    hyperliquidChain: "Mainnet",
     agentAddress: "0x...",
     agentName: "Agent",
     nonce: Date.now(),
-};
+} as const;
 
 const signature = await signUserSignedAction({
     wallet: privateKey,
     action,
-    types: userSignedActionEip712Types[action.type], // key order affects signature
-    chainId: parseInt(action.signatureChainId, 16),
+    types: userSignedActionEip712Types[action.type],
 });
 
-const response = await fetch("https://api.hyperliquid-testnet.xyz/exchange", {
+// Send the signed action to the Hyperliquid API
+const response = await fetch("https://api.hyperliquid.xyz/exchange", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ action, signature, nonce: action.nonce }),
@@ -763,7 +757,25 @@ const response = await fetch("https://api.hyperliquid-testnet.xyz/exchange", {
 const body = await response.json();
 ```
 
-</details>
+## FAQ
+
+### How to execute an L1 action via an external wallet (e.g. MetaMask)?
+
+Hyperliquid requires chain `1337` for L1 actions (open order, change leverage, etc.). There are two ways to execute an
+L1 action through an external wallet:
+
+- (recommended) Create an
+  [Agent Wallet](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets#api-wallets)
+  and execute all L1 actions through it
+- Change the user's chain to `1337`, however, the user will sign unreadable data
+
+### How to create a market order?
+
+Hyperliquid doesn't have traditional market orders, but you can achieve market-like execution by placing limit orders
+with `tif: "Ioc"` and prices that guarantee immediate execution:
+
+- For buys: set limit price >= current best ask
+- For sells: set limit price <= current best bid
 
 ## Contributing
 

package/esm/mod.d.ts

@@ -11,7 +11,7 @@ export type * from "./src/types/exchange/responses.js";
 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/validators.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";

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;AAC9B,cAAc,0BAA0B,CAAC;AAGzC,YAAY,EACR,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,GACzB,MAAM,sBAAsB,CAAC;AAG9B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAG9C,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"}
+{"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,wBAAwB,EACxB,sBAAsB,GACzB,MAAM,sBAAsB,CAAC;AAG9B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAG9C,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,gCAAgC,CAAC;AACpD,mBAAmB,6BAA6B,CAAC;AACjD,mBAAmB,4BAA4B,CAAC;AAChD,mBAAmB,4BAA4B,CAAC;AAChD,mBAAmB,wCAAwC,CAAC"}

package/esm/src/base.d.ts

@@ -1,7 +1,10 @@
 export type Hex = `0x${string}`;
 export type MaybePromise<T> = T | Promise<T>;
+export type DeepImmutable<T> = {
+    readonly [K in keyof T]: DeepImmutable<T[K]>;
+};
 /** Base error class for all SDK errors. */
 export declare class HyperliquidError extends Error {
-    constructor(message?: string);
+    constructor(message?: string, options?: ErrorOptions);
 }
 //# 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,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"}
+{"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;AAG7C,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC3B,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/C,CAAC;AAEF,2CAA2C;AAC3C,qBAAa,gBAAiB,SAAQ,KAAK;gBAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIvD"}

package/esm/src/base.js

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