@hfunlabs/hyperliquid 0.27.1 → 0.30.0-hfunlabs.1

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

@@ -0,0 +1,127 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { UnsignedInteger } from "../../_schemas.js";
+import { ErrorResponse, SignatureSchema, SuccessResponse } from "./_base/commonSchemas.js";
+
+/**
+ * Reserve additional rate-limited actions for a fee.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#reserve-additional-actions
+ */
+export const ReserveRequestWeightRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("reserveRequestWeight"),
+            v.description("Type of action."),
+          ),
+          /** Amount of request weight to reserve. */
+          weight: v.pipe(
+            UnsignedInteger,
+            v.maxValue(1844674407370955), // truncated max uint64 / 1000
+            v.description("Amount of request weight to reserve."),
+          ),
+        }),
+        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."),
+      ),
+    }),
+    v.description("Reserve additional rate-limited actions for a fee."),
+  );
+})();
+export type ReserveRequestWeightRequest = v.InferOutput<typeof ReserveRequestWeightRequest>;
+
+/**
+ * Successful response without specific data or error response.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#reserve-additional-actions
+ */
+export const ReserveRequestWeightResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([SuccessResponse, ErrorResponse]),
+    v.description("Successful response without specific data or error response."),
+  );
+})();
+export type ReserveRequestWeightResponse = v.InferOutput<typeof ReserveRequestWeightResponse>;
+
+// ============================================================
+// 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 ReserveRequestWeightParameters = /* @__PURE__ */ (() => {
+  return v.omit(
+    v.object(ReserveRequestWeightRequest.entries.action.entries),
+    ["type"],
+  );
+})();
+/** Action parameters for the {@linkcode reserveRequestWeight} function. */
+export type ReserveRequestWeightParameters = v.InferInput<typeof ReserveRequestWeightParameters>;
+
+/** Request options for the {@linkcode reserveRequestWeight} function. */
+export type ReserveRequestWeightOptions = ExtractRequestOptions<v.InferInput<typeof ReserveRequestWeightRequest>>;
+
+/** Successful variant of {@linkcode ReserveRequestWeightResponse} without errors. */
+export type ReserveRequestWeightSuccessResponse = ExcludeErrorResponse<ReserveRequestWeightResponse>;
+
+/**
+ * Reserve additional rate-limited actions for a fee.
+ *
+ * @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 { reserveRequestWeight } 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 reserveRequestWeight(
+ *   { transport, wallet },
+ *   { weight: 10 },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#reserve-additional-actions
+ */
+export function reserveRequestWeight(
+  config: ExchangeConfig,
+  params: ReserveRequestWeightParameters,
+  opts?: ReserveRequestWeightOptions,
+): Promise<ReserveRequestWeightSuccessResponse> {
+  const action = v.parse(ReserveRequestWeightParameters, params);
+  return executeL1Action(config, { type: "reserveRequestWeight", ...action }, opts);
+}

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

@@ -0,0 +1,153 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address, UnsignedInteger } from "../../_schemas.js";
+import { ErrorResponse, SignatureSchema, SuccessResponse } from "./_base/commonSchemas.js";
+
+/**
+ * Schedule a cancel-all operation at a future time.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#schedule-cancel-dead-mans-switch
+ */
+export const ScheduleCancelRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("scheduleCancel"),
+            v.description("Type of action."),
+          ),
+          /**
+           * Scheduled time (in ms since epoch).
+           * Must be at least 5 seconds in the future.
+           *
+           * If not specified, will cause all scheduled cancel operations to be deleted.
+           */
+          time: v.pipe(
+            v.optional(UnsignedInteger),
+            v.description(
+              "Scheduled time (in ms since epoch)." +
+                "\nMust be at least 5 seconds in the future." +
+                "\n\nIf not specified, will cause all scheduled cancel operations to be deleted.",
+            ),
+          ),
+        }),
+        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("Schedule a cancel-all operation at a future time."),
+  );
+})();
+export type ScheduleCancelRequest = v.InferOutput<typeof ScheduleCancelRequest>;
+
+/**
+ * Successful response without specific data or error response.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#schedule-cancel-dead-mans-switch
+ */
+export const ScheduleCancelResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([SuccessResponse, ErrorResponse]),
+    v.description("Successful response without specific data or error response."),
+  );
+})();
+export type ScheduleCancelResponse = v.InferOutput<typeof ScheduleCancelResponse>;
+
+// ============================================================
+// 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 ScheduleCancelParameters = /* @__PURE__ */ (() => {
+  return v.omit(
+    v.object(ScheduleCancelRequest.entries.action.entries),
+    ["type"],
+  );
+})();
+/** Action parameters for the {@linkcode scheduleCancel} function. */
+export type ScheduleCancelParameters = v.InferInput<typeof ScheduleCancelParameters>;
+
+/** Request options for the {@linkcode scheduleCancel} function. */
+export type ScheduleCancelOptions = ExtractRequestOptions<v.InferInput<typeof ScheduleCancelRequest>>;
+
+/** Successful variant of {@linkcode ScheduleCancelResponse} without errors. */
+export type ScheduleCancelSuccessResponse = ExcludeErrorResponse<ScheduleCancelResponse>;
+
+/**
+ * Schedule a cancel-all operation at a future time.
+ *
+ * @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 { scheduleCancel } 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 scheduleCancel(
+ *   { transport, wallet },
+ *   { time: Date.now() + 10_000 },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#schedule-cancel-dead-mans-switch
+ */
+export function scheduleCancel(
+  config: ExchangeConfig,
+  params?: ScheduleCancelParameters,
+  opts?: ScheduleCancelOptions,
+): Promise<ScheduleCancelSuccessResponse>;
+export function scheduleCancel(
+  config: ExchangeConfig,
+  opts?: ScheduleCancelOptions,
+): Promise<ScheduleCancelSuccessResponse>;
+export function scheduleCancel(
+  config: ExchangeConfig,
+  paramsOrOpts?: ScheduleCancelParameters | ScheduleCancelOptions,
+  maybeOpts?: ScheduleCancelOptions,
+): Promise<ScheduleCancelSuccessResponse> {
+  const isFirstArgParams = paramsOrOpts && "time" in paramsOrOpts;
+  const params = isFirstArgParams ? paramsOrOpts : {};
+  const opts = isFirstArgParams ? maybeOpts : paramsOrOpts as ScheduleCancelOptions;
+
+  const action = v.parse(ScheduleCancelParameters, params);
+  return executeL1Action(config, { type: "scheduleCancel", ...action }, opts);
+}

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

@@ -0,0 +1,189 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address, Hex, UnsignedDecimal, UnsignedInteger } from "../../_schemas.js";
+import { ErrorResponse, HyperliquidChainSchema, SignatureSchema, SuccessResponse } from "./_base/commonSchemas.js";
+
+/**
+ * Transfer tokens between different perp DEXs, spot balance, users, and/or sub-accounts.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#send-asset
+ */
+export const SendAssetRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("sendAsset"),
+            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."),
+          ),
+          /** Destination address. */
+          destination: v.pipe(
+            Address,
+            v.description("Destination address."),
+          ),
+          /** Source DEX ("" for default USDC perp DEX, "spot" for spot). */
+          sourceDex: v.pipe(
+            v.string(),
+            v.description('Source DEX ("" for default USDC perp DEX, "spot" for spot).'),
+          ),
+          /** Destination DEX ("" for default USDC perp DEX, "spot" for spot). */
+          destinationDex: v.pipe(
+            v.string(),
+            v.description('Destination DEX ("" for default USDC perp DEX, "spot" for spot).'),
+          ),
+          /** Token identifier. */
+          token: v.pipe(
+            v.string(),
+            v.description("Token identifier."),
+          ),
+          /** Amount to send (not in wei). */
+          amount: v.pipe(
+            UnsignedDecimal,
+            v.description("Amount to send (not in wei)."),
+          ),
+          /** Source sub-account address ("" for main account). */
+          fromSubAccount: v.pipe(
+            v.optional(
+              v.union([v.literal(""), Address]),
+              "",
+            ),
+            v.description('Source sub-account address ("" for main account).'),
+          ),
+          /** 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."),
+      ),
+      /** 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."),
+      ),
+    }),
+    v.description("Transfer tokens between different perp DEXs, spot balance, users, and/or sub-accounts."),
+  );
+})();
+export type SendAssetRequest = v.InferOutput<typeof SendAssetRequest>;
+
+/**
+ * Successful response without specific data or error response.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#send-asset
+ */
+export const SendAssetResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([SuccessResponse, ErrorResponse]),
+    v.description("Successful response without specific data or error response."),
+  );
+})();
+export type SendAssetResponse = v.InferOutput<typeof SendAssetResponse>;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { type ExchangeConfig, executeUserSignedAction, type ExtractRequestOptions } from "./_base/execute.js";
+import type { ExcludeErrorResponse } from "./_base/errors.js";
+
+/** Schema for user-provided action parameters (excludes system fields). */
+const SendAssetParameters = /* @__PURE__ */ (() => {
+  return v.omit(
+    v.object(SendAssetRequest.entries.action.entries),
+    ["type", "signatureChainId", "hyperliquidChain", "nonce"],
+  );
+})();
+/** Action parameters for the {@linkcode sendAsset} function. */
+export type SendAssetParameters = v.InferInput<typeof SendAssetParameters>;
+
+/** Request options for the {@linkcode sendAsset} function. */
+export type SendAssetOptions = ExtractRequestOptions<v.InferInput<typeof SendAssetRequest>>;
+
+/** Successful variant of {@linkcode SendAssetResponse} without errors. */
+export type SendAssetSuccessResponse = ExcludeErrorResponse<SendAssetResponse>;
+
+/** EIP-712 types for the {@linkcode sendAsset} function. */
+export const SendAssetTypes = {
+  "HyperliquidTransaction:SendAsset": [
+    { name: "hyperliquidChain", type: "string" },
+    { name: "destination", type: "string" },
+    { name: "sourceDex", type: "string" },
+    { name: "destinationDex", type: "string" },
+    { name: "token", type: "string" },
+    { name: "amount", type: "string" },
+    { name: "fromSubAccount", type: "string" },
+    { name: "nonce", type: "uint64" },
+  ],
+};
+
+/**
+ * Transfer tokens between different perp DEXs, spot balance, users, and/or sub-accounts.
+ *
+ * @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 { sendAsset } 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 sendAsset(
+ *   { transport, wallet },
+ *   {
+ *     destination: "0x0000000000000000000000000000000000000001",
+ *     sourceDex: "",
+ *     destinationDex: "test",
+ *     token: "USDC:0xeb62eee3685fc4c43992febcd9e75443",
+ *     amount: "1",
+ *   },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#send-asset
+ */
+export function sendAsset(
+  config: ExchangeConfig,
+  params: SendAssetParameters,
+  opts?: SendAssetOptions,
+): Promise<SendAssetSuccessResponse> {
+  const action = v.parse(SendAssetParameters, params);
+  return executeUserSignedAction(
+    config,
+    { type: "sendAsset", ...action },
+    SendAssetTypes,
+    opts,
+  );
+}

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

@@ -0,0 +1,125 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { UnsignedInteger } from "../../_schemas.js";
+import { ErrorResponse, SignatureSchema, SuccessResponse } from "./_base/commonSchemas.js";
+
+/** Set the display name in the leaderboard. */
+export const SetDisplayNameRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("setDisplayName"),
+            v.description("Type of action."),
+          ),
+          /**
+           * Display name.
+           * Set to an empty string to remove the display name.
+           */
+          displayName: v.pipe(
+            v.string(),
+            v.maxLength(20),
+            v.description(
+              "Display name." +
+                "\nSet to an empty string to remove the display name.",
+            ),
+          ),
+        }),
+        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."),
+      ),
+    }),
+    v.description("Set the display name in the leaderboard."),
+  );
+})();
+export type SetDisplayNameRequest = v.InferOutput<typeof SetDisplayNameRequest>;
+
+/** Successful response without specific data or error response. */
+export const SetDisplayNameResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([SuccessResponse, ErrorResponse]),
+    v.description("Successful response without specific data or error response."),
+  );
+})();
+export type SetDisplayNameResponse = v.InferOutput<typeof SetDisplayNameResponse>;
+
+// ============================================================
+// 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 SetDisplayNameParameters = /* @__PURE__ */ (() => {
+  return v.omit(
+    v.object(SetDisplayNameRequest.entries.action.entries),
+    ["type"],
+  );
+})();
+/** Action parameters for the {@linkcode setDisplayName} function. */
+export type SetDisplayNameParameters = v.InferInput<typeof SetDisplayNameParameters>;
+
+/** Request options for the {@linkcode setDisplayName} function. */
+export type SetDisplayNameOptions = ExtractRequestOptions<v.InferInput<typeof SetDisplayNameRequest>>;
+
+/** Successful variant of {@linkcode SetDisplayNameResponse} without errors. */
+export type SetDisplayNameSuccessResponse = ExcludeErrorResponse<SetDisplayNameResponse>;
+
+/**
+ * Set the display name in the leaderboard.
+ *
+ * @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 { setDisplayName } 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 setDisplayName(
+ *   { transport, wallet },
+ *   { displayName: "..." },
+ * );
+ * ```
+ */
+export function setDisplayName(
+  config: ExchangeConfig,
+  params: SetDisplayNameParameters,
+  opts?: SetDisplayNameOptions,
+): Promise<SetDisplayNameSuccessResponse> {
+  const action = v.parse(SetDisplayNameParameters, params);
+  return executeL1Action(config, { type: "setDisplayName", ...action }, opts);
+}