@hfunlabs/hyperliquid 0.27.1 → 0.30.0-hfunlabs.1

package/src/bin/cli.ts

@@ -1,11 +1,36 @@
 #!/usr/bin/env node
+// deno-lint-ignore-file no-console
+
+/**
+ * Command-line interface for interacting with Hyperliquid API.
+ *
+ * @example
+ * ```sh
+ * npx @nktkas/hyperliquid <endpoint> <method> [options]
+ * ```
+ *
+ * @example Info Endpoint
+ * ```sh
+ * npx @nktkas/hyperliquid info clearinghouseState --user 0x...
+ * ```
+ *
+ * @example Exchange Endpoint
+ * ```sh
+ * npx @nktkas/hyperliquid exchange withdraw3 --private-key 0x... --destination 0x... --amount 100.5
+ * ```
+ */
+
 // @ts-ignore: Ignore missing TS types when building npm
 import process from "node:process";
-import * as v from "valibot";
-import * as hl from "../src/mod.js";
-import { type Args, parseArgs, transformArgs } from "./_utils.js";
+import { type Args, extractArgs, transformArgs } from "./_utils.js";
+import { ExchangeClient, HttpTransport, InfoClient } from "../src/mod.js";
+import { PrivateKeySigner } from "../src/signing/mod.js";
+
+// ============================================================
+// Execute
+// ============================================================
 
-function transformParams(method: string, params: Args) {
+function transformParams(method: string, params: Args<false>): Record<string, unknown> {
   switch (method) {
     case "spotUser": {
       return { toggleSpotDusting: { ...params } };
@@ -19,69 +44,59 @@ function transformParams(method: string, params: Args) {
   }
 }
 
-class EchoTransport implements hl.IRequestTransport {
-  isTestnet: boolean;
+class EchoTransport extends HttpTransport {
   constructor(isTestnet: boolean) {
-    this.isTestnet = isTestnet;
+    super({ isTestnet });
   }
-  request<T>(_: "info" | "exchange" | "explorer", payload: unknown): Promise<T> {
+  override request<T>(_: string, payload: unknown): Promise<T> {
     return new Promise((resolve) => resolve({ status: "ok", response: payload } as T));
   }
 }
-async function executeEndpointMethod(
-  endpoint: string,
-  method: string,
-  args: Args,
-): Promise<unknown> {
+
+/** Execute CLI command on info/exchange endpoint */
+async function executeEndpointMethod(endpoint: string, method: string, args: Args<false>): Promise<unknown> {
+  // Parse CLI flags
   const isTestnet = "testnet" in args;
   const timeout = Number(args.timeout) || undefined;
   const isOffline = "offline" in args;
 
-  const transport = isOffline ? new EchoTransport(isTestnet) : new hl.HttpTransport({ isTestnet, timeout });
-  let client: hl.InfoClient | hl.ExchangeClient;
+  // Create transport (echo for offline, http for online)
+  const transport = isOffline ? new EchoTransport(isTestnet) : new HttpTransport({ isTestnet, timeout });
+  let client: InfoClient | ExchangeClient;
 
-  if (endpoint === "info") {
-    client = new hl.InfoClient({ transport });
+  // Create client based on endpoint
+  switch (endpoint) {
+    case "info":
+      client = new InfoClient({ transport });
+      break;
+    case "exchange": {
+      const wallet = new PrivateKeySigner(args["private-key"] as `0x${string}`);
+      delete args["private-key"]; // remove before uncontrolled transfer of arguments (just in case)
 
-    if (!(method in client)) {
-      throw new Error(`CLI does not support the "${method}" method in the "${endpoint}" endpoint`);
-    }
-  } else if (endpoint === "exchange") {
-    const pk = v.parse(
-      v.pipe(v.string(), v.hexadecimal()),
-      args["private-key"],
-      { message: 'Invalid format "private-key": Expected 32-byte hexadecimal string' },
-    );
-    delete args["private-key"]; // just in case
-
-    const defaultVaultAddress = v.parse(
-      v.optional(v.pipe(v.string(), v.hexadecimal())),
-      args.vault,
-      { message: 'Invalid format "vault": Expected 20-byte hexadecimal string OR nothing' },
-    );
-
-    client = new hl.ExchangeClient({ transport, wallet: pk, defaultVaultAddress });
-
-    if (!(method in client)) {
-      throw new Error(`CLI does not support the "${method}" method in the "${endpoint}" endpoint`);
+      const defaultVaultAddress = args.vault as `0x${string}` | undefined;
+
+      client = new ExchangeClient({ transport, wallet, defaultVaultAddress });
+      break;
     }
-  } else {
-    throw new Error(`Invalid endpoint "${endpoint}". Use "info" or "exchange"`);
+    default:
+      throw new Error(`Invalid endpoint "${endpoint}". Use "info" or "exchange"`);
   }
 
-  if (isOffline) {
-    // @ts-ignore - dynamic method access
-    const response = await client[method](transformParams(method, args));
-    return response.response;
-  } else {
-    // @ts-ignore - dynamic method access
-    return await client[method](transformParams(method, args));
-  }
+  // Check if method exists on client
+  if (!(method in client)) throw new Error(`Unknown "${method}" method for "${endpoint}" endpoint`);
+
+  // Execute method and return result
+  const params = transformParams(method, args);
+  // @ts-expect-error: dynamic method access
+  const response = await client[method](params);
+  return isOffline ? response.response : response; // for offline mode, we want to see the request payload, not the wrapper
 }
 
-// ──────────────────── Main ────────────────────
+// ============================================================
+// CLI
+// ============================================================
 
-function printHelp() {
+function printHelp(): void {
   console.log(`Hyperliquid CLI
 
 Usage:
@@ -118,8 +133,6 @@ Market Data:
   maxMarketOrderNtls      (no params)
   meta                    [--dex <string>]
   metaAndAssetCtxs        [--dex <string>]
-  perpDexLimits           --dex <string>
-  perpDexs                (no params)
   perpsAtOpenInterestCap  [--dex <string>]
   predictedFundings       (no params)
   recentTrades            --coin <string>
@@ -176,6 +189,11 @@ Vault:
   vaultDetails            --vaultAddress <address> [--user <address>]
   vaultSummaries          (no params)
 
+DEX:
+  perpDexLimits           --dex <string>
+  perpDexs                (no params)
+  perpDexStatus           --dex <string>
+
 Deploy Market:
   perpDeployAuctionStatus      (no params)
   spotDeployState              --user <address>
@@ -251,16 +269,12 @@ Vault:
   vaultTransfer           --vaultAddress <address> --isDeposit <bool> --usd <number>
 
 Deploy Market:
-  perpDeploy              --registerAsset <json> | --setOracle <json> | --setFundingMultipliers <json> |
-                          --haltTrading <json> | --setMarginTableIds <json> | --setFeeRecipient <json> |
-                          --setOpenInterestCaps <json> | --setSubDeployers <json> | --setFeeScale <json>
-  spotDeploy              --genesis <json> | --registerHyperliquidity <json> | --registerSpot <json> |
-                          --registerToken2 <json> | --setDeployerTradingFeeShare <json> | --userGenesis <json> |
-                          --enableQuoteToken <json>
+  perpDeploy              --<action> <json>
+  spotDeploy              --<action> <json>
 
 Validator Actions:
   cSignerAction           --jailSelf null | --unjailSelf null
-  cValidatorAction        --changeProfile <json> | --register <json> | --unregister null
+  cValidatorAction        --<action> <json>
   validatorL1Stream       --riskFreeRate <number>
 
 Other:
@@ -282,13 +296,13 @@ Examples:
   npx @nktkas/hyperliquid info candleSnapshot --coin BTC --interval 1h --startTime 1700000000000
 
   # Place a limit order
-  npx @nktkas/hyperliquid exchange order --private-key 0x... --orders '[{\\"a\\":0,\\"b\\":true,\\"p\\":30000,\\"s\\":0.1,\\"r\\":false,\\"t\\":{\\"limit\\":{\\"tif\\":\\"Gtc\\"}}}]'
+  npx @nktkas/hyperliquid exchange order --private-key 0x... --orders '[{\"a\":0,\"b\":true,\"p\":30000,\"s\":0.1,\"r\":false,\"t\":{\"limit\":{\"tif\":\"Gtc\"}}}]'
 
   # Modify an existing order
-  npx @nktkas/hyperliquid exchange modify --private-key 0x... --oid 12345 --order '{\\"a\\":0,\\"b\\":true,\\"p\\":31000,\\"s\\":0.1,\\"r\\":false,\\"t\\":{\\"limit\\":{\\"tif\\":\\"Gtc\\"}}}'
+  npx @nktkas/hyperliquid exchange modify --private-key 0x... --oid 12345 --order '{\"a\":0,\"b\":true,\"p\":31000,\"s\":0.1,\"r\":false,\"t\":{\"limit\":{\"tif\":\"Gtc\"}}}'
 
   # Cancel orders
-  npx @nktkas/hyperliquid exchange cancel --private-key 0x... --cancels '[{\\"a\\":0,\\"o\\":12345}]'
+  npx @nktkas/hyperliquid exchange cancel --private-key 0x... --cancels '[{\"a\":0,\"o\":12345}]'
 
   # Update leverage
   npx @nktkas/hyperliquid exchange updateLeverage --private-key 0x... --asset 0 --isCross true --leverage 5
@@ -303,18 +317,20 @@ Examples:
   npx @nktkas/hyperliquid exchange createVault --private-key 0x... --name "My Vault" --description "Test vault" --initialUsd 1000`);
 }
 
-const rawArgs = parseArgs(process.argv.slice(2), {
+// ============================================================
+// Entry
+// ============================================================
+
+const rawArgs = extractArgs(process.argv.slice(2), {
   flags: ["testnet", "help", "h", "offline"],
+  collect: false,
 });
-const args = transformArgs(rawArgs, {
-  number: "string",
-});
+const args = transformArgs(rawArgs, { number: "string" });
 const [endpoint, method] = args._;
-
 if (args.help || args.h || !endpoint || !method) {
   printHelp();
 } else {
   executeEndpointMethod(endpoint, method, args)
     .then((result) => console.log(JSON.stringify(result)))
-    .catch((error) => console.error("Error:", error instanceof Error ? error.message : String(error)));
+    .catch((error) => console.error(error));
 }

package/src/src/api/_schemas.ts

@@ -0,0 +1,110 @@
+// deno-lint-ignore-file valibot-project/require-name-suffix valibot-project/require-jsdoc valibot-project/require-description
+
+import * as v from "valibot";
+
+// ============================================================
+// Number
+// ============================================================
+
+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]+)?$/),
+  );
+})();
+export type UnsignedDecimal = v.InferOutput<typeof UnsignedDecimal>;
+
+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]+)?$/),
+  );
+})();
+export type Decimal = v.InferOutput<typeof Decimal>;
+
+export const Integer = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([v.string(), v.number()]),
+    v.toNumber(),
+    v.number(), // HACK: for correct JSONSchema generation
+    v.safeInteger(),
+  );
+})();
+export type Integer = v.InferOutput<typeof Integer>;
+
+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),
+  );
+})();
+export type UnsignedInteger = v.InferOutput<typeof UnsignedInteger>;
+
+function formatDecimalString(value: string): string {
+  return value
+    // remove leading/trailing whitespace
+    .trim() // "  123.45  " → "123.45"
+    // remove leading zeros
+    .replace(/^(-?)0+(?=\d)/, "$1") // "00123" → "123", "-00.5" → "-0.5"
+    // remove trailing zeros
+    .replace(/\.0*$|(\.\d+?)0+$/, "$1") // "1.2000" → "1.2", "5.0" → "5"
+    // add leading zero if starts with decimal point
+    .replace(/^(-?)\./, "$10.") // ".5" → "0.5", "-.5" → "-0.5"
+    // add "0" if string is empty after trimming
+    .replace(/^-?$/, "0") // "" → "0", "-" → "0"
+    // normalize negative zero
+    .replace(/^-0$/, "0"); // "-0" → "0"
+}
+
+// ============================================================
+// Hex
+// ============================================================
+
+export const Hex = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.string(),
+    v.regex(/^0[xX][0-9a-fA-F]+$/),
+    v.transform((value) => value.toLowerCase() as `0x${string}`),
+  );
+})();
+export type Hex = v.InferOutput<typeof Hex>;
+
+export const Address = /* @__PURE__ */ (() => {
+  return v.pipe(Hex, v.length(42));
+})();
+export type Address = v.InferOutput<typeof Address>;
+
+export const Cloid = /* @__PURE__ */ (() => {
+  return v.pipe(Hex, v.length(34));
+})();
+export type Cloid = v.InferOutput<typeof Cloid>;
+
+// ============================================================
+// Other
+// ============================================================
+
+export const Percent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.string(),
+    v.regex(/^[0-9]+(\.[0-9]+)?%$/),
+    v.transform((value) => value as `${string}%`),
+  );
+})();
+export type Percent = v.InferOutput<typeof Percent>;
+
+export const ISO8601WithoutTimezone = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.string(),
+    v.regex(/^\d{4}-(?:0[1-9]|1[0-2])-(?:[12]\d|0[1-9]|3[01])[T ](?:0\d|1\d|2[0-3])(?::[0-5]\d){2}(?:\.\d{1,9})?$/),
+  );
+})();
+export type ISO8601WithoutTimezone = v.InferOutput<typeof ISO8601WithoutTimezone>;

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

@@ -0,0 +1,28 @@
+/**
+ * Nonce manager for generating unique nonces per wallet address and network.
+ * Uses lazy cleanup: removes entries when Date.now() > lastNonce.
+ */
+class NonceManager {
+  #map = new Map<string, number>();
+
+  getNonce(key: string): number {
+    const now = Date.now();
+    this.#cleanup(now);
+
+    const lastNonce = this.#map.get(key) ?? 0;
+    const nonce = now > lastNonce ? now : lastNonce + 1;
+    this.#map.set(key, nonce);
+    return nonce;
+  }
+
+  #cleanup(now: number): void {
+    for (const [key, lastNonce] of this.#map) {
+      if (now > lastNonce) {
+        this.#map.delete(key);
+      }
+    }
+  }
+}
+
+/** Default nonce manager, used when custom nonceManager is not provided in config. */
+export const defaultNonceManager = /* @__PURE__ */ new NonceManager();

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

@@ -0,0 +1,99 @@
+// ============================================================
+// 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
+// ============================================================
+
+class RefCountedRegistry<K, V> {
+  #map = new Map<K, { value: V; refs: number }>();
+  #factory: () => V;
+
+  constructor(factory: () => V) {
+    this.#factory = factory;
+  }
+
+  ref(key: K): V {
+    let entry = this.#map.get(key);
+    if (!entry) {
+      entry = { value: this.#factory(), refs: 0 };
+      this.#map.set(key, entry);
+    }
+    entry.refs++;
+    return entry.value;
+  }
+
+  unref(key: K): void {
+    const entry = this.#map.get(key);
+    if (!entry) return;
+    if (--entry.refs === 0) {
+      this.#map.delete(key);
+    }
+  }
+}
+
+// ============================================================
+// Helper
+// ============================================================
+
+const semaphores = new RefCountedRegistry(() => new Semaphore(1));
+
+export async function withLock<K, T>(key: K, fn: () => Promise<T>): Promise<T> {
+  const semaphore = semaphores.ref(key);
+  await semaphore.acquire();
+  try {
+    return await fn();
+  } finally {
+    semaphore.release();
+    semaphores.unref(key);
+  }
+}

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

@@ -0,0 +1,84 @@
+import * as v from "valibot";
+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."),
+  );
+})();
+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."),
+      ),
+    }),
+    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."),
+  );
+})();
+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."),
+  );
+})();
+export type HyperliquidChainSchema = v.InferOutput<typeof HyperliquidChainSchema>;

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

@@ -0,0 +1,108 @@
+import { HyperliquidError } from "../../../../_base.js";
+
+// =============================================================
+// Error Detection (Duck Typing)
+// =============================================================
+
+/** Check if value has an error property. */
+function hasError(value: unknown): value is { error: string } {
+  return typeof value === "object" && value !== null &&
+    "error" in value && typeof value.error === "string";
+}
+
+/** Check if response has error status. */
+function hasErrorStatus(response: unknown): response is { status: "err"; response: string } {
+  return typeof response === "object" && response !== null &&
+    "status" in response && response.status === "err";
+}
+
+/** Check if response has statuses array with errors. */
+function hasStatusesWithErrors(response: unknown): boolean {
+  if (typeof response !== "object" || response === null) return false;
+  const r = response as { response?: { data?: { statuses?: unknown[] } } };
+  const statuses = r.response?.data?.statuses;
+  return Array.isArray(statuses) && statuses.some(hasError);
+}
+
+/** Check if response has single status with error. */
+function hasSingleStatusWithError(response: unknown): boolean {
+  if (typeof response !== "object" || response === null) return false;
+  const r = response as { response?: { data?: { status?: unknown } } };
+  return hasError(r.response?.data?.status);
+}
+
+/** Extract error message from response using duck typing. */
+function extractErrorMessage(response: unknown): string | undefined {
+  if (hasErrorStatus(response)) {
+    return response.response;
+  }
+
+  const r = response as { response?: { data?: { statuses?: unknown[]; status?: unknown } } };
+
+  if (Array.isArray(r.response?.data?.statuses)) {
+    const errors = r.response.data.statuses.reduce<string[]>((acc, status, index) => {
+      if (hasError(status)) acc.push(`Order ${index}: ${status.error}`);
+      return acc;
+    }, []);
+    if (errors.length > 0) return errors.join(", ");
+  }
+
+  if (hasError(r.response?.data?.status)) {
+    return r.response.data.status.error;
+  }
+
+  return undefined;
+}
+
+// =============================================================
+// Error Classes
+// =============================================================
+
+/** Thrown when Exchange API returns an error response. */
+export class ApiRequestError extends HyperliquidError {
+  readonly response: unknown;
+
+  constructor(response: unknown) {
+    const message = extractErrorMessage(response) ||
+      "An unknown error occurred while processing an API request. See `response` for more details.";
+    super(message);
+    this.name = "ApiRequestError";
+    this.response = response;
+  }
+}
+
+// =============================================================
+// Assertions
+// =============================================================
+
+/** Assert that response is successful, throw ApiRequestError otherwise. */
+export function assertSuccessResponse(response: unknown): void {
+  if (hasErrorStatus(response) || hasStatusesWithErrors(response) || hasSingleStatusWithError(response)) {
+    throw new ApiRequestError(response);
+  }
+}
+
+// =============================================================
+// Type Utilities
+// =============================================================
+
+// deno-lint-ignore ban-types
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Exclude error variants from response type. */
+export type ExcludeErrorResponse<T> = T extends { status: "err" } ? never // with error status
+  : T extends { response: { data: { statuses: ReadonlyArray<infer S> } } } // with multiple statuses
+    ? Exclude<S, { error: unknown }> extends never ? never
+    : Prettify<
+      Omit<T, "response"> & {
+        response: Prettify<Omit<T["response"], "data"> & { data: { statuses: Array<Exclude<S, { error: unknown }>> } }>;
+      }
+    >
+  : T extends { response: { data: { status: infer S } } } // with single status
+    ? S extends { error: unknown } ? never
+    : Prettify<
+      Omit<T, "response"> & {
+        response: Prettify<Omit<T["response"], "data"> & { data: { status: Exclude<S, { error: unknown }> } }>;
+      }
+    >
+  : T;