@nktkas/hyperliquid 0.16.0 → 0.17.0

package/README.md

@@ -11,12 +11,11 @@ runtimes, written in TypeScript and provided with tests.
 ## Features
 
 - 🖋️ **Typed**: Source code is 100% TypeScript.
-- 🧪 **Tested**: Good code coverage and type testing.
-- 📦 **Minimal dependencies**: Few small dependencies, standard JS is favored.
-- 🌐 **Cross-Environment Support**: Compatible with all major JS runtimes, including Node.js, Deno, Bun, and browser
-  environments.
+- 🧪 **Tested**: Good code coverage and guarantee of type validity.
+- 📦 **Minimal dependencies**: A few small trusted dependencies.
+- 🌐 **Cross-Environment Support**: Compatible with all major JS runtimes.
 - 🔧 **Integratable**: Easy to use with [viem](https://github.com/wevm/viem),
-  [ethers](https://github.com/ethers-io/ethers.js) and web3 wallets.
+  [ethers](https://github.com/ethers-io/ethers.js) and other wallet libraries.
 - 📚 **Documented**: Comprehensive documentation and usage examples, provided directly in JSDoc annotations within the
   source code.
 
@@ -26,7 +25,7 @@ runtimes, written in TypeScript and provided with tests.
 # npm
 npm i @nktkas/hyperliquid
 
-# yarn 
+# yarn
 yarn add @nktkas/hyperliquid
 
 # pnpm
@@ -44,7 +43,7 @@ import * as hl from "https://esm.sh/jsr/@nktkas/hyperliquid"
 
 ## Usage
 
-### Initialize Transport
+### 1) Initialize Transport
 
 First, choose and configure your transport layer (more details in the [API Reference](#transports)):
 
@@ -52,13 +51,13 @@ First, choose and configure your transport layer (more details in the [API Refer
 import * as hl from "@nktkas/hyperliquid"; // ESM & Common.js
 
 // HTTP Transport
-const httpTransport = new hl.HttpTransport(); // Accepts optional parameters (e.g. url, timeout, fetchOptions)
+const httpTransport = new hl.HttpTransport(); // Accepts optional parameters
 
-// or WebSocket Transport
-const wsTransport = new hl.WebSocketTransport(); // Accepts optional parameters (e.g. url, timeout, keepAlive, reconnect)
+// WebSocket Transport
+const wsTransport = new hl.WebSocketTransport(); // Accepts optional parameters
 ```
 
-### Initialize Client
+### 2) Initialize Client
 
 Next, initialize a client with the transport layer (more details in the [API Reference](#clients)):
 
@@ -103,11 +102,11 @@ const windowMetamaskClient = new hl.WalletClient({ wallet: window.ethereum, tran
 ```typescript
 import * as hl from "@nktkas/hyperliquid"; // ESM & Common.js
 
-const transport = new hl.WebSocketTransport(); // Only WebSocketTransport is supported
+const transport = new hl.WebSocketTransport(); // Only WebSocketTransport
 const client = new hl.EventClient({ transport });
 ```
 
-### Use Client
+### 3) Use Client
 
 Finally, use client methods to interact with the Hyperliquid API (more details in the [API Reference](#clients)):
 
@@ -178,33 +177,29 @@ const transport = new hl.WebSocketTransport();
 const client = new hl.EventClient({ transport });
 
 // L2 Book updates
-// Promise is resolved when the subscription is set up
 const sub = await client.l2Book({ coin: "BTC" }, (data) => {
     console.log(data);
 });
-// Later, you can unsubscribe from receiving events
-await sub.unsubscribe();
+await sub.unsubscribe(); // Unsubscribe from the event
 
 // User fills
 const sub = await client.userFills({ user: "0x..." }, (data) => {
     console.log(data);
 });
-await sub.unsubscribe();
+await sub.unsubscribe(); // Unsubscribe from the event
 
 // Explorer block updates
 const sub = await client.explorerBlock((data) => {
     console.log(data);
 });
-await sub.unsubscribe();
+await sub.unsubscribe(); // Unsubscribe from the event
 ```
 
 ## API Reference
 
 ### Clients
 
-A **Client** provides access to the Hyperliquid API endpoints.
-
-There are three types of **Clients** in the sdk:
+A Client provides access to the Hyperliquid API endpoints.
 
 #### Public Client
 
@@ -289,10 +284,8 @@ A Wallet Client which provides access to
 and `withdraw3`.
 
 The Wallet Client class sets up with a given [Transport](#transports) and a wallet instance, which can be a
-[Viem Wallet](https://viem.sh/docs/clients/wallet) or an
-[Ethers Wallet](https://docs.ethers.org/v6/api/providers/#Signer).
-
-> NOTE: When using a web3 wallet, the wallet network must be set to 1337 for proper generation of L1 transactions.
+[viem](https://viem.sh/docs/clients/wallet), [ethers.js](https://docs.ethers.org/v6/api/providers/#Signer) or other
+wallet libraries.
 
 ```typescript
 class WalletClient {
@@ -300,13 +293,14 @@ class WalletClient {
         transport: HttpTransport | WebSocketTransport;
         wallet:
             | AbstractViemWalletClient // viem
-            | AbstractExtendedViemWalletClient // extended viem (e.g. privy)
             | AbstractEthersSigner // ethers
             | AbstractEthersV5Signer // ethers v5
+            | AbstractExtendedViemWalletClient // privy
             | AbstractWindowEthereum; // window.ethereum (EIP-1193) directly
-        isTestnet?: boolean; // Whether to use testnet API (default: false)
+        isTestnet?: boolean; // Whether to use testnet (default: false)
         defaultVaultAddress?: Hex; // Vault address used by default if not provided in method call
-        signatureChainId?: Hex; // Chain ID used for signing (default: trying to guess based on wallet and isTestnet)
+        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
@@ -324,9 +318,10 @@ class WalletClient {
     // Account
     approveAgent(args: ApproveAgentParameters): Promise<SuccessResponse>;
     approveBuilderFee(args: ApproveBuilderFeeParameters): Promise<SuccessResponse>;
-    claimRewards(args: ClaimRewardsParameters): Promise<SuccessResponse>;
+    claimRewards(): Promise<SuccessResponse>;
     createSubAccount(args: CreateSubAccountParameters): Promise<CreateSubAccountResponse>;
     evmUserModify(args: EvmUserModifyParameters): Promise<SuccessResponse>;
+    reserveRequestWeight(args: ReserveRequestWeightParameters): Promise<SuccessResponse>;
     setDisplayName(args: SetDisplayNameParameters): Promise<SuccessResponse>;
     setReferrer(args: SetReferrerParameters): Promise<SuccessResponse>;
     spotUser(args: SpotUserParameters): Promise<SuccessResponse>;
@@ -400,10 +395,10 @@ class EventClient {
 
 ### Transports
 
-A [Client](#clients) is instantiated with a **Transport**, which is the intermediary layer that is responsible for
-executing outgoing requests (ie. API calls and event listeners).
+A [Client](#clients) is instantiated with a Transport, which is the intermediary layer that is responsible for executing
+outgoing requests (ie. API calls and event listeners).
 
-There are two types of **Transports** in the sdk:
+There are two types of Transports in the sdk:
 
 #### HTTP Transport
 
@@ -413,7 +408,7 @@ API.
 ```typescript
 class HttpTransport {
     constructor(options?: {
-        url?: string | URL; // Base URL for API endpoints (default: "https://hyperliquid.xyz")
+        isTestnet?: boolean; // Whether to use testnet url (default: false)
         timeout?: number; // Request timeout in ms (default: 10_000)
         fetchOptions?: RequestInit; // A custom fetch options
         onRequest?: (request: Request) => MaybePromise<Request | void | null | undefined>; // A callback before request is sent
@@ -482,70 +477,50 @@ Useful if you want to sign a Hyperliquid transaction yourself.
 
 ```typescript
 import { signL1Action } from "@nktkas/hyperliquid/signing";
-import type { CancelRequest, CancelResponse } from "@nktkas/hyperliquid/types";
 import { privateKeyToAccount } from "viem/accounts";
 
-// —————————— Prepare ——————————
-
 const wallet = privateKeyToAccount("0x..."); // Change to your private key
 
-// The CancelRequest["action"] type ensures that we collect the correct cancel request action
-const action: CancelRequest["action"] = {
+const action = {
     type: "cancel",
     cancels: [
-        { a: 0, o: 12345 },
+        { a: 0, o: 12345 }, // Asset index and order ID
     ],
 };
 const nonce = Date.now();
 
-// —————————— Signing ——————————
-
-const signature = await signL1Action({ wallet, action, nonce, isTestnet: true });
-
-// —————————— Request ——————————
-
-// The CancelRequest type guarantees us that the object we want to send is valid in terms of types
-const request: CancelRequest = { action, signature, nonce };
+const signature = await signL1Action({
+    wallet,
+    action,
+    nonce,
+    isTestnet: true, // Change to false for mainnet
+});
 
 const response = await fetch("https://api.hyperliquid-testnet.xyz/exchange", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(request),
+    body: JSON.stringify({ action, signature, nonce }),
 });
-
-if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`Failed to cancel order: ${response.statusText} ${body}`);
-}
-
-// If we sent a cancel request and received a successful response, then we got exactly the CancelResponse type
-const body = await response.json() as CancelResponse;
-console.log("Order cancel response:", body);
+const body = await response.json();
 ```
 
 #### Approve an agent without a client
 
 ```typescript
 import { signUserSignedAction } from "@nktkas/hyperliquid/signing";
-import type { ApproveAgentRequest, ErrorResponse, SuccessResponse } from "@nktkas/hyperliquid/types";
 import { privateKeyToAccount } from "viem/accounts";
 
-// —————————— Prepare ——————————
-
 const wallet = privateKeyToAccount("0x..."); // Change to your private key
 
-// The ApproveAgentRequest["action"] type ensures that we collect the correct approve agent request action
-const action: ApproveAgentRequest["action"] = {
+const action = {
     type: "approveAgent",
-    hyperliquidChain: "Testnet",
+    hyperliquidChain: "Testnet", // "Mainnet" or "Testnet"
     signatureChainId: "0x66eee",
     nonce: Date.now(),
-    agentAddress: "0x...", // Change to the agent address you want to approve
-    agentName: "TempAgent",
+    agentAddress: "0x...", // Change to your agent address
+    agentName: "Agent",
 };
 
-// —————————— Signing ——————————
-
 const signature = await signUserSignedAction({
     wallet,
     action,
@@ -560,33 +535,10 @@ const signature = await signUserSignedAction({
     chainId: parseInt(action.signatureChainId, 16),
 });
 
-// —————————— Request ——————————
-
-// The ApproveAgentRequest type guarantees us that the object we want to send is valid in terms of types
-const request: ApproveAgentRequest = { action, signature, nonce: action.nonce };
-
 const response = await fetch("https://api.hyperliquid-testnet.xyz/exchange", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(request),
+    body: JSON.stringify({ action, signature, nonce: action.nonce }),
 });
-
-if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`Failed to approve agent: ${response.statusText} ${body}`);
-}
-
-// If we sent a request for agent approval and received a successful response,
-// we will get either a SuccessResponse type or an ErrorResponse type
-const body = await response.json() as SuccessResponse | ErrorResponse;
-console.log("Agent approval response:", body);
+const body = await response.json();
 ```
-
-## Contributing
-
-Contributions are welcome! Please see the [CONTRIBUTING](./CONTRIBUTING.md) file for guidelines on how to contribute to
-this project.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.