@nktkas/hyperliquid 0.27.0 → 0.28.0

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

@@ -0,0 +1,342 @@
+import * as v from "valibot";
+import type { HttpTransport } from "../../../../transport/http/mod.js";
+import type { WebSocketTransport } from "../../../../transport/websocket/mod.js";
+import { Address, Hex, UnsignedInteger } from "../../../_schemas.js";
+import {
+  type AbstractWallet,
+  getWalletAddress,
+  getWalletChainId,
+  signL1Action,
+  signMultiSigAction,
+  signUserSignedAction,
+} from "../../../../signing/mod.js";
+import { assertSuccessResponse } from "./errors.js";
+import { defaultNonceManager } from "./_nonce.js";
+import { withLock } from "./_semaphore.js";
+import type { Signature } from "./schemas.js";
+
+// =============================================================
+// Type Utilities
+// =============================================================
+
+type MaybePromise<T> = T | Promise<T>;
+
+// deno-lint-ignore ban-types
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Extract request options from a request type (excludes action, nonce, signature). */
+export type ExtractRequestOptions<T extends { action: Record<string, unknown> }> = Prettify<
+  & { signal?: AbortSignal }
+  & Omit<T, "action" | "nonce" | "signature">
+>;
+
+// =============================================================
+// Config
+// =============================================================
+
+/** Base configuration shared by single-wallet and multi-sig configs. */
+interface BaseConfig<T extends HttpTransport | WebSocketTransport = HttpTransport | WebSocketTransport> {
+  /** The transport used to connect to the Hyperliquid Exchange API. */
+  transport: T;
+
+  /** Signature chain ID for EIP-712 signing, defaults to wallet's chain ID. */
+  signatureChainId?: `0x${string}` | (() => MaybePromise<`0x${string}`>);
+
+  /**
+   * Default vault address for vault-based operations, used when not specified in action options.
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#subaccounts-and-vaults
+   */
+  defaultVaultAddress?: `0x${string}`;
+
+  /**
+   * Default expiration time in milliseconds, used when not specified in action options.
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#expires-after
+   */
+  defaultExpiresAfter?: number | (() => MaybePromise<number>);
+
+  /**
+   * Custom nonce generator function.
+   * Defaults to a global manager using timestamp with auto-increment.
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets#hyperliquid-nonces
+   */
+  nonceManager?: (address: string) => MaybePromise<number>;
+}
+
+/** Configuration for single-wallet Exchange API requests. */
+export interface ExchangeSingleWalletConfig<
+  T extends HttpTransport | WebSocketTransport = HttpTransport | WebSocketTransport,
+> extends BaseConfig<T> {
+  /** The wallet used to sign requests. */
+  wallet: AbstractWallet;
+}
+
+/** Configuration for multi-signature Exchange API requests. */
+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[]];
+  /** The multi-signature account address. */
+  multiSigUser: `0x${string}`;
+}
+
+/** Union type for all Exchange API configurations. */
+export type ExchangeConfig = ExchangeSingleWalletConfig | ExchangeMultiSigConfig;
+
+// =============================================================
+// Execute L1 Action
+// =============================================================
+
+/**
+ * Execute an L1 action on the Hyperliquid Exchange.
+ * Handles both single-wallet and multi-sig signing.
+ */
+export async function executeL1Action<T>(
+  config: ExchangeConfig,
+  action: Record<string, unknown>,
+  options?: {
+    vaultAddress?: string;
+    expiresAfter?: string | number;
+    signal?: AbortSignal;
+  },
+): Promise<T> {
+  const { transport } = config;
+  const leader = getLeader(config);
+  const walletAddress = await getWalletAddress(leader);
+
+  // 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));
+
+    // Validate and resolve options
+    const vaultAddress = v.parse(
+      v.optional(Address),
+      options?.vaultAddress ?? config.defaultVaultAddress,
+    );
+    const expiresAfter = v.parse(
+      v.optional(UnsignedInteger),
+      options?.expiresAfter ??
+        (typeof config.defaultExpiresAfter === "number"
+          ? config.defaultExpiresAfter
+          : await config.defaultExpiresAfter?.()),
+    );
+    const signal = options?.signal;
+
+    // Sign action (multi-sig or single wallet)
+    const [finalAction, signature] = isMultiSig(config)
+      ? await signMultiSigL1(config, action, walletAddress, nonce, vaultAddress, expiresAfter)
+      : [
+        action,
+        await signL1Action({
+          wallet: leader,
+          action,
+          nonce,
+          isTestnet: transport.isTestnet,
+          vaultAddress,
+          expiresAfter,
+        }),
+      ];
+
+    // Send request and validate response
+    const response = await transport.request("exchange", {
+      action: finalAction,
+      signature,
+      nonce,
+      vaultAddress,
+      expiresAfter,
+    }, signal);
+    assertSuccessResponse(response);
+    return response as T;
+  });
+}
+
+// =============================================================
+// Execute User-Signed Action
+// =============================================================
+
+/** Extract nonce field name from EIP-712 types ("nonce" or "time"). */
+function getNonceFieldName(types: Record<string, { name: string; type: string }[]>): "nonce" | "time" {
+  const primaryType = Object.keys(types)[0];
+  const field = types[primaryType].find((f) => f.name === "nonce" || f.name === "time") as {
+    name: "nonce" | "time";
+    type: string;
+  } | undefined;
+  return field?.name ?? "nonce";
+}
+
+/**
+ * Execute a user-signed action (EIP-712) on the Hyperliquid Exchange.
+ * Handles both single-wallet and multi-sig signing.
+ * Automatically adds signatureChainId, hyperliquidChain, and nonce/time.
+ */
+export async function executeUserSignedAction<T>(
+  config: ExchangeConfig,
+  action: Record<string, unknown>,
+  types: Record<string, { name: string; type: string }[]>,
+  options?: {
+    signal?: AbortSignal;
+  },
+): Promise<T> {
+  const { transport } = config;
+  const leader = getLeader(config);
+  const walletAddress = await getWalletAddress(leader);
+
+  // 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 signal = options?.signal;
+
+    // Add system fields for user-signed actions
+    const { type, ...restAction } = action;
+    const nonceFieldName = getNonceFieldName(types);
+    const fullAction = { // key order is important for multi-sig
+      type,
+      signatureChainId: await getSignatureChainId(config),
+      hyperliquidChain: transport.isTestnet ? "Testnet" : "Mainnet",
+      ...restAction,
+      [nonceFieldName]: nonce,
+    };
+
+    // 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 })];
+
+    // Send request and validate response
+    const response = await transport.request("exchange", {
+      action: finalAction,
+      signature,
+      nonce,
+    }, signal);
+    assertSuccessResponse(response);
+    return response as T;
+  });
+}
+
+// =============================================================
+// Multi-sig signing (private)
+// =============================================================
+
+/** Remove leading zeros from signature components (required by Hyperliquid). */
+function trimSignature(sig: Signature): Signature {
+  return {
+    r: sig.r.replace(/^0x0+/, "0x") as `0x${string}`,
+    s: sig.s.replace(/^0x0+/, "0x") as `0x${string}`,
+    v: sig.v,
+  };
+}
+
+/** Sign an L1 action with multi-sig. */
+async function signMultiSigL1(
+  config: ExchangeMultiSigConfig,
+  action: Record<string, unknown>,
+  outerSigner: `0x${string}`,
+  nonce: number,
+  vaultAddress?: `0x${string}`,
+  expiresAfter?: number,
+): Promise<[Record<string, unknown>, Signature]> {
+  const { transport: { isTestnet }, wallet: signers, multiSigUser } = config;
+  const multiSigUser_ = v.parse(Address, multiSigUser);
+  const outerSigner_ = v.parse(Address, outerSigner);
+
+  // Collect signatures from all signers
+  const signatures = await Promise.all(signers.map(async (signer) => {
+    const signature = await signL1Action({
+      wallet: signer,
+      action: [multiSigUser_, outerSigner_, action],
+      nonce,
+      isTestnet,
+      vaultAddress,
+      expiresAfter,
+    });
+    return trimSignature(signature);
+  }));
+
+  // Build multi-sig action wrapper
+  const multiSigAction = {
+    type: "multiSig",
+    signatureChainId: await getSignatureChainId(config),
+    signatures,
+    payload: { multiSigUser: multiSigUser_, outerSigner: outerSigner_, action },
+  };
+
+  // Sign the wrapper with the leader
+  const signature = await signMultiSigAction({
+    wallet: signers[0],
+    action: multiSigAction,
+    nonce,
+    isTestnet,
+    vaultAddress,
+    expiresAfter,
+  });
+
+  return [multiSigAction, signature];
+}
+
+/** Sign a user-signed action (EIP-712) with multi-sig. */
+async function signMultiSigUserSigned(
+  config: ExchangeMultiSigConfig,
+  action: Record<string, unknown> & { signatureChainId: `0x${string}` },
+  types: Record<string, { name: string; type: string }[]>,
+  outerSigner: `0x${string}`,
+  nonce: number,
+): Promise<[Record<string, unknown>, Signature]> {
+  const { wallet: signers, multiSigUser, transport: { isTestnet } } = config;
+  const multiSigUser_ = v.parse(Address, multiSigUser);
+  const outerSigner_ = v.parse(Address, outerSigner);
+
+  // Collect signatures from all signers
+  const signatures = await Promise.all(signers.map(async (signer) => {
+    const signature = await signUserSignedAction({
+      wallet: signer,
+      action: { payloadMultiSigUser: multiSigUser_, outerSigner: outerSigner_, ...action },
+      types,
+    });
+    return trimSignature(signature);
+  }));
+
+  // Build multi-sig action wrapper
+  const multiSigAction = {
+    type: "multiSig",
+    signatureChainId: await getSignatureChainId(config),
+    signatures,
+    payload: { multiSigUser: multiSigUser_, outerSigner: outerSigner_, action },
+  };
+
+  // Sign the wrapper with the leader
+  const signature = await signMultiSigAction({
+    wallet: signers[0],
+    action: multiSigAction,
+    nonce,
+    isTestnet,
+  });
+
+  return [multiSigAction, signature];
+}
+
+// =============================================================
+// Helpers (private)
+// =============================================================
+
+/** 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). */
+function getLeader(config: ExchangeConfig): AbstractWallet {
+  return isMultiSig(config) ? config.wallet[0] : config.wallet;
+}
+
+/** Resolve signature chain ID from config or wallet. */
+async function getSignatureChainId(config: ExchangeConfig): Promise<`0x${string}`> {
+  if (config.signatureChainId) {
+    const id = typeof config.signatureChainId === "function"
+      ? await config.signatureChainId()
+      : config.signatureChainId;
+    return v.parse(Hex, id);
+  }
+  return getWalletChainId(getLeader(config));
+}

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

@@ -0,0 +1,100 @@
+import * as v from "valibot";
+import { Hex, UnsignedInteger } 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 Signature = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** First 32-byte component. */
+      r: v.pipe(
+        v.pipe(Hex, v.length(66)),
+        v.description("First 32-byte component."),
+      ),
+      /** Second 32-byte component. */
+      s: v.pipe(
+        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 Signature = v.InferOutput<typeof Signature>;
+
+/** Nonce (timestamp in ms) used to prevent replay attacks. */
+export const Nonce = /* @__PURE__ */ (() => {
+  return v.pipe(
+    UnsignedInteger,
+    v.description("Nonce (timestamp in ms) used to prevent replay attacks."),
+  );
+})();
+export type Nonce = v.InferOutput<typeof Nonce>;
+
+/** Chain ID in hex format for EIP-712 signing. */
+export const SignatureChainId = /* @__PURE__ */ (() => {
+  return v.pipe(
+    Hex,
+    v.description("Chain ID in hex format for EIP-712 signing."),
+  );
+})();
+export type SignatureChainId = v.InferOutput<typeof SignatureChainId>;
+
+/** HyperLiquid network type. */
+export const HyperliquidChain = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.picklist(["Mainnet", "Testnet"]),
+    v.description("HyperLiquid network type."),
+  );
+})();
+export type HyperliquidChain = v.InferOutput<typeof HyperliquidChain>;

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

@@ -0,0 +1,102 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { UnsignedInteger } from "../../_schemas.js";
+import { ErrorResponse, Nonce, Signature, SuccessResponse } from "./_base/schemas.js";
+
+/**
+ * Enable HIP-3 DEX abstraction.
+ * @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: Nonce,
+      /** ECDSA signature components. */
+      signature: Signature,
+      /** Expiration time of the action. */
+      expiresAfter: v.pipe(
+        v.optional(UnsignedInteger),
+        v.description("Expiration time of the action."),
+      ),
+    }),
+    v.description("Enable HIP-3 DEX abstraction request."),
+  );
+})();
+export type AgentEnableDexAbstractionRequest = v.InferOutput<typeof AgentEnableDexAbstractionRequest>;
+
+/**
+ * Successful response without specific data or error response.
+ * @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."),
+  );
+})();
+export type AgentEnableDexAbstractionResponse = v.InferOutput<typeof AgentEnableDexAbstractionResponse>;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { type ExchangeConfig, executeL1Action, type ExtractRequestOptions } from "./_base/execute.js";
+import type { ExcludeErrorResponse } from "./_base/errors.js";
+
+/** Request options for the {@linkcode agentEnableDexAbstraction} function. */
+export type AgentEnableDexAbstractionOptions = ExtractRequestOptions<
+  v.InferInput<typeof AgentEnableDexAbstractionRequest>
+>;
+
+/** Successful variant of {@linkcode AgentEnableDexAbstractionResponse} without errors. */
+export type AgentEnableDexAbstractionSuccessResponse = ExcludeErrorResponse<AgentEnableDexAbstractionResponse>;
+
+/**
+ * Enable HIP-3 DEX abstraction.
+ *
+ * @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 { agentEnableDexAbstraction } 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 agentEnableDexAbstraction({ transport, wallet });
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#enable-hip-3-dex-abstraction-agent
+ */
+export function agentEnableDexAbstraction(
+  config: ExchangeConfig,
+  opts?: AgentEnableDexAbstractionOptions,
+): Promise<AgentEnableDexAbstractionSuccessResponse> {
+  return executeL1Action(config, { type: "agentEnableDexAbstraction" }, opts);
+}

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

@@ -0,0 +1,148 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+import {
+  ErrorResponse,
+  HyperliquidChain,
+  Nonce,
+  Signature,
+  SignatureChainId,
+  SuccessResponse,
+} from "./_base/schemas.js";
+
+/**
+ * Approve an agent to sign on behalf of the master account.
+ * @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."),
+          ),
+          /** Chain ID in hex format for EIP-712 signing. */
+          signatureChainId: SignatureChainId,
+          /** HyperLiquid network type. */
+          hyperliquidChain: HyperliquidChain,
+          /** Agent address. */
+          agentAddress: v.pipe(
+            Address,
+            v.description("Agent address."),
+          ),
+          /** Agent name or null for unnamed agent (default: null). */
+          agentName: v.pipe(
+            v.optional(v.nullable(v.string()), null),
+            v.description("Agent name or null for unnamed agent."),
+          ),
+          /** Nonce (timestamp in ms) used to prevent replay attacks. */
+          nonce: Nonce,
+        }),
+        v.description("Action to perform."),
+      ),
+      /** Nonce (timestamp in ms) used to prevent replay attacks. */
+      nonce: Nonce,
+      /** ECDSA signature components. */
+      signature: Signature,
+    }),
+    v.description("Approve an agent to sign on behalf of the master account."),
+  );
+})();
+export type ApproveAgentRequest = v.InferOutput<typeof ApproveAgentRequest>;
+
+/**
+ * Successful response without specific data or error response.
+ * @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."),
+  );
+})();
+export type ApproveAgentResponse = v.InferOutput<typeof ApproveAgentResponse>;
+
+// ============================================================
+// 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 ApproveAgentParameters = /* @__PURE__ */ (() => {
+  return v.omit(
+    v.object(ApproveAgentRequest.entries.action.entries),
+    ["type", "signatureChainId", "hyperliquidChain", "nonce"],
+  );
+})();
+/** Action parameters for the {@linkcode approveAgent} function. */
+export type ApproveAgentParameters = v.InferInput<typeof ApproveAgentParameters>;
+
+/** Request options for the {@linkcode approveAgent} function. */
+export type ApproveAgentOptions = ExtractRequestOptions<v.InferInput<typeof ApproveAgentRequest>>;
+
+/** Successful variant of {@linkcode ApproveAgentResponse} without errors. */
+export type ApproveAgentSuccessResponse = ExcludeErrorResponse<ApproveAgentResponse>;
+
+/** EIP-712 types for the {@linkcode approveAgent} function. */
+export const ApproveAgentTypes = {
+  "HyperliquidTransaction:ApproveAgent": [
+    { name: "hyperliquidChain", type: "string" },
+    { name: "agentAddress", type: "address" },
+    { name: "agentName", type: "string" },
+    { name: "nonce", type: "uint64" },
+  ],
+};
+
+/**
+ * Approve an agent to sign on behalf of the master account.
+ *
+ * @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 { approveAgent } 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 approveAgent(
+ *   { transport, wallet },
+ *   { agentAddress: "0x...", agentName: "..." },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#approve-an-api-wallet
+ */
+export function approveAgent(
+  config: ExchangeConfig,
+  params: ApproveAgentParameters,
+  opts?: ApproveAgentOptions,
+): Promise<ApproveAgentSuccessResponse> {
+  const action = v.parse(ApproveAgentParameters, params);
+  return executeUserSignedAction(
+    config,
+    { type: "approveAgent", ...action },
+    ApproveAgentTypes,
+    opts,
+  );
+}