@nktkas/hyperliquid 0.30.0 → 0.30.3

package/src/deps/jsr.io/@std/async/1.1.0/unstable_semaphore.ts

@@ -0,0 +1,147 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+
+/** Internal node for the FIFO waiting queue. */
+interface Node {
+  res: () => void;
+  next: Node | undefined;
+}
+
+/**
+ * A counting semaphore for limiting concurrent access to a resource.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { Semaphore } from "@std/async/unstable-semaphore";
+ *
+ * const sem = new Semaphore(2);
+ * {
+ *   using _permit = await sem.acquire();
+ *   // critical section
+ * } // permit is automatically released when exiting the block
+ * ```
+ */
+export class Semaphore {
+  #max: number;
+  /** Current number of available permits. */
+  #count: number;
+  /** Head of the waiting queue. */
+  #head: Node | undefined;
+  /** Tail of the waiting queue. */
+  #tail: Node | undefined;
+
+  /**
+   * 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 (!Number.isInteger(max) || max < 1) {
+      throw new TypeError(
+        `Cannot create semaphore as 'max' must be a positive integer: received ${max}`,
+      );
+    }
+    this.#count = this.#max = max;
+  }
+
+  /**
+   * Acquires a permit, waiting if none are available.
+   *
+   * @example Usage
+   * ```ts no-assert
+   * import { Semaphore } from "@std/async/unstable-semaphore";
+   *
+   * const sem = new Semaphore(1);
+   * await sem.acquire();
+   * try {
+   *   // critical section
+   * } finally {
+   *   sem.release();
+   * }
+   * ```
+   *
+   * @example Using `using` statement
+   * ```ts no-assert
+   * import { Semaphore } from "@std/async/unstable-semaphore";
+   *
+   * const sem = new Semaphore(1);
+   * {
+   *   using _permit = await sem.acquire();
+   *   // critical section
+   * } // permit is automatically released when exiting the block
+   * ```
+   *
+   * @returns A promise that resolves to a {@linkcode Disposable} when a permit is acquired.
+   */
+  acquire(): Promise<Disposable> {
+    const disposable: Disposable = { [Symbol.dispose]: () => this.release() };
+    if (this.#count > 0) {
+      this.#count--;
+      return Promise.resolve(disposable);
+    }
+    return new Promise((res) => {
+      const node: Node = { res: () => res(disposable), next: undefined };
+      if (this.#tail) {
+        this.#tail = this.#tail.next = node;
+      } else {
+        this.#head = this.#tail = node;
+      }
+    });
+  }
+
+  /**
+   * Tries to acquire a permit without waiting.
+   *
+   * @example Usage
+   * ```ts no-assert
+   * import { Semaphore } from "@std/async/unstable-semaphore";
+   *
+   * const sem = new Semaphore(1);
+   * const permit = sem.tryAcquire();
+   * if (permit) {
+   *   using _ = permit;
+   *   // critical section
+   * } else {
+   *   // resource is busy
+   * }
+   * ```
+   *
+   * @returns A {@linkcode Disposable} if a permit was acquired, `undefined` otherwise.
+   */
+  tryAcquire(): Disposable | undefined {
+    if (this.#count > 0) {
+      this.#count--;
+      return { [Symbol.dispose]: () => this.release() };
+    }
+    return undefined;
+  }
+
+  /**
+   * Releases a permit, allowing the next waiter to proceed.
+   *
+   * @example Usage
+   * ```ts no-assert
+   * import { Semaphore } from "@std/async/unstable-semaphore";
+   *
+   * const sem = new Semaphore(1);
+   * await sem.acquire();
+   * try {
+   *   // critical section
+   * } finally {
+   *   sem.release();
+   * }
+   * ```
+   */
+  release(): void {
+    if (this.#head) {
+      this.#head.res();
+      this.#head = this.#head.next;
+      if (!this.#head) this.#tail = undefined;
+    } else if (this.#count < this.#max) {
+      this.#count++;
+    }
+  }
+}

package/src/src/api/_schemas.ts

@@ -10,6 +10,7 @@ export const UnsignedDecimal = /* @__PURE__ */ (() => {
   return v.pipe(
     v.union([v.string(), v.number()]),
     v.toString(),
+    v.string(), // HACK: for correct JSONSchema generation
     v.transform((value) => formatDecimalString(value)),
     v.regex(/^[0-9]+(\.[0-9]+)?$/),
   );
@@ -20,6 +21,7 @@ export const Decimal = /* @__PURE__ */ (() => {
   return v.pipe(
     v.union([v.string(), v.number()]),
     v.toString(),
+    v.string(), // HACK: for correct JSONSchema generation
     v.transform((value) => formatDecimalString(value)),
     v.regex(/^-?[0-9]+(\.[0-9]+)?$/),
   );
@@ -30,6 +32,7 @@ export const Integer = /* @__PURE__ */ (() => {
   return v.pipe(
     v.union([v.string(), v.number()]),
     v.toNumber(),
+    v.number(), // HACK: for correct JSONSchema generation
     v.safeInteger(),
   );
 })();
@@ -39,6 +42,7 @@ export const UnsignedInteger = /* @__PURE__ */ (() => {
   return v.pipe(
     v.union([v.string(), v.number()]),
     v.toNumber(),
+    v.number(), // HACK: for correct JSONSchema generation
     v.safeInteger(),
     v.minValue(0),
   );

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

@@ -1,5 +1,6 @@
 /**
  * Nonce manager for generating unique nonces per wallet address and network.
+ *
  * Uses lazy cleanup: removes entries when Date.now() > lastNonce.
  */
 class NonceManager {
@@ -24,5 +25,5 @@ class NonceManager {
   }
 }
 
-/** Default nonce manager, used when custom nonceManager is not provided in config. */
-export const defaultNonceManager = /* @__PURE__ */ new NonceManager();
+/** Global nonce manager instance. */
+export const globalNonceManager = /* @__PURE__ */ new NonceManager();

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

@@ -1,67 +1,32 @@
-// ============================================================
-// Semaphore
-// ============================================================
-
-// TODO: Replace with @std/async/semaphore if the PR (https://github.com/denoland/std/pull/6894) will be merged
-
-interface Node {
-  res: () => void;
-  next: Node | undefined;
-}
-
-export class Semaphore {
-  #max: number;
-  #count: number;
-  #head: Node | undefined;
-  #tail: Node | undefined;
-
-  constructor(max: number = 1) {
-    if (max < 1) {
-      throw new TypeError(
-        `Cannot create semaphore as 'max' must be at least 1: current value is ${max}`,
-      );
-    }
-    this.#count = this.#max = max;
-  }
-
-  acquire(): Promise<void> {
-    if (this.#count > 0) {
-      this.#count--;
-      return Promise.resolve();
-    }
-    return new Promise((res) => {
-      const node: Node = { res, next: undefined };
-      if (this.#tail) {
-        this.#tail = this.#tail.next = node;
-      } else {
-        this.#head = this.#tail = node;
-      }
-    });
-  }
-
-  release(): void {
-    if (this.#head) {
-      this.#head.res();
-      this.#head = this.#head.next;
-      if (!this.#head) this.#tail = undefined;
-    } else if (this.#count < this.#max) {
-      this.#count++;
-    }
-  }
-}
-
-// ============================================================
-// RefCounted Registry
-// ============================================================
+import { Semaphore } from "../../../../../deps/jsr.io/@std/async/1.1.0/unstable_semaphore.js";
 
+/**
+ * A reference-counted registry for lazily creating and reusing per-key values.
+ *
+ * @template K - Map key type.
+ * @template V - Stored value type.
+ */
 class RefCountedRegistry<K, V> {
   #map = new Map<K, { value: V; refs: number }>();
   #factory: () => V;
 
+  /**
+   * Creates a new registry instance.
+   *
+   * @param factory - Factory function used to create a new value when a key is first referenced.
+   */
   constructor(factory: () => V) {
     this.#factory = factory;
   }
 
+  /**
+   * Increments the reference count for a key and returns its value.
+   *
+   * If the key is not present, a new value is created via the factory.
+   *
+   * @param key - Registry key.
+   * @returns The value associated with the key.
+   */
   ref(key: K): V {
     let entry = this.#map.get(key);
     if (!entry) {
@@ -72,6 +37,13 @@ class RefCountedRegistry<K, V> {
     return entry.value;
   }
 
+  /**
+   * Decrements the reference count for a key.
+   *
+   * When the count reaches zero, the entry is removed.
+   *
+   * @param key - Registry key.
+   */
   unref(key: K): void {
     const entry = this.#map.get(key);
     if (!entry) return;
@@ -81,12 +53,15 @@ class RefCountedRegistry<K, V> {
   }
 }
 
-// ============================================================
-// Helper
-// ============================================================
-
 const semaphores = new RefCountedRegistry(() => new Semaphore(1));
 
+/**
+ * Acquires a lock for the given key, executes the provided async function, and releases the lock.
+ *
+ * @param key The key to lock on.
+ * @param fn The async function to execute while holding the lock.
+ * @returns The result of the async function.
+ */
 export async function withLock<K, T>(key: K, fn: () => Promise<T>): Promise<T> {
   const semaphore = semaphores.ref(key);
   await semaphore.acquire();

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

@@ -10,7 +10,7 @@ import {
   signUserSignedAction,
 } from "../../../../signing/mod.js";
 import { assertSuccessResponse } from "./errors.js";
-import { defaultNonceManager } from "./_nonce.js";
+import { globalNonceManager } from "./_nonce.js";
 import { withLock } from "./_semaphore.js";
 import type { SignatureSchema } from "./commonSchemas.js";
 
@@ -108,7 +108,7 @@ export async function executeL1Action<T>(
   // Semaphore ensures requests arrive at server in nonce order (prevents out-of-order delivery)
   const key = `${walletAddress}:${transport.isTestnet}`;
   return await withLock(key, async () => {
-    const nonce = await (config.nonceManager?.(walletAddress) ?? defaultNonceManager.getNonce(key));
+    const nonce = await (config.nonceManager?.(walletAddress) ?? globalNonceManager.getNonce(key));
 
     // Validate and resolve options
     const vaultAddress = v.parse(
@@ -186,7 +186,7 @@ export async function executeUserSignedAction<T>(
   // Semaphore ensures requests arrive at server in nonce order (prevents out-of-order delivery)
   const key = `${walletAddress}:${transport.isTestnet}`;
   return withLock(key, async () => {
-    const nonce = await (config.nonceManager?.(walletAddress) ?? defaultNonceManager.getNonce(key));
+    const nonce = await (config.nonceManager?.(walletAddress) ?? globalNonceManager.getNonce(key));
     const signal = options?.signal;
 
     // Add system fields for user-signed actions

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

@@ -37,17 +37,26 @@ export const ApproveAgentRequest = /* @__PURE__ */ (() => {
             Address,
             v.description("Agent address."),
           ),
-          /** Agent name or null for unnamed agent. */
+          /** Agent name (min 1 and max 16 characters) or null for unnamed agent. */
           agentName: v.pipe(
             v.nullish(
               v.pipe(
                 v.string(),
-                v.minLength(1),
-                v.maxLength(17),
+                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}`;
+                  },
+                ),
               ),
               null,
             ),
-            v.description("Agent name or null for unnamed agent."),
+            v.description("Agent name (min 1 and max 16 characters) or null for unnamed agent."),
           ),
           /** Nonce (timestamp in ms) used to prevent replay attacks. */
           nonce: v.pipe(
@@ -140,9 +149,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: "..." },
+ *   { agentAddress: "0x...", agentName: "myAgent" },
+ * );
+ *
+ * // With expiration timestamp
+ * const expirationTimestamp = Date.now() + 24 * 60 * 60 * 1000;
+ * await approveAgent(
+ *   { transport, wallet },
+ *   {
+ *     agentAddress: "0x...",
+ *     agentName: `myAgent valid_until ${expirationTimestamp}`,
+ *   },
  * );
  * ```
  *

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

@@ -0,0 +1,133 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address, UnsignedDecimal, UnsignedInteger } from "../../_schemas.js";
+import { ErrorResponse, SignatureSchema, SuccessResponse } from "./_base/commonSchemas.js";
+
+/** Borrow or lend assets. */
+export const BorrowLendRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("borrowLend"),
+            v.description("Type of action."),
+          ),
+          /** Operation type. */
+          operation: v.pipe(
+            v.picklist(["supply", "withdraw", "repay", "borrow"]),
+            v.description("Operation type."),
+          ),
+          /** Token ID. */
+          token: v.pipe(
+            UnsignedInteger,
+            v.description("Token ID."),
+          ),
+          /** Amount to supply/withdraw (null = full). */
+          amount: v.pipe(
+            v.nullable(UnsignedDecimal),
+            v.description("Amount to supply/withdraw (null = full)."),
+          ),
+        }),
+        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."),
+      ),
+      /** Vault address (for vault trading). */
+      vaultAddress: v.pipe(
+        v.optional(Address),
+        v.description("Vault address (for vault trading)."),
+      ),
+      /** Expiration time of the action. */
+      expiresAfter: v.pipe(
+        v.optional(UnsignedInteger),
+        v.description("Expiration time of the action."),
+      ),
+    }),
+    v.description("Borrow or lend assets."),
+  );
+})();
+export type BorrowLendRequest = v.InferOutput<typeof BorrowLendRequest>;
+
+/** Successful response without specific data or error response. */
+export const BorrowLendResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([SuccessResponse, ErrorResponse]),
+    v.description("Successful response without specific data or error response."),
+  );
+})();
+export type BorrowLendResponse = v.InferOutput<typeof BorrowLendResponse>;
+
+// ============================================================
+// 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 BorrowLendParameters = /* @__PURE__ */ (() => {
+  return v.omit(
+    v.object(BorrowLendRequest.entries.action.entries),
+    ["type"],
+  );
+})();
+/** Action parameters for the {@linkcode borrowLend} function. */
+export type BorrowLendParameters = v.InferInput<typeof BorrowLendParameters>;
+
+/** Request options for the {@linkcode borrowLend} function. */
+export type BorrowLendOptions = ExtractRequestOptions<v.InferInput<typeof BorrowLendRequest>>;
+
+/** Successful variant of {@linkcode BorrowLendResponse} without errors. */
+export type BorrowLendSuccessResponse = ExcludeErrorResponse<BorrowLendResponse>;
+
+/**
+ * Borrow or lend assets.
+ *
+ * @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 { borrowLend } from "@nktkas/hyperliquid/api/exchange";
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ *
+ * const wallet = privateKeyToAccount("0x..."); // viem or ethers
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await borrowLend(
+ *   { transport, wallet },
+ *   { operation: "supply", token: 0, amount: "20" },
+ * );
+ * ```
+ */
+export function borrowLend(
+  config: ExchangeConfig,
+  params: BorrowLendParameters,
+  opts?: BorrowLendOptions,
+): Promise<BorrowLendSuccessResponse> {
+  const action = v.parse(BorrowLendParameters, params);
+  return executeL1Action(config, { type: "borrowLend", ...action }, opts);
+}

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

@@ -141,11 +141,11 @@ export const OrderRequest = /* @__PURE__ */ (() => {
                 Address,
                 v.description("Builder address."),
               ),
-              /** Builder fee in 0.1bps (1 = 0.0001%). */
+              /** Builder fee in 0.1bps (1 = 0.0001%). Max 100 for perps (0.1%), 1000 for spot (1%). */
               f: v.pipe(
                 UnsignedInteger,
-                v.maxValue(100),
-                v.description("Builder fee in 0.1bps (1 = 0.0001%)."),
+                v.maxValue(1000),
+                v.description("Builder fee in 0.1bps (1 = 0.0001%). Max 100 for perps (0.1%), 1000 for spot (1%)."),
               ),
             })),
             v.description("Builder fee."),
@@ -259,6 +259,8 @@ export const OrderResponse = /* @__PURE__ */ (() => {
                         v.description("Error message."),
                       ),
                     }),
+                    v.literal("waitingForFill"),
+                    v.literal("waitingForTrigger"),
                   ]),
                 ),
                 v.description("Array of statuses for each placed order."),