@nktkas/hyperliquid 0.25.8 → 0.26.0

package/src/api/exchange/updateLeverage.ts

@@ -0,0 +1,131 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser, UnsignedInteger } from "../_base.ts";
+import {
+  type ExchangeRequestConfig,
+  executeL1Action,
+  type ExtractRequestAction,
+  type ExtractRequestOptions,
+  type MultiSignRequestConfig,
+  Signature,
+} from "./_base/mod.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Update cross or isolated leverage on a coin.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#update-leverage
+ */
+export const UpdateLeverageRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("updateLeverage"),
+            v.description("Type of action."),
+          ),
+          /** Asset ID. */
+          asset: v.pipe(
+            UnsignedInteger,
+            v.description("Asset ID."),
+          ),
+          /** `true` for cross leverage, `false` for isolated leverage. */
+          isCross: v.pipe(
+            v.boolean(),
+            v.description("`true` for cross leverage, `false` for isolated leverage."),
+          ),
+          /** New leverage value. */
+          leverage: v.pipe(
+            v.pipe(UnsignedInteger, v.minValue(1)),
+            v.description("New leverage value."),
+          ),
+        }),
+        v.description("Action to perform."),
+      ),
+      /** Unique request identifier (current timestamp in ms). */
+      nonce: v.pipe(
+        UnsignedInteger,
+        v.description("Unique request identifier (current timestamp in ms)."),
+      ),
+      /** Cryptographic signature. */
+      signature: v.pipe(
+        Signature,
+        v.description("Cryptographic signature."),
+      ),
+      /** 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("Update cross or isolated leverage on a coin."),
+  );
+})();
+export type UpdateLeverageRequest = v.InferOutput<typeof UpdateLeverageRequest>;
+
+import { SuccessResponse } from "./_base/mod.ts";
+export { SuccessResponse };
+
+// -------------------- Function --------------------
+
+/** Action parameters for the {@linkcode updateLeverage} function. */
+export type UpdateLeverageParameters = ExtractRequestAction<v.InferInput<typeof UpdateLeverageRequest>>;
+/** Request options for the {@linkcode updateLeverage} function. */
+export type UpdateLeverageOptions = ExtractRequestOptions<v.InferInput<typeof UpdateLeverageRequest>>;
+
+/**
+ * Update cross or isolated leverage on a coin.
+ * @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 {ApiRequestError} When the API returns an unsuccessful response.
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#update-leverage
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { updateLeverage } 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 updateLeverage(
+ *   { transport, wallet },
+ *   { asset: 0, isCross: true, leverage: 5 },
+ * );
+ * ```
+ */
+export async function updateLeverage(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  params: DeepImmutable<UpdateLeverageParameters>,
+  opts?: UpdateLeverageOptions,
+): Promise<SuccessResponse> {
+  const request = parser(UpdateLeverageRequest)({
+    action: {
+      type: "updateLeverage",
+      ...params,
+    },
+    nonce: 0, // Placeholder; actual nonce generated in `executeL1Action`
+    signature: { // Placeholder; actual signature generated in `executeL1Action`
+      r: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      s: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      v: 27,
+    },
+    vaultAddress: opts?.vaultAddress ?? config.defaultVaultAddress,
+    expiresAfter: typeof config.defaultExpiresAfter === "number"
+      ? config.defaultExpiresAfter
+      : await config.defaultExpiresAfter?.(),
+  });
+  return await executeL1Action(config, request, opts?.signal);
+}

package/src/api/exchange/usdClassTransfer.ts

@@ -0,0 +1,141 @@
+import * as v from "valibot";
+import { type DeepImmutable, Hex, parser, UnsignedDecimal, UnsignedInteger } from "../_base.ts";
+import {
+  type ExchangeRequestConfig,
+  executeUserSignedAction,
+  type ExtractRequestAction,
+  type ExtractRequestOptions,
+  getSignatureChainId,
+  type MultiSignRequestConfig,
+  Signature,
+} from "./_base/mod.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Transfer funds between Spot account and Perp account.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#transfer-from-spot-account-to-perp-account-and-vice-versa
+ */
+export const UsdClassTransferRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("usdClassTransfer"),
+            v.description("Type of action."),
+          ),
+          /** Chain ID used for signing. */
+          signatureChainId: v.pipe(
+            Hex,
+            v.description("Chain ID used for signing."),
+          ),
+          /** HyperLiquid network. */
+          hyperliquidChain: v.pipe(
+            v.union([v.literal("Mainnet"), v.literal("Testnet")]),
+            v.description("HyperLiquid network."),
+          ),
+          /** Amount to transfer (1 = $1). */
+          amount: v.pipe(
+            UnsignedDecimal,
+            v.description("Amount to transfer (1 = $1)."),
+          ),
+          /** `true` for Spot to Perp, `false` for Perp to Spot. */
+          toPerp: v.pipe(
+            v.boolean(),
+            v.description("`true` for Spot to Perp, `false` for Perp to Spot."),
+          ),
+          /** Unique request identifier (current timestamp in ms). */
+          nonce: v.pipe(
+            UnsignedInteger,
+            v.description("Unique request identifier (current timestamp in ms)."),
+          ),
+        }),
+        v.description("Action to perform."),
+      ),
+      /** Unique request identifier (current timestamp in ms). */
+      nonce: v.pipe(
+        UnsignedInteger,
+        v.description("Unique request identifier (current timestamp in ms)."),
+      ),
+      /** Cryptographic signature. */
+      signature: v.pipe(
+        Signature,
+        v.description("Cryptographic signature."),
+      ),
+    }),
+    v.description("Transfer funds between Spot account and Perp account."),
+  );
+})();
+export type UsdClassTransferRequest = v.InferOutput<typeof UsdClassTransferRequest>;
+
+import { SuccessResponse } from "./_base/mod.ts";
+export { SuccessResponse };
+
+// -------------------- Function --------------------
+
+/** Action parameters for the {@linkcode usdClassTransfer} function. */
+export type UsdClassTransferParameters = ExtractRequestAction<v.InferInput<typeof UsdClassTransferRequest>>;
+/** Request options for the {@linkcode usdClassTransfer} function. */
+export type UsdClassTransferOptions = ExtractRequestOptions<v.InferInput<typeof UsdClassTransferRequest>>;
+
+/** EIP-712 types for the {@linkcode usdClassTransfer} function. */
+export const UsdClassTransferTypes = {
+  "HyperliquidTransaction:UsdClassTransfer": [
+    { name: "hyperliquidChain", type: "string" },
+    { name: "amount", type: "string" },
+    { name: "toPerp", type: "bool" },
+    { name: "nonce", type: "uint64" },
+  ],
+};
+
+/**
+ * Transfer funds between Spot account and Perp 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 {ApiRequestError} When the API returns an unsuccessful response.
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#transfer-from-spot-account-to-perp-account-and-vice-versa
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { usdClassTransfer } 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 usdClassTransfer(
+ *   { transport, wallet },
+ *   { amount: "1", toPerp: true },
+ * );
+ * ```
+ */
+export async function usdClassTransfer(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  params: DeepImmutable<UsdClassTransferParameters>,
+  opts?: UsdClassTransferOptions,
+): Promise<SuccessResponse> {
+  const request = parser(UsdClassTransferRequest)({
+    action: {
+      type: "usdClassTransfer",
+      hyperliquidChain: config.transport.isTestnet ? "Testnet" : "Mainnet",
+      signatureChainId: await getSignatureChainId(config),
+      nonce: 0, // Placeholder; actual nonce generated in `executeUserSignedAction` to prevent race conditions
+      ...params,
+    },
+    nonce: 0, // Placeholder; actual nonce generated in `executeUserSignedAction` to prevent race conditions
+    signature: { // Placeholder; actual signature generated in `executeUserSignedAction`
+      r: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      s: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      v: 27,
+    },
+  });
+  return await executeUserSignedAction(config, request, UsdClassTransferTypes, opts?.signal);
+}

package/src/api/exchange/usdSend.ts

@@ -0,0 +1,141 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, Hex, parser, UnsignedDecimal, UnsignedInteger } from "../_base.ts";
+import {
+  type ExchangeRequestConfig,
+  executeUserSignedAction,
+  type ExtractRequestAction,
+  type ExtractRequestOptions,
+  getSignatureChainId,
+  type MultiSignRequestConfig,
+  Signature,
+} from "./_base/mod.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Send usd to another address.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#core-usdc-transfer
+ */
+export const UsdSendRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("usdSend"),
+            v.description("Type of action."),
+          ),
+          /** Chain ID used for signing. */
+          signatureChainId: v.pipe(
+            Hex,
+            v.description("Chain ID used for signing."),
+          ),
+          /** HyperLiquid network. */
+          hyperliquidChain: v.pipe(
+            v.union([v.literal("Mainnet"), v.literal("Testnet")]),
+            v.description("HyperLiquid network."),
+          ),
+          /** Destination address. */
+          destination: v.pipe(
+            Address,
+            v.description("Destination address."),
+          ),
+          /** Amount to send (1 = $1). */
+          amount: v.pipe(
+            UnsignedDecimal,
+            v.description("Amount to send (1 = $1)."),
+          ),
+          /** Unique request identifier (current timestamp in ms). */
+          time: v.pipe(
+            UnsignedInteger,
+            v.description("Unique request identifier (current timestamp in ms)."),
+          ),
+        }),
+        v.description("Action to perform."),
+      ),
+      /** Unique request identifier (current timestamp in ms). */
+      nonce: v.pipe(
+        UnsignedInteger,
+        v.description("Unique request identifier (current timestamp in ms)."),
+      ),
+      /** Cryptographic signature. */
+      signature: v.pipe(
+        Signature,
+        v.description("Cryptographic signature."),
+      ),
+    }),
+    v.description("Send usd to another address."),
+  );
+})();
+export type UsdSendRequest = v.InferOutput<typeof UsdSendRequest>;
+
+import { SuccessResponse } from "./_base/mod.ts";
+export { SuccessResponse };
+
+// -------------------- Function --------------------
+
+/** Action parameters for the {@linkcode usdSend} function. */
+export type UsdSendParameters = ExtractRequestAction<v.InferInput<typeof UsdSendRequest>>;
+/** Request options for the {@linkcode usdSend} function. */
+export type UsdSendOptions = ExtractRequestOptions<v.InferInput<typeof UsdSendRequest>>;
+
+/** EIP-712 types for the {@linkcode usdSend} function. */
+export const UsdSendTypes = {
+  "HyperliquidTransaction:UsdSend": [
+    { name: "hyperliquidChain", type: "string" },
+    { name: "destination", type: "string" },
+    { name: "amount", type: "string" },
+    { name: "time", type: "uint64" },
+  ],
+};
+
+/**
+ * Send usd to another address.
+ * @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 {ApiRequestError} When the API returns an unsuccessful response.
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#core-usdc-transfer
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { usdSend } 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 usdSend(
+ *   { transport, wallet },
+ *   { destination: "0x...", amount: "1" },
+ * );
+ * ```
+ */
+export async function usdSend(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  params: DeepImmutable<UsdSendParameters>,
+  opts?: UsdSendOptions,
+): Promise<SuccessResponse> {
+  const request = parser(UsdSendRequest)({
+    action: {
+      type: "usdSend",
+      hyperliquidChain: config.transport.isTestnet ? "Testnet" : "Mainnet",
+      signatureChainId: await getSignatureChainId(config),
+      time: 0, // Placeholder; actual nonce generated in `executeUserSignedAction` to prevent race conditions
+      ...params,
+    },
+    nonce: 0, // Placeholder; actual nonce generated in `executeUserSignedAction` to prevent race conditions
+    signature: { // Placeholder; actual signature generated in `executeUserSignedAction`
+      r: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      s: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      v: 27,
+    },
+  });
+  return await executeUserSignedAction(config, request, UsdSendTypes, opts?.signal);
+}

package/src/api/exchange/userDexAbstraction.ts

@@ -0,0 +1,145 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, Hex, parser, UnsignedInteger } from "../_base.ts";
+import {
+  type ExchangeRequestConfig,
+  executeUserSignedAction,
+  type ExtractRequestAction,
+  type ExtractRequestOptions,
+  getSignatureChainId,
+  type MultiSignRequestConfig,
+  Signature,
+} from "./_base/mod.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Enable/disable HIP-3 DEX abstraction.
+ * @see null
+ */
+export const UserDexAbstractionExchangeRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("userDexAbstraction"),
+            v.description("Type of action."),
+          ),
+          /** Chain ID used for signing. */
+          signatureChainId: v.pipe(
+            Hex,
+            v.description("Chain ID used for signing."),
+          ),
+          /** HyperLiquid network. */
+          hyperliquidChain: v.pipe(
+            v.union([v.literal("Mainnet"), v.literal("Testnet")]),
+            v.description("HyperLiquid network."),
+          ),
+          /** User address. */
+          user: v.pipe(
+            Address,
+            v.description("User address."),
+          ),
+          /** Whether to enable or disable HIP-3 DEX abstraction. */
+          enabled: v.pipe(
+            v.boolean(),
+            v.description("Whether to enable or disable HIP-3 DEX abstraction."),
+          ),
+          /** Unique request identifier (current timestamp in ms). */
+          nonce: v.pipe(
+            UnsignedInteger,
+            v.description("Unique request identifier (current timestamp in ms)."),
+          ),
+        }),
+        v.description("Action to perform."),
+      ),
+      /** Unique request identifier (current timestamp in ms). */
+      nonce: v.pipe(
+        UnsignedInteger,
+        v.description("Unique request identifier (current timestamp in ms)."),
+      ),
+      /** Cryptographic signature. */
+      signature: v.pipe(
+        Signature,
+        v.description("Cryptographic signature."),
+      ),
+    }),
+    v.description("Enable/disable HIP-3 DEX abstraction."),
+  );
+})();
+export type UserDexAbstractionExchangeRequest = v.InferOutput<typeof UserDexAbstractionExchangeRequest>;
+
+import { SuccessResponse } from "./_base/mod.ts";
+export { SuccessResponse };
+
+// -------------------- Function --------------------
+
+/** Action parameters for the {@linkcode userDexAbstraction} function. */
+export type UserDexAbstractionExchangeParameters = ExtractRequestAction<
+  v.InferInput<typeof UserDexAbstractionExchangeRequest>
+>;
+/** Request options for the {@linkcode userDexAbstraction} function. */
+export type UserDexAbstractionExchangeOptions = ExtractRequestOptions<
+  v.InferInput<typeof UserDexAbstractionExchangeRequest>
+>;
+
+/** EIP-712 types for the {@linkcode userDexAbstraction} function. */
+export const UserDexAbstractionTypes = {
+  "HyperliquidTransaction:UserDexAbstraction": [
+    { name: "hyperliquidChain", type: "string" },
+    { name: "user", type: "address" },
+    { name: "enabled", type: "bool" },
+    { name: "nonce", type: "uint64" },
+  ],
+};
+
+/**
+ * Enable/disable 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 {ApiRequestError} When the API returns an unsuccessful response.
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see null
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { userDexAbstraction } 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 userDexAbstraction(
+ *   { transport, wallet },
+ *   { user: "0x...", enabled: true },
+ * );
+ * ```
+ */
+export async function userDexAbstraction(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  params: DeepImmutable<UserDexAbstractionExchangeParameters>,
+  opts?: UserDexAbstractionExchangeOptions,
+): Promise<SuccessResponse> {
+  const request = parser(UserDexAbstractionExchangeRequest)({
+    action: {
+      type: "userDexAbstraction",
+      hyperliquidChain: config.transport.isTestnet ? "Testnet" : "Mainnet",
+      signatureChainId: await getSignatureChainId(config),
+      nonce: 0, // Placeholder; actual nonce generated in `executeUserSignedAction` to prevent race conditions
+      ...params,
+    },
+    nonce: 0, // Placeholder; actual nonce generated in `executeUserSignedAction` to prevent race conditions
+    signature: { // Placeholder; actual signature generated in `executeUserSignedAction`
+      r: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      s: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      v: 27,
+    },
+  });
+  return await executeUserSignedAction(config, request, UserDexAbstractionTypes, opts?.signal);
+}

package/src/api/exchange/vaultDistribute.ts

@@ -0,0 +1,127 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser, UnsignedInteger } from "../_base.ts";
+import {
+  type ExchangeRequestConfig,
+  executeL1Action,
+  type ExtractRequestAction,
+  type ExtractRequestOptions,
+  type MultiSignRequestConfig,
+  Signature,
+} from "./_base/mod.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Distribute funds from a vault between followers.
+ * @see null
+ */
+export const VaultDistributeRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("vaultDistribute"),
+            v.description("Type of action."),
+          ),
+          /** Vault address. */
+          vaultAddress: v.pipe(
+            Address,
+            v.description("Vault address."),
+          ),
+          /**
+           * Amount to distribute (float * 1e6).
+           *
+           * Set to 0 to close the vault.
+           */
+          usd: v.pipe(
+            UnsignedInteger,
+            v.description(
+              "Amount to distribute (float * 1e6)." +
+                "\n\nSet to 0 to close the vault.",
+            ),
+          ),
+        }),
+        v.description("Action to perform."),
+      ),
+      /** Unique request identifier (current timestamp in ms). */
+      nonce: v.pipe(
+        UnsignedInteger,
+        v.description("Unique request identifier (current timestamp in ms)."),
+      ),
+      /** Cryptographic signature. */
+      signature: v.pipe(
+        Signature,
+        v.description("Cryptographic signature."),
+      ),
+      /** Expiration time of the action. */
+      expiresAfter: v.pipe(
+        v.optional(UnsignedInteger),
+        v.description("Expiration time of the action."),
+      ),
+    }),
+    v.description("Distribute funds from a vault between followers."),
+  );
+})();
+export type VaultDistributeRequest = v.InferOutput<typeof VaultDistributeRequest>;
+
+import { SuccessResponse } from "./_base/mod.ts";
+export { SuccessResponse };
+
+// -------------------- Function --------------------
+
+/** Action parameters for the {@linkcode vaultDistribute} function. */
+export type VaultDistributeParameters = ExtractRequestAction<v.InferInput<typeof VaultDistributeRequest>>;
+/** Request options for the {@linkcode vaultDistribute} function. */
+export type VaultDistributeOptions = ExtractRequestOptions<v.InferInput<typeof VaultDistributeRequest>>;
+
+/**
+ * Distribute funds from a vault between followers.
+ * @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 {ApiRequestError} When the API returns an unsuccessful response.
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see null
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { vaultDistribute } 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 vaultDistribute(
+ *   { transport, wallet },
+ *   { vaultAddress: "0x...", usd: 10 * 1e6 },
+ * );
+ * ```
+ */
+export async function vaultDistribute(
+  config: ExchangeRequestConfig | MultiSignRequestConfig,
+  params: DeepImmutable<VaultDistributeParameters>,
+  opts?: VaultDistributeOptions,
+): Promise<SuccessResponse> {
+  const request = parser(VaultDistributeRequest)({
+    action: {
+      type: "vaultDistribute",
+      ...params,
+    },
+    nonce: 0, // Placeholder; actual nonce generated in `executeL1Action`
+    signature: { // Placeholder; actual signature generated in `executeL1Action`
+      r: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      s: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      v: 27,
+    },
+    expiresAfter: typeof config.defaultExpiresAfter === "number"
+      ? config.defaultExpiresAfter
+      : await config.defaultExpiresAfter?.(),
+  });
+  return await executeL1Action(config, request, opts?.signal);
+}