@nktkas/hyperliquid 0.22.1 → 0.23.0

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,10 +44,71 @@ 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 polyfills before importing the SDK:</summary>
+
+```js
+// React Native v0.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) {
+    globalThis.EventTarget = EventTarget;
+    globalThis.Event = Event;
+}
+
+if (!globalThis.CustomEvent) {
+    globalThis.CustomEvent = function (type, params) {
+        params = params || {};
+        const event = new Event(type, params);
+        event.detail = params.detail || null;
+        return event;
+    };
+}
+
+if (!AbortSignal.timeout) {
+    AbortSignal.timeout = function (delay) {
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), delay);
+        return controller.signal;
+    };
+}
+
+if (!Promise.withResolvers) {
+    Promise.withResolvers = function () {
+        let resolve, reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        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>
+
 ## Quick Start
 
 #### Info endpoint
@@ -65,12 +126,11 @@ const openOrders = await infoClient.openOrders({ user: "0x..." });
 
 ```ts
 import * as hl from "@nktkas/hyperliquid";
-import { privateKeyToAccount } from "viem/accounts"; // or other wallet libraries
 
-const wallet = privateKeyToAccount("0x...");
+const privateKey = "0x..."; // or `viem`, `ethers`
 
 const transport = new hl.HttpTransport();
-const exchClient = new hl.ExchangeClient({ wallet, transport });
+const exchClient = new hl.ExchangeClient({ wallet: privateKey, transport });
 
 const result = await exchClient.order({
     orders: [{
@@ -108,27 +168,22 @@ await sub.unsubscribe(); // unsubscribe from the event
 
 ```ts
 import * as hl from "@nktkas/hyperliquid";
-import { privateKeyToAccount } from "viem/accounts"; // or other wallet libraries
 
 const multiSignAddress = "0x...";
 const signers = [
-    privateKeyToAccount("0x..."), // first is leader
-    privateKeyToAccount("0x..."), // can be a custom async wallet
-    // ...
-    privateKeyToAccount("0x..."),
-];
+    "0x...", // Private key; or any other wallet libraries
+] 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
 
@@ -137,11 +192,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
@@ -153,7 +208,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 });
 ```
 
@@ -165,22 +220,26 @@ 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 directly
+const privateKey = "0x...";
+const exchClient_privateKey = new hl.ExchangeClient({ wallet: privateKey, transport });
 
-// 1. Using Viem with private key
+// 2. Using Viem
 const viemAccount = privateKeyToAccount("0x...");
 const exchClient_viem = new hl.ExchangeClient({ wallet: viemAccount, transport });
 
-// 2. 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 });
 
-// 3. Using external wallet (e.g. MetaMask) via Viem
+// 4. 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 exchClient_viemMetamask = new hl.ExchangeClient({ wallet: externalWallet, transport });
 
-// 4. 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 });
 ```
 
@@ -189,7 +248,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 });
 ```
 
@@ -203,8 +262,9 @@ import { ethers } from "ethers";
 const multiSignAddress = "0x...";
 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;
@@ -221,15 +281,14 @@ const signers = [
             message: Record<string, unknown>;
         }): Promise<Hex> {
             // Custom signer logic
-            return "0x..."; // return signature
+            return "0x..."; // return hex signature
         },
     },
-    // ...
-    new ethers.Wallet("0x..."),
+    "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
@@ -258,12 +317,11 @@ const openOrders = await infoClient.openOrders({ user: "0x..." });
 
 ```ts
 import * as hl from "@nktkas/hyperliquid";
-import { privateKeyToAccount } from "viem/accounts";
 
-const account = privateKeyToAccount("0x...");
+const privateKey = "0x..."; // or `viem`, `ethers`
 
 const transport = new hl.HttpTransport();
-const exchClient = new hl.ExchangeClient({ wallet: account, transport });
+const exchClient = new hl.ExchangeClient({ wallet: privateKey, transport });
 
 // Place an orders
 const result = await exchClient.order({
@@ -323,15 +381,16 @@ const sub = await subsClient.candle({ coin: "BTC", interval: "1h" }, (data) => {
 
 ```ts
 import * as hl from "@nktkas/hyperliquid";
-import { privateKeyToAccount } from "viem/accounts";
 
 const multiSignAddress = "0x...";
-const signers = [privateKeyToAccount("0x...")];
+const signers = [
+    "0x...", // Private keys
+] as const;
 
 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({
@@ -363,10 +422,7 @@ const result = await multiSignClient.withdraw3({
 });
 ```
 
-</details>
-
-<details>
-<summary><h2>API Reference</h2></summary>
+## API Reference
 
 ### Clients
 
@@ -454,6 +510,7 @@ class ExchangeClient {
     constructor(args: {
         transport: HttpTransport | WebSocketTransport;
         wallet:
+            | Hex // Private key directly
             | AbstractViemWalletClient // viem
             | AbstractEthersSigner // ethers
             | AbstractEthersV5Signer // ethers v5
@@ -491,6 +548,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>;
@@ -555,7 +613,7 @@ class SubscriptionClient {
 
     // Explorer
     explorerBlock(listener: (data: WsBlockDetails[]) => void): Promise<Subscription>;
-    explorerTx(listener: (data: TxDetails[]) => void): Promise<Subscription>;
+    explorerTxs(listener: (data: TxDetails[]) => void): Promise<Subscription>;
 }
 ```
 <!-- deno-fmt-ignore-end -->
@@ -576,16 +634,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?: {
@@ -604,6 +664,8 @@ class HttpTransport {
 
 #### WebSocket Transport
 
+WebSocket transport has better network latency than HTTP transport.
+
 ```ts
 class WebSocketTransport {
     constructor(options?: {
@@ -627,10 +689,7 @@ class WebSocketTransport {
 }
 ```
 
-</details>
-
-<details>
-<summary><h2>Additional Import Points</h2></summary>
+## Additional Import Points
 
 ### `/types`
 
@@ -647,26 +706,25 @@ The import point gives access to functions that generate signatures for Hyperliq
 
 ```ts
 import { actionSorter, signL1Action } from "@nktkas/hyperliquid/signing";
-import { privateKeyToAccount } from "viem/accounts"; // or other wallet libraries
 
-const wallet = privateKeyToAccount("0x...");
+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,
-    action: actionSorter[action.type](action), // key order affects signature
+    wallet: privateKey,
+    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 }),
@@ -678,27 +736,26 @@ const body = await response.json();
 
 ```ts
 import { signUserSignedAction, userSignedActionEip712Types } from "@nktkas/hyperliquid/signing";
-import { privateKeyToAccount } from "viem/accounts"; // or other wallet libraries
 
-const wallet = privateKeyToAccount("0x...");
+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,
+    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 }),
@@ -706,8 +763,6 @@ const response = await fetch("https://api.hyperliquid-testnet.xyz/exchange", {
 const body = await response.json();
 ```
 
-</details>
-
 ## Contributing
 
 We appreciate your help! To contribute, please read the [contributing instructions](CONTRIBUTING.md).

package/esm/mod.d.ts

@@ -1,6 +1,6 @@
 export * from "./src/base.js";
 export * from "./src/transports/base.js";
-export type { AbstractEthersSigner, AbstractEthersV5Signer, AbstractViemWalletClient, AbstractWindowEthereum, } from "./src/signing.js";
+export type { AbstractEthersSigner, AbstractEthersV5Signer, AbstractViemWalletClient, AbstractWindowEthereum, } from "./src/signing/mod.js";
 export * from "./src/clients/exchange.js";
 export * from "./src/clients/info.js";
 export * from "./src/clients/multiSign.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,kBAAkB,CAAC;AAG1B,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,iCAAiC,CAAC;AACrD,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";
     }
 }