@nktkas/hyperliquid 0.28.0 → 0.29.0

package/src/src/api/exchange/_methods/_base/execute.ts

@@ -24,9 +24,15 @@ type MaybePromise<T> = T | Promise<T>;
 // deno-lint-ignore ban-types
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
 
+/** Options for any execute functions. */
+interface BaseOptions {
+  /** [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to cancel a request. */
+  signal?: AbortSignal;
+}
+
 /** Extract request options from a request type (excludes action, nonce, signature). */
 export type ExtractRequestOptions<T extends { action: Record<string, unknown> }> = Prettify<
-  & { signal?: AbortSignal }
+  & BaseOptions
   & Omit<T, "action" | "nonce" | "signature">
 >;
 
@@ -75,7 +81,7 @@ export interface ExchangeMultiSigConfig<
   T extends HttpTransport | WebSocketTransport = HttpTransport | WebSocketTransport,
 > extends BaseConfig<T> {
   /** Array of wallets for multi-sig. First wallet is the leader. */
-  wallet: readonly [AbstractWallet, ...AbstractWallet[]];
+  signers: readonly [AbstractWallet, ...AbstractWallet[]];
   /** The multi-signature account address. */
   multiSigUser: `0x${string}`;
 }
@@ -124,9 +130,8 @@ export async function executeL1Action<T>(
     const signal = options?.signal;
 
     // Sign action (multi-sig or single wallet)
-    const [finalAction, signature] = isMultiSig(config)
-      ? await signMultiSigL1(config, action, walletAddress, nonce, vaultAddress, expiresAfter)
-      : [
+    const [finalAction, signature] = "wallet" in config
+      ? [
         action,
         await signL1Action({
           wallet: leader,
@@ -136,7 +141,8 @@ export async function executeL1Action<T>(
           vaultAddress,
           expiresAfter,
         }),
-      ];
+      ]
+      : await signMultiSigL1(config, action, walletAddress, nonce, vaultAddress, expiresAfter);
 
     // Send request and validate response
     const response = await transport.request("exchange", {
@@ -200,9 +206,9 @@ export async function executeUserSignedAction<T>(
     };
 
     // Sign action (multi-sig or single wallet)
-    const [finalAction, signature] = isMultiSig(config)
-      ? await signMultiSigUserSigned(config, fullAction, types, walletAddress, nonce)
-      : [fullAction, await signUserSignedAction({ wallet: leader, action: fullAction, types })];
+    const [finalAction, signature] = "wallet" in config
+      ? [fullAction, await signUserSignedAction({ wallet: leader, action: fullAction, types })]
+      : await signMultiSigUserSigned(config, fullAction, types, walletAddress, nonce);
 
     // Send request and validate response
     const response = await transport.request("exchange", {
@@ -216,7 +222,7 @@ export async function executeUserSignedAction<T>(
 }
 
 // =============================================================
-// Multi-sig signing (private)
+// Multi-sig signing
 // =============================================================
 
 /** Remove leading zeros from signature components (required by Hyperliquid). */
@@ -237,7 +243,7 @@ async function signMultiSigL1(
   vaultAddress?: `0x${string}`,
   expiresAfter?: number,
 ): Promise<[Record<string, unknown>, Signature]> {
-  const { transport: { isTestnet }, wallet: signers, multiSigUser } = config;
+  const { transport: { isTestnet }, signers, multiSigUser } = config;
   const multiSigUser_ = v.parse(Address, multiSigUser);
   const outerSigner_ = v.parse(Address, outerSigner);
 
@@ -259,7 +265,11 @@ async function signMultiSigL1(
     type: "multiSig",
     signatureChainId: await getSignatureChainId(config),
     signatures,
-    payload: { multiSigUser: multiSigUser_, outerSigner: outerSigner_, action },
+    payload: {
+      multiSigUser: multiSigUser_,
+      outerSigner: outerSigner_,
+      action,
+    },
   };
 
   // Sign the wrapper with the leader
@@ -283,7 +293,7 @@ async function signMultiSigUserSigned(
   outerSigner: `0x${string}`,
   nonce: number,
 ): Promise<[Record<string, unknown>, Signature]> {
-  const { wallet: signers, multiSigUser, transport: { isTestnet } } = config;
+  const { signers, multiSigUser, transport: { isTestnet } } = config;
   const multiSigUser_ = v.parse(Address, multiSigUser);
   const outerSigner_ = v.parse(Address, outerSigner);
 
@@ -291,7 +301,11 @@ async function signMultiSigUserSigned(
   const signatures = await Promise.all(signers.map(async (signer) => {
     const signature = await signUserSignedAction({
       wallet: signer,
-      action: { payloadMultiSigUser: multiSigUser_, outerSigner: outerSigner_, ...action },
+      action: {
+        payloadMultiSigUser: multiSigUser_,
+        outerSigner: outerSigner_,
+        ...action,
+      },
       types,
     });
     return trimSignature(signature);
@@ -302,7 +316,11 @@ async function signMultiSigUserSigned(
     type: "multiSig",
     signatureChainId: await getSignatureChainId(config),
     signatures,
-    payload: { multiSigUser: multiSigUser_, outerSigner: outerSigner_, action },
+    payload: {
+      multiSigUser: multiSigUser_,
+      outerSigner: outerSigner_,
+      action,
+    },
   };
 
   // Sign the wrapper with the leader
@@ -317,17 +335,12 @@ async function signMultiSigUserSigned(
 }
 
 // =============================================================
-// Helpers (private)
+// Helpers
 // =============================================================
 
-/** Type guard for multi-sig configuration. */
-function isMultiSig(config: ExchangeConfig): config is ExchangeMultiSigConfig {
-  return Array.isArray(config.wallet);
-}
-
-/** Get the leader wallet (first signer for multi-sig, or the single wallet). */
+/** Get the leader wallet (first signer for the single wallet, or multi-sig). */
 function getLeader(config: ExchangeConfig): AbstractWallet {
-  return isMultiSig(config) ? config.wallet[0] : config.wallet;
+  return "wallet" in config ? config.wallet : config.signers[0];
 }
 
 /** Resolve signature chain ID from config or wallet. */

package/src/src/api/exchange/client.ts

@@ -1,4 +1,4 @@
-import type { ExchangeConfig } from "./_methods/_base/execute.js";
+import type { ExchangeConfig, ExchangeSingleWalletConfig } from "./_methods/_base/execute.js";
 
 // =============================================================
 // Methods Imports
@@ -256,7 +256,7 @@ import {
 /**
  * A client for interacting with the Hyperliquid Exchange API.
  */
-export class ExchangeClient<C extends ExchangeConfig = ExchangeConfig> {
+export class ExchangeClient<C extends ExchangeConfig = ExchangeSingleWalletConfig> {
   config_: C;
 
   /**
@@ -290,15 +290,15 @@ export class ExchangeClient<C extends ExchangeConfig = ExchangeConfig> {
    * import { privateKeyToAccount } from "npm:viem/accounts";
    * import { ethers } from "npm:ethers";
    *
-   * const wallet1 = privateKeyToAccount("0x...");
-   * const wallet2 = new ethers.Wallet("0x...");
-   * // ... and more wallets
+   * const signer1 = privateKeyToAccount("0x...");
+   * const signer2 = new ethers.Wallet("0x...");
+   * // ... and more signers
    *
    * const transport = new hl.HttpTransport(); // or `WebSocketTransport`
    *
    * const client = new hl.ExchangeClient({
    *   transport,
-   *   wallet: [wallet1, wallet2],
+   *   signers: [signer1, signer2],
    *   multiSigUser: "0x...",
    * });
    * ```

package/src/src/api/subscription/_methods/allDexsAssetCtxs.ts

@@ -0,0 +1,140 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Decimal, UnsignedDecimal } from "../../_schemas.js";
+
+/** Subscription to asset context events for all DEXs. */
+export const AllDexsAssetCtxsRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of subscription. */
+      type: v.pipe(
+        v.literal("allDexsAssetCtxs"),
+        v.description("Type of subscription."),
+      ),
+    }),
+    v.description("Subscription to asset context events for all DEXs."),
+  );
+})();
+export type AllDexsAssetCtxsRequest = v.InferOutput<typeof AllDexsAssetCtxsRequest>;
+
+/** Event of asset contexts for all DEXs. */
+export const AllDexsAssetCtxsEvent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Array of tuples of dex names and contexts for each perpetual asset. */
+      ctxs: v.pipe(
+        v.array(
+          v.tuple([
+            v.string(),
+            v.array(
+              v.object({
+                /** Previous day's closing price. */
+                prevDayPx: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Previous day's closing price."),
+                ),
+                /** Daily notional volume. */
+                dayNtlVlm: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Daily notional volume."),
+                ),
+                /** Mark price. */
+                markPx: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Mark price."),
+                ),
+                /** Mid price. */
+                midPx: v.pipe(
+                  v.nullable(UnsignedDecimal),
+                  v.description("Mid price."),
+                ),
+                /** Funding rate. */
+                funding: v.pipe(
+                  Decimal,
+                  v.description("Funding rate."),
+                ),
+                /** Total open interest. */
+                openInterest: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Total open interest."),
+                ),
+                /** Premium price. */
+                premium: v.pipe(
+                  v.nullable(Decimal),
+                  v.description("Premium price."),
+                ),
+                /** Oracle price. */
+                oraclePx: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Oracle price."),
+                ),
+                /** Array of impact prices. */
+                impactPxs: v.pipe(
+                  v.nullable(v.array(v.string())),
+                  v.description("Array of impact prices."),
+                ),
+                /** Daily volume in base currency. */
+                dayBaseVlm: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Daily volume in base currency."),
+                ),
+              }),
+            ),
+          ]),
+        ),
+        v.description("Array of tuples of dex names and contexts for each perpetual asset."),
+      ),
+    }),
+    v.description("Event of asset contexts for all DEXs."),
+  );
+})();
+export type AllDexsAssetCtxsEvent = v.InferOutput<typeof AllDexsAssetCtxsEvent>;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import type { SubscriptionConfig } from "./_types.js";
+import type { WebSocketSubscription } from "../../../transport/websocket/mod.js";
+
+/**
+ * Subscribe to asset contexts for all DEXs.
+ *
+ * @param config - General configuration for Subscription API subscriptions.
+ * @param listener - A callback function to be called when the event is received.
+ *
+ * @returns A request-promise that resolves with a {@link WebSocketSubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValiError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { WebSocketTransport } from "@nktkas/hyperliquid";
+ * import { allDexsAssetCtxs } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport(); // only `WebSocketTransport`
+ *
+ * const sub = await allDexsAssetCtxs(
+ *   { transport },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function allDexsAssetCtxs(
+  config: SubscriptionConfig,
+  listener: (data: AllDexsAssetCtxsEvent) => void,
+): Promise<WebSocketSubscription> {
+  const payload = v.parse(AllDexsAssetCtxsRequest, {
+    type: "allDexsAssetCtxs",
+  });
+  return config.transport.subscribe<AllDexsAssetCtxsEvent>(payload.type, payload, (e) => {
+    listener(e.detail);
+  });
+}

package/src/src/api/subscription/_methods/allDexsClearinghouseState.ts

@@ -0,0 +1,105 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+import { ClearinghouseStateResponse } from "../../info/_methods/clearinghouseState.js";
+
+/** Subscription to clearinghouse state events for all DEXs for a specific user. */
+export const AllDexsClearinghouseStateRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of subscription. */
+      type: v.pipe(
+        v.literal("allDexsClearinghouseState"),
+        v.description("Type of subscription."),
+      ),
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+    }),
+    v.description("Subscription to clearinghouse state events for all DEXs for a specific user."),
+  );
+})();
+export type AllDexsClearinghouseStateRequest = v.InferOutput<typeof AllDexsClearinghouseStateRequest>;
+
+/** Event of clearinghouse states for all DEXs for a specific user. */
+export const AllDexsClearinghouseStateEvent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+      /** Array of tuples of dex names and clearinghouse states. */
+      clearinghouseStates: v.pipe(
+        v.array(
+          v.tuple([
+            v.string(),
+            ClearinghouseStateResponse,
+          ]),
+        ),
+        v.description("Array of tuples of dex names and clearinghouse states."),
+      ),
+    }),
+    v.description("Event of clearinghouse states for all DEXs for a specific user."),
+  );
+})();
+export type AllDexsClearinghouseStateEvent = v.InferOutput<typeof AllDexsClearinghouseStateEvent>;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import type { SubscriptionConfig } from "./_types.js";
+import type { WebSocketSubscription } from "../../../transport/websocket/mod.js";
+
+/** Request parameters for the {@linkcode allDexsClearinghouseState} function. */
+export type AllDexsClearinghouseStateParameters = Omit<v.InferInput<typeof AllDexsClearinghouseStateRequest>, "type">;
+
+/**
+ * Subscribe to clearinghouse states for all DEXs for a specific user.
+ *
+ * @param config - General configuration for Subscription API subscriptions.
+ * @param params - Parameters specific to the API subscription.
+ * @param listener - A callback function to be called when the event is received.
+ *
+ * @returns A request-promise that resolves with a {@link WebSocketSubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValiError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { WebSocketTransport } from "@nktkas/hyperliquid";
+ * import { allDexsClearinghouseState } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport(); // only `WebSocketTransport`
+ *
+ * const sub = await allDexsClearinghouseState(
+ *   { transport },
+ *   { user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function allDexsClearinghouseState(
+  config: SubscriptionConfig,
+  params: AllDexsClearinghouseStateParameters,
+  listener: (data: AllDexsClearinghouseStateEvent) => void,
+): Promise<WebSocketSubscription> {
+  const payload = v.parse(AllDexsClearinghouseStateRequest, {
+    type: "allDexsClearinghouseState",
+    ...params,
+  });
+  return config.transport.subscribe<AllDexsClearinghouseStateEvent>(payload.type, payload, (e) => {
+    listener(e.detail);
+  });
+}

package/src/src/api/subscription/client.ts

@@ -16,6 +16,12 @@ import {
   type ActiveSpotAssetCtxEvent,
   type ActiveSpotAssetCtxParameters,
 } from "./_methods/activeSpotAssetCtx.js";
+import { allDexsAssetCtxs, type AllDexsAssetCtxsEvent } from "./_methods/allDexsAssetCtxs.js";
+import {
+  allDexsClearinghouseState,
+  type AllDexsClearinghouseStateEvent,
+  type AllDexsClearinghouseStateParameters,
+} from "./_methods/allDexsClearinghouseState.js";
 import { allMids, type AllMidsEvent, type AllMidsParameters } from "./_methods/allMids.js";
 import { assetCtxs, type AssetCtxsEvent, type AssetCtxsParameters } from "./_methods/assetCtxs.js";
 import { bbo, type BboEvent, type BboParameters } from "./_methods/bbo.js";
@@ -112,6 +118,21 @@ export class SubscriptionClient<C extends SubscriptionConfig = SubscriptionConfi
     return activeSpotAssetCtx(this.config_, params, listener);
   }
 
+  /** @see {@link allDexsAssetCtxs} */
+  allDexsAssetCtxs(
+    listener: (data: AllDexsAssetCtxsEvent) => void,
+  ): Promise<WebSocketSubscription> {
+    return allDexsAssetCtxs(this.config_, listener);
+  }
+
+  /** @see {@link allDexsClearinghouseState} */
+  allDexsClearinghouseState(
+    params: AllDexsClearinghouseStateParameters,
+    listener: (data: AllDexsClearinghouseStateEvent) => void,
+  ): Promise<WebSocketSubscription> {
+    return allDexsClearinghouseState(this.config_, params, listener);
+  }
+
   /** @see {@link allMids} */
   allMids(
     listener: (data: AllMidsEvent) => void,
@@ -330,6 +351,11 @@ export type {
   ActiveSpotAssetCtxEvent as ActiveSpotAssetCtxWsEvent,
   ActiveSpotAssetCtxParameters as ActiveSpotAssetCtxWsParameters,
 } from "./_methods/activeSpotAssetCtx.js";
+export type { AllDexsAssetCtxsEvent as AllDexsAssetCtxsWsEvent } from "./_methods/allDexsAssetCtxs.js";
+export type {
+  AllDexsClearinghouseStateEvent as AllDexsClearinghouseStateWsEvent,
+  AllDexsClearinghouseStateParameters as AllDexsClearinghouseStateWsParameters,
+} from "./_methods/allDexsClearinghouseState.js";
 export type { AllMidsEvent as AllMidsWsEvent, AllMidsParameters as AllMidsWsParameters } from "./_methods/allMids.js";
 export type {
   AssetCtxsEvent as AssetCtxsWsEvent,

package/src/src/api/subscription/mod.ts

@@ -28,6 +28,8 @@ export type { SubscriptionConfig } from "./_methods/_types.js";
 export * from "./_methods/activeAssetCtx.js";
 export * from "./_methods/activeAssetData.js";
 export * from "./_methods/activeSpotAssetCtx.js";
+export * from "./_methods/allDexsAssetCtxs.js";
+export * from "./_methods/allDexsClearinghouseState.js";
 export * from "./_methods/allMids.js";
 export * from "./_methods/assetCtxs.js";
 export * from "./_methods/bbo.js";