@nktkas/hyperliquid 0.30.2 → 0.31.0

package/src/deps/jsr.io/@std/async/{1.0.16 → 1.1.1}/unstable_semaphore.ts

@@ -1,4 +1,4 @@
-// Copyright 2018-2025 the Deno authors. MIT license.
+// Copyright 2018-2026 the Deno authors. MIT license.
 // This module is browser compatible.
 
 /** Internal node for the FIFO waiting queue. */
@@ -36,11 +36,12 @@ export class Semaphore {
    * Creates a new semaphore with the specified number of permits.
    *
    * @param max Maximum concurrent permits. Defaults to 1 (mutex).
+   * @throws {TypeError} If `max` is not a positive integer.
    */
   constructor(max: number = 1) {
-    if (max < 1) {
+    if (!Number.isInteger(max) || max < 1) {
       throw new TypeError(
-        `Cannot create semaphore as 'max' must be at least 1: current value is ${max}`,
+        `Cannot create semaphore as 'max' must be a positive integer: received ${max}`,
       );
     }
     this.#count = this.#max = max;

package/src/src/api/_schemas.ts

@@ -1,4 +1,4 @@
-// deno-lint-ignore-file valibot-project/require-name-suffix valibot-project/require-jsdoc valibot-project/require-description
+// deno-lint-ignore-file valibot-project/require-name-suffix
 
 import * as v from "valibot";
 
@@ -6,6 +6,7 @@ import * as v from "valibot";
 // Number
 // ============================================================
 
+/** Unsigned decimal number as a string (e.g., "123.45"). */
 export const UnsignedDecimal = /* @__PURE__ */ (() => {
   return v.pipe(
     v.union([v.string(), v.number()]),
@@ -17,6 +18,7 @@ export const UnsignedDecimal = /* @__PURE__ */ (() => {
 })();
 export type UnsignedDecimal = v.InferOutput<typeof UnsignedDecimal>;
 
+/** Decimal number as a string, can be negative (e.g., "-123.45"). */
 export const Decimal = /* @__PURE__ */ (() => {
   return v.pipe(
     v.union([v.string(), v.number()]),
@@ -28,6 +30,7 @@ export const Decimal = /* @__PURE__ */ (() => {
 })();
 export type Decimal = v.InferOutput<typeof Decimal>;
 
+/** Safe integer number. */
 export const Integer = /* @__PURE__ */ (() => {
   return v.pipe(
     v.union([v.string(), v.number()]),
@@ -38,6 +41,7 @@ export const Integer = /* @__PURE__ */ (() => {
 })();
 export type Integer = v.InferOutput<typeof Integer>;
 
+/** Unsigned safe integer number (>= 0). */
 export const UnsignedInteger = /* @__PURE__ */ (() => {
   return v.pipe(
     v.union([v.string(), v.number()]),
@@ -69,6 +73,7 @@ function formatDecimalString(value: string): string {
 // Hex
 // ============================================================
 
+/** Hexadecimal string starting with "0x". */
 export const Hex = /* @__PURE__ */ (() => {
   return v.pipe(
     v.string(),
@@ -78,11 +83,13 @@ export const Hex = /* @__PURE__ */ (() => {
 })();
 export type Hex = v.InferOutput<typeof Hex>;
 
+/** Ethereum address (42 characters hex string). */
 export const Address = /* @__PURE__ */ (() => {
   return v.pipe(Hex, v.length(42));
 })();
 export type Address = v.InferOutput<typeof Address>;
 
+/** Client order ID (34 characters hex string). */
 export const Cloid = /* @__PURE__ */ (() => {
   return v.pipe(Hex, v.length(34));
 })();
@@ -92,6 +99,7 @@ export type Cloid = v.InferOutput<typeof Cloid>;
 // Other
 // ============================================================
 
+/** Percentage string (e.g., "50%"). */
 export const Percent = /* @__PURE__ */ (() => {
   return v.pipe(
     v.string(),
@@ -101,6 +109,7 @@ export const Percent = /* @__PURE__ */ (() => {
 })();
 export type Percent = v.InferOutput<typeof Percent>;
 
+/** ISO 8601 datetime string without timezone (e.g., "2024-01-15T10:30:00"). */
 export const ISO8601WithoutTimezone = /* @__PURE__ */ (() => {
   return v.pipe(
     v.string(),

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

@@ -1,4 +1,4 @@
-import { Semaphore } from "../../../../../deps/jsr.io/@std/async/1.0.16/unstable_semaphore.js";
+import { Semaphore } from "../../../../../deps/jsr.io/@std/async/1.1.1/unstable_semaphore.js";
 
 /**
  * A reference-counted registry for lazily creating and reusing per-key values.

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

@@ -3,82 +3,44 @@ import { Hex } from "../../../_schemas.js";
 
 /** Error response for failed operations. */
 export const ErrorResponse = /* @__PURE__ */ (() => {
-  return v.pipe(
-    v.object({
-      /** Error status. */
-      status: v.pipe(
-        v.literal("err"),
-        v.description("Error status."),
-      ),
-      /** Error message. */
-      response: v.pipe(
-        v.string(),
-        v.description("Error message."),
-      ),
-    }),
-    v.description("Error response for failed operations."),
-  );
+  return v.object({
+    /** Error status. */
+    status: v.literal("err"),
+    /** Error message. */
+    response: v.string(),
+  });
 })();
 export type ErrorResponse = v.InferOutput<typeof ErrorResponse>;
 
 /** Successful response without specific data. */
 export const SuccessResponse = /* @__PURE__ */ (() => {
-  return v.pipe(
-    v.object({
-      /** Successful status. */
-      status: v.pipe(
-        v.literal("ok"),
-        v.description("Successful status."),
-      ),
-      /** Response details. */
-      response: v.pipe(
-        v.object({
-          /** Type of response. */
-          type: v.pipe(
-            v.literal("default"),
-            v.description("Type of response."),
-          ),
-        }),
-        v.description("Response details."),
-      ),
+  return v.object({
+    /** Successful status. */
+    status: v.literal("ok"),
+    /** Response details. */
+    response: v.object({
+      /** Type of response. */
+      type: v.literal("default"),
     }),
-    v.description("Successful response without specific data."),
-  );
+  });
 })();
 export type SuccessResponse = v.InferOutput<typeof SuccessResponse>;
 
 /** ECDSA signature components. */
 export const SignatureSchema = /* @__PURE__ */ (() => {
-  return v.pipe(
-    v.object({
-      /** First 32-byte component. */
-      r: v.pipe(
-        Hex,
-        v.length(66),
-        v.description("First 32-byte component."),
-      ),
-      /** Second 32-byte component. */
-      s: v.pipe(
-        Hex,
-        v.length(66),
-        v.description("Second 32-byte component."),
-      ),
-      /** Recovery identifier. */
-      v: v.pipe(
-        v.picklist([27, 28]),
-        v.description("Recovery identifier."),
-      ),
-    }),
-    v.description("ECDSA signature components."),
-  );
+  return v.object({
+    /** First 32-byte component. */
+    r: v.pipe(Hex, v.length(66)),
+    /** Second 32-byte component. */
+    s: v.pipe(Hex, v.length(66)),
+    /** Recovery identifier. */
+    v: v.picklist([27, 28]),
+  });
 })();
 export type SignatureSchema = v.InferOutput<typeof SignatureSchema>;
 
 /** HyperLiquid network type. */
 export const HyperliquidChainSchema = /* @__PURE__ */ (() => {
-  return v.pipe(
-    v.picklist(["Mainnet", "Testnet"]),
-    v.description("HyperLiquid network type."),
-  );
+  return v.picklist(["Mainnet", "Testnet"]);
 })();
 export type HyperliquidChainSchema = v.InferOutput<typeof HyperliquidChainSchema>;

package/src/src/api/exchange/_methods/agentEnableDexAbstraction.ts

@@ -12,37 +12,19 @@ import { ErrorResponse, SignatureSchema, SuccessResponse } from "./_base/commonS
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#enable-hip-3-dex-abstraction-agent
  */
 export const AgentEnableDexAbstractionRequest = /* @__PURE__ */ (() => {
-  return v.pipe(
-    v.object({
-      /** Action to perform. */
-      action: v.pipe(
-        v.object({
-          /** Type of action. */
-          type: v.pipe(
-            v.literal("agentEnableDexAbstraction"),
-            v.description("Type of action."),
-          ),
-        }),
-        v.description("Action to perform."),
-      ),
-      /** Nonce (timestamp in ms) used to prevent replay attacks. */
-      nonce: v.pipe(
-        UnsignedInteger,
-        v.description("Nonce (timestamp in ms) used to prevent replay attacks."),
-      ),
-      /** ECDSA signature components. */
-      signature: v.pipe(
-        SignatureSchema,
-        v.description("ECDSA signature components."),
-      ),
-      /** Expiration time of the action. */
-      expiresAfter: v.pipe(
-        v.optional(UnsignedInteger),
-        v.description("Expiration time of the action."),
-      ),
+  return v.object({
+    /** Action to perform. */
+    action: v.object({
+      /** Type of action. */
+      type: v.literal("agentEnableDexAbstraction"),
     }),
-    v.description("Enable HIP-3 DEX abstraction."),
-  );
+    /** Nonce (timestamp in ms) used to prevent replay attacks. */
+    nonce: UnsignedInteger,
+    /** ECDSA signature components. */
+    signature: SignatureSchema,
+    /** Expiration time of the action. */
+    expiresAfter: v.optional(UnsignedInteger),
+  });
 })();
 export type AgentEnableDexAbstractionRequest = v.InferOutput<typeof AgentEnableDexAbstractionRequest>;
 
@@ -51,10 +33,7 @@ export type AgentEnableDexAbstractionRequest = v.InferOutput<typeof AgentEnableD
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#enable-hip-3-dex-abstraction-agent
  */
 export const AgentEnableDexAbstractionResponse = /* @__PURE__ */ (() => {
-  return v.pipe(
-    v.union([SuccessResponse, ErrorResponse]),
-    v.description("Successful response without specific data or error response."),
-  );
+  return v.union([SuccessResponse, ErrorResponse]);
 })();
 export type AgentEnableDexAbstractionResponse = v.InferOutput<typeof AgentEnableDexAbstractionResponse>;
 
@@ -76,6 +55,8 @@ export type AgentEnableDexAbstractionSuccessResponse = ExcludeErrorResponse<Agen
 /**
  * Enable HIP-3 DEX abstraction.
  *
+ * @deprecated Use {@link agentSetAbstraction} instead.
+ *
  * @param config - General configuration for Exchange API requests.
  * @param params - Parameters specific to the API request.
  * @param opts - Request execution options.

package/src/src/api/exchange/_methods/agentSetAbstraction.ts

@@ -0,0 +1,109 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { UnsignedInteger } from "../../_schemas.js";
+import { ErrorResponse, SignatureSchema, SuccessResponse } from "./_base/commonSchemas.js";
+
+/**
+ * Set User abstraction mode (method for agent wallet).
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#set-user-abstraction-agent
+ */
+export const AgentSetAbstractionRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Action to perform. */
+    action: v.object({
+      /** Type of action. */
+      type: v.literal("agentSetAbstraction"),
+      /**
+       * User abstraction mode.
+       * - `"i"`: disabled
+       * - `"u"`: unifiedAccount
+       * - `"p"`: portfolioMargin
+       */
+      abstraction: v.picklist(["i", "u", "p"]),
+    }),
+    /** Nonce (timestamp in ms) used to prevent replay attacks. */
+    nonce: UnsignedInteger,
+    /** ECDSA signature components. */
+    signature: SignatureSchema,
+    /** Expiration time of the action. */
+    expiresAfter: v.optional(UnsignedInteger),
+  });
+})();
+export type AgentSetAbstractionRequest = v.InferOutput<typeof AgentSetAbstractionRequest>;
+
+/**
+ * Successful response without specific data or error response.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#set-user-abstraction-agent
+ */
+export const AgentSetAbstractionResponse = /* @__PURE__ */ (() => {
+  return v.union([SuccessResponse, ErrorResponse]);
+})();
+export type AgentSetAbstractionResponse = v.InferOutput<typeof AgentSetAbstractionResponse>;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { type ExchangeConfig, executeL1Action, type ExtractRequestOptions } from "./_base/execute.js";
+import type { ExcludeErrorResponse } from "./_base/errors.js";
+
+/** Schema for user-provided action parameters (excludes system fields). */
+const AgentSetAbstractionParameters = /* @__PURE__ */ (() => {
+  return v.omit(
+    v.object(AgentSetAbstractionRequest.entries.action.entries),
+    ["type"],
+  );
+})();
+/** Action parameters for the {@linkcode agentSetAbstraction} function. */
+export type AgentSetAbstractionParameters = v.InferInput<typeof AgentSetAbstractionParameters>;
+
+/** Request options for the {@linkcode agentSetAbstraction} function. */
+export type AgentSetAbstractionOptions = ExtractRequestOptions<
+  v.InferInput<typeof AgentSetAbstractionRequest>
+>;
+
+/** Successful variant of {@linkcode AgentSetAbstractionResponse} without errors. */
+export type AgentSetAbstractionSuccessResponse = ExcludeErrorResponse<AgentSetAbstractionResponse>;
+
+/**
+ * Set User abstraction mode (method for agent wallet).
+ *
+ * @param config - General configuration for Exchange API requests.
+ * @param params - Parameters specific to the API request.
+ * @param opts - Request execution options.
+ *
+ * @returns Successful response without specific data.
+ *
+ * @throws {ValiError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ * @throws {ApiRequestError} When the API returns an unsuccessful response.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { agentSetAbstraction } from "@nktkas/hyperliquid/api/exchange";
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ *
+ * const wallet = privateKeyToAccount("0x..."); // viem or ethers
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * await agentSetAbstraction(
+ *   { transport, wallet },
+ *   { abstraction: "u" },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#set-user-abstraction-agent
+ */
+export function agentSetAbstraction(
+  config: ExchangeConfig,
+  params: AgentSetAbstractionParameters,
+  opts?: AgentSetAbstractionOptions,
+): Promise<AgentSetAbstractionSuccessResponse> {
+  const action = v.parse(AgentSetAbstractionParameters, params);
+  return executeL1Action(config, { type: "agentSetAbstraction", ...action }, opts);
+}

package/src/src/api/exchange/_methods/approveAgent.ts

@@ -12,64 +12,43 @@ import { ErrorResponse, HyperliquidChainSchema, SignatureSchema, SuccessResponse
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#approve-an-api-wallet
  */
 export const ApproveAgentRequest = /* @__PURE__ */ (() => {
-  return v.pipe(
-    v.object({
-      /** Action to perform. */
-      action: v.pipe(
-        v.object({
-          /** Type of action. */
-          type: v.pipe(
-            v.literal("approveAgent"),
-            v.description("Type of action."),
+  return v.object({
+    /** Action to perform. */
+    action: v.object({
+      /** Type of action. */
+      type: v.literal("approveAgent"),
+      /** Chain ID in hex format for EIP-712 signing. */
+      signatureChainId: Hex,
+      /** HyperLiquid network type. */
+      hyperliquidChain: HyperliquidChainSchema,
+      /** Agent address. */
+      agentAddress: Address,
+      /** Agent name (min 1 and max 16 characters) or null for unnamed agent. */
+      agentName: v.nullish(
+        v.pipe(
+          v.string(),
+          v.check(
+            (input) => {
+              // Ignore trailing ` valid_until <timestamp>` when checking length
+              const baseName = input.replace(/ valid_until \d+$/, "");
+              return baseName.length >= 1 && baseName.length <= 16;
+            },
+            (issue) => {
+              const baseName = issue.input.replace(/ valid_until \d+$/, "");
+              return `Invalid length: Expected >= 1 and <= 16 but received ${baseName.length}`;
+            },
           ),
-          /** Chain ID in hex format for EIP-712 signing. */
-          signatureChainId: v.pipe(
-            Hex,
-            v.description("Chain ID in hex format for EIP-712 signing."),
-          ),
-          /** HyperLiquid network type. */
-          hyperliquidChain: v.pipe(
-            HyperliquidChainSchema,
-            v.description("HyperLiquid network type."),
-          ),
-          /** Agent address. */
-          agentAddress: v.pipe(
-            Address,
-            v.description("Agent address."),
-          ),
-          /** Agent name or null for unnamed agent. */
-          agentName: v.pipe(
-            v.nullish(
-              v.pipe(
-                v.string(),
-                v.minLength(1),
-                v.maxLength(17),
-              ),
-              null,
-            ),
-            v.description("Agent name or null for unnamed agent."),
-          ),
-          /** Nonce (timestamp in ms) used to prevent replay attacks. */
-          nonce: v.pipe(
-            UnsignedInteger,
-            v.description("Nonce (timestamp in ms) used to prevent replay attacks."),
-          ),
-        }),
-        v.description("Action to perform."),
+        ),
+        null,
       ),
       /** Nonce (timestamp in ms) used to prevent replay attacks. */
-      nonce: v.pipe(
-        UnsignedInteger,
-        v.description("Nonce (timestamp in ms) used to prevent replay attacks."),
-      ),
-      /** ECDSA signature components. */
-      signature: v.pipe(
-        SignatureSchema,
-        v.description("ECDSA signature components."),
-      ),
+      nonce: UnsignedInteger,
     }),
-    v.description("Approve an agent to sign on behalf of the master account."),
-  );
+    /** Nonce (timestamp in ms) used to prevent replay attacks. */
+    nonce: UnsignedInteger,
+    /** ECDSA signature components. */
+    signature: SignatureSchema,
+  });
 })();
 export type ApproveAgentRequest = v.InferOutput<typeof ApproveAgentRequest>;
 
@@ -78,10 +57,7 @@ export type ApproveAgentRequest = v.InferOutput<typeof ApproveAgentRequest>;
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#approve-an-api-wallet
  */
 export const ApproveAgentResponse = /* @__PURE__ */ (() => {
-  return v.pipe(
-    v.union([SuccessResponse, ErrorResponse]),
-    v.description("Successful response without specific data or error response."),
-  );
+  return v.union([SuccessResponse, ErrorResponse]);
 })();
 export type ApproveAgentResponse = v.InferOutput<typeof ApproveAgentResponse>;
 
@@ -140,9 +116,20 @@ export const ApproveAgentTypes = {
  * const wallet = privateKeyToAccount("0x..."); // viem or ethers
  * const transport = new HttpTransport(); // or `WebSocketTransport`
  *
+ * // Basic usage
+ * await approveAgent(
+ *   { transport, wallet },
+ *   { agentAddress: "0x...", agentName: "myAgent" },
+ * );
+ *
+ * // With expiration timestamp
+ * const expirationTimestamp = Date.now() + 24 * 60 * 60 * 1000;
  * await approveAgent(
  *   { transport, wallet },
- *   { agentAddress: "0x...", agentName: "..." },
+ *   {
+ *     agentAddress: "0x...",
+ *     agentName: `myAgent valid_until ${expirationTimestamp}`,
+ *   },
  * );
  * ```
  *

package/src/src/api/exchange/_methods/approveBuilderFee.ts

@@ -12,57 +12,27 @@ import { ErrorResponse, HyperliquidChainSchema, SignatureSchema, SuccessResponse
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#approve-a-builder-fee
  */
 export const ApproveBuilderFeeRequest = /* @__PURE__ */ (() => {
-  return v.pipe(
-    v.object({
-      /** Action to perform. */
-      action: v.pipe(
-        v.object({
-          /** Type of action. */
-          type: v.pipe(
-            v.literal("approveBuilderFee"),
-            v.description("Type of action."),
-          ),
-          /** Chain ID in hex format for EIP-712 signing. */
-          signatureChainId: v.pipe(
-            Hex,
-            v.description("Chain ID in hex format for EIP-712 signing."),
-          ),
-          /** HyperLiquid network type. */
-          hyperliquidChain: v.pipe(
-            HyperliquidChainSchema,
-            v.description("HyperLiquid network type."),
-          ),
-          /** Max fee rate (e.g., "0.01%"). */
-          maxFeeRate: v.pipe(
-            Percent,
-            v.description('Max fee rate (e.g., "0.01%").'),
-          ),
-          /** Builder address. */
-          builder: v.pipe(
-            Address,
-            v.description("Builder address."),
-          ),
-          /** Nonce (timestamp in ms) used to prevent replay attacks. */
-          nonce: v.pipe(
-            UnsignedInteger,
-            v.description("Nonce (timestamp in ms) used to prevent replay attacks."),
-          ),
-        }),
-        v.description("Action to perform."),
-      ),
+  return v.object({
+    /** Action to perform. */
+    action: v.object({
+      /** Type of action. */
+      type: v.literal("approveBuilderFee"),
+      /** Chain ID in hex format for EIP-712 signing. */
+      signatureChainId: Hex,
+      /** HyperLiquid network type. */
+      hyperliquidChain: HyperliquidChainSchema,
+      /** Max fee rate (e.g., "0.01%"). */
+      maxFeeRate: Percent,
+      /** Builder address. */
+      builder: Address,
       /** Nonce (timestamp in ms) used to prevent replay attacks. */
-      nonce: v.pipe(
-        UnsignedInteger,
-        v.description("Nonce (timestamp in ms) used to prevent replay attacks."),
-      ),
-      /** ECDSA signature components. */
-      signature: v.pipe(
-        SignatureSchema,
-        v.description("ECDSA signature components."),
-      ),
+      nonce: UnsignedInteger,
     }),
-    v.description("Approve a maximum fee rate for a builder."),
-  );
+    /** Nonce (timestamp in ms) used to prevent replay attacks. */
+    nonce: UnsignedInteger,
+    /** ECDSA signature components. */
+    signature: SignatureSchema,
+  });
 })();
 export type ApproveBuilderFeeRequest = v.InferOutput<typeof ApproveBuilderFeeRequest>;
 
@@ -71,10 +41,7 @@ export type ApproveBuilderFeeRequest = v.InferOutput<typeof ApproveBuilderFeeReq
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#approve-a-builder-fee
  */
 export const ApproveBuilderFeeResponse = /* @__PURE__ */ (() => {
-  return v.pipe(
-    v.union([SuccessResponse, ErrorResponse]),
-    v.description("Successful response without specific data or error response."),
-  );
+  return v.union([SuccessResponse, ErrorResponse]);
 })();
 export type ApproveBuilderFeeResponse = v.InferOutput<typeof ApproveBuilderFeeResponse>;