@hfunlabs/hyperliquid 0.27.1-hfunlabs.5 → 0.29.1-hfunlabs.1

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

@@ -0,0 +1,231 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address, Hex, UnsignedDecimal, UnsignedInteger } from "../../_schemas.js";
+import { ErrorResponse, Nonce, Signature, SuccessResponse } from "./_base/schemas.js";
+
+/**
+ * Modify an order.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#modify-an-order
+ */
+export const ModifyRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("modify"),
+            v.description("Type of action."),
+          ),
+          /** Order ID or Client Order ID. */
+          oid: v.pipe(
+            v.union([
+              UnsignedInteger,
+              v.pipe(Hex, v.length(34)),
+            ]),
+            v.description("Order ID or Client Order ID."),
+          ),
+          /** New order parameters. */
+          order: v.pipe(
+            v.object({
+              /** Asset ID. */
+              a: v.pipe(
+                UnsignedInteger,
+                v.description("Asset ID."),
+              ),
+              /** Position side (`true` for long, `false` for short). */
+              b: v.pipe(
+                v.boolean(),
+                v.description("Position side (`true` for long, `false` for short)."),
+              ),
+              /** Price. */
+              p: v.pipe(
+                UnsignedDecimal,
+                v.description("Price."),
+              ),
+              /** Size (in base currency units). */
+              s: v.pipe(
+                UnsignedDecimal,
+                v.description("Size (in base currency units)."),
+              ),
+              /** Is reduce-only? */
+              r: v.pipe(
+                v.boolean(),
+                v.description("Is reduce-only?"),
+              ),
+              /** Order type. */
+              t: v.pipe(
+                v.union([
+                  v.object({
+                    /** Limit order parameters. */
+                    limit: v.pipe(
+                      v.object({
+                        /**
+                         * Time-in-force.
+                         * - `"Gtc"`: Remains active until filled or canceled.
+                         * - `"Ioc"`: Fills immediately or cancels any unfilled portion.
+                         * - `"Alo"`: Adds liquidity only.
+                         * - `"FrontendMarket"`: Similar to Ioc, used in Hyperliquid UI.
+                         * - `"LiquidationMarket"`: Similar to Ioc, used in Hyperliquid UI.
+                         */
+                        tif: v.pipe(
+                          v.picklist(["Gtc", "Ioc", "Alo", "FrontendMarket", "LiquidationMarket"]),
+                          v.description(
+                            "Time-in-force." +
+                              '\n- `"Gtc"`: Remains active until filled or canceled.' +
+                              '\n- `"Ioc"`: Fills immediately or cancels any unfilled portion.' +
+                              '\n- `"Alo"`: Adds liquidity only.' +
+                              '\n- `"FrontendMarket"`: Similar to Ioc, used in Hyperliquid UI.' +
+                              '\n- `"LiquidationMarket"`: Similar to Ioc, used in Hyperliquid UI.',
+                          ),
+                        ),
+                      }),
+                      v.description("Limit order parameters."),
+                    ),
+                  }),
+                  v.object({
+                    /** Trigger order parameters. */
+                    trigger: v.pipe(
+                      v.object({
+                        /** Is market order? */
+                        isMarket: v.pipe(
+                          v.boolean(),
+                          v.description("Is market order?"),
+                        ),
+                        /** Trigger price. */
+                        triggerPx: v.pipe(
+                          UnsignedDecimal,
+                          v.description("Trigger price."),
+                        ),
+                        /** Indicates whether it is take profit or stop loss. */
+                        tpsl: v.pipe(
+                          v.picklist(["tp", "sl"]),
+                          v.description("Indicates whether it is take profit or stop loss."),
+                        ),
+                      }),
+                      v.description("Trigger order parameters."),
+                    ),
+                  }),
+                ]),
+                v.description("Order type."),
+              ),
+              /** Client Order ID. */
+              c: v.pipe(
+                v.optional(v.pipe(Hex, v.length(34))),
+                v.description("Client Order ID."),
+              ),
+            }),
+            v.description("New order parameters."),
+          ),
+        }),
+        v.description("Action to perform."),
+      ),
+      /** Nonce (timestamp in ms) used to prevent replay attacks. */
+      nonce: Nonce,
+      /** ECDSA signature components. */
+      signature: 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("Modify an order."),
+  );
+})();
+export type ModifyRequest = v.InferOutput<typeof ModifyRequest>;
+
+/**
+ * Successful response without specific data or error response.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#modify-an-order
+ */
+export const ModifyResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([SuccessResponse, ErrorResponse]),
+    v.description("Successful response without specific data or error response."),
+  );
+})();
+export type ModifyResponse = v.InferOutput<typeof ModifyResponse>;
+
+// ============================================================
+// 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 ModifyParameters = /* @__PURE__ */ (() => {
+  return v.omit(
+    v.object(ModifyRequest.entries.action.entries),
+    ["type"],
+  );
+})();
+/** Action parameters for the {@linkcode modify} function. */
+export type ModifyParameters = v.InferInput<typeof ModifyParameters>;
+
+/** Request options for the {@linkcode modify} function. */
+export type ModifyOptions = ExtractRequestOptions<v.InferInput<typeof ModifyRequest>>;
+
+/** Successful variant of {@linkcode ModifyResponse} without errors. */
+export type ModifySuccessResponse = ExcludeErrorResponse<ModifyResponse>;
+
+/**
+ * Modify an order.
+ *
+ * @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 { modify } 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 modify(
+ *   { transport, wallet },
+ *   {
+ *     oid: 123,
+ *     order: {
+ *       a: 0,
+ *       b: true,
+ *       p: "31000",
+ *       s: "0.2",
+ *       r: false,
+ *       t: { limit: { tif: "Gtc" } },
+ *       c: "0x...",
+ *     },
+ *   },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#modify-an-order
+ */
+export function modify(
+  config: ExchangeConfig,
+  params: ModifyParameters,
+  opts?: ModifyOptions,
+): Promise<ModifySuccessResponse> {
+  const action = v.parse(ModifyParameters, params);
+  return executeL1Action(config, { type: "modify", ...action }, opts);
+}

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

@@ -0,0 +1,100 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { UnsignedInteger } from "../../_schemas.js";
+import { ErrorResponse, Nonce, Signature, SuccessResponse } from "./_base/schemas.js";
+
+/**
+ * This action does not do anything (no operation), but causes the nonce to be marked as used.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#invalidate-pending-nonce-noop
+ */
+export const NoopRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("noop"),
+            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("This action does not do anything (no operation), but causes the nonce to be marked as used."),
+  );
+})();
+export type NoopRequest = v.InferOutput<typeof NoopRequest>;
+
+/**
+ * Successful response without specific data or error response.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#invalidate-pending-nonce-noop
+ */
+export const NoopResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([SuccessResponse, ErrorResponse]),
+    v.description("Successful response without specific data or error response."),
+  );
+})();
+export type NoopResponse = v.InferOutput<typeof NoopResponse>;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { type ExchangeConfig, executeL1Action, type ExtractRequestOptions } from "./_base/execute.js";
+import type { ExcludeErrorResponse } from "./_base/errors.js";
+
+/** Request options for the {@linkcode noop} function. */
+export type NoopOptions = ExtractRequestOptions<v.InferInput<typeof NoopRequest>>;
+
+/** Successful variant of {@linkcode NoopResponse} without errors. */
+export type NoopSuccessResponse = ExcludeErrorResponse<NoopResponse>;
+
+/**
+ * This action does not do anything (no operation), but causes the nonce to be marked as used.
+ *
+ * @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 { noop } 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 noop({ transport, wallet });
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#invalidate-pending-nonce-noop
+ */
+export function noop(
+  config: ExchangeConfig,
+  opts?: NoopOptions,
+): Promise<NoopSuccessResponse> {
+  return executeL1Action(config, { type: "noop" }, opts);
+}

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

@@ -0,0 +1,345 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address, Hex, UnsignedDecimal, UnsignedInteger } from "../../_schemas.js";
+import { Nonce, Signature } from "./_base/schemas.js";
+
+/**
+ * Place an order(s).
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#place-an-order
+ */
+export const OrderRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Action to perform. */
+      action: v.pipe(
+        v.object({
+          /** Type of action. */
+          type: v.pipe(
+            v.literal("order"),
+            v.description("Type of action."),
+          ),
+          /** Array of order parameters. */
+          orders: v.pipe(
+            v.array(
+              v.pipe(
+                v.object({
+                  /** Asset ID. */
+                  a: v.pipe(
+                    UnsignedInteger,
+                    v.description("Asset ID."),
+                  ),
+                  /** Position side (`true` for long, `false` for short). */
+                  b: v.pipe(
+                    v.boolean(),
+                    v.description("Position side (`true` for long, `false` for short)."),
+                  ),
+                  /** Price. */
+                  p: v.pipe(
+                    UnsignedDecimal,
+                    v.description("Price."),
+                  ),
+                  /** Size (in base currency units). */
+                  s: v.pipe(
+                    UnsignedDecimal,
+                    v.description("Size (in base currency units)."),
+                  ),
+                  /** Is reduce-only? */
+                  r: v.pipe(
+                    v.boolean(),
+                    v.description("Is reduce-only?"),
+                  ),
+                  /** Order type. */
+                  t: v.pipe(
+                    v.union([
+                      v.object({
+                        /** Limit order parameters. */
+                        limit: v.pipe(
+                          v.object({
+                            /**
+                             * Time-in-force.
+                             * - `"Gtc"`: Remains active until filled or canceled.
+                             * - `"Ioc"`: Fills immediately or cancels any unfilled portion.
+                             * - `"Alo"`: Adds liquidity only.
+                             * - `"FrontendMarket"`: Similar to Ioc, used in Hyperliquid UI.
+                             * - `"LiquidationMarket"`: Similar to Ioc, used in Hyperliquid UI.
+                             */
+                            tif: v.pipe(
+                              v.picklist(["Gtc", "Ioc", "Alo", "FrontendMarket", "LiquidationMarket"]),
+                              v.description(
+                                "Time-in-force." +
+                                  '\n- `"Gtc"`: Remains active until filled or canceled.' +
+                                  '\n- `"Ioc"`: Fills immediately or cancels any unfilled portion.' +
+                                  '\n- `"Alo"`: Adds liquidity only.' +
+                                  '\n- `"FrontendMarket"`: Similar to Ioc, used in Hyperliquid UI.' +
+                                  '\n- `"LiquidationMarket"`: Similar to Ioc, used in Hyperliquid UI.',
+                              ),
+                            ),
+                          }),
+                          v.description("Limit order parameters."),
+                        ),
+                      }),
+                      v.object({
+                        /** Trigger order parameters. */
+                        trigger: v.pipe(
+                          v.object({
+                            /** Is market order? */
+                            isMarket: v.pipe(
+                              v.boolean(),
+                              v.description("Is market order?"),
+                            ),
+                            /** Trigger price. */
+                            triggerPx: v.pipe(
+                              UnsignedDecimal,
+                              v.description("Trigger price."),
+                            ),
+                            /** Indicates whether it is take profit or stop loss. */
+                            tpsl: v.pipe(
+                              v.picklist(["tp", "sl"]),
+                              v.description("Indicates whether it is take profit or stop loss."),
+                            ),
+                          }),
+                          v.description("Trigger order parameters."),
+                        ),
+                      }),
+                    ]),
+                    v.description("Order type."),
+                  ),
+                  /** Client Order ID. */
+                  c: v.pipe(
+                    v.optional(v.pipe(Hex, v.length(34))),
+                    v.description("Client Order ID."),
+                  ),
+                }),
+                v.description("Place order parameters."),
+              ),
+            ),
+            v.description("Array of order parameters."),
+          ),
+          /**
+           * Order grouping strategy:
+           * - `na`: Standard order without grouping (default).
+           * - `normalTpsl`: TP/SL order with fixed size that doesn't adjust with position changes.
+           * - `positionTpsl`: TP/SL order that adjusts proportionally with the position size.
+           */
+          grouping: v.pipe(
+            v.optional(v.picklist(["na", "normalTpsl", "positionTpsl"]), "na"),
+            v.description(
+              "Order grouping strategy:" +
+                "\n- `na`: Standard order without grouping." +
+                "\n- `normalTpsl`: TP/SL order with fixed size that doesn't adjust with position changes." +
+                "\n- `positionTpsl`: TP/SL order that adjusts proportionally with the position size.",
+            ),
+          ),
+          /** Builder fee. */
+          builder: v.pipe(
+            v.optional(v.object({
+              /** Builder address. */
+              b: v.pipe(
+                Address,
+                v.description("Builder address."),
+              ),
+              /** Builder fee in 0.1bps (1 = 0.0001%). */
+              f: v.pipe(
+                UnsignedInteger,
+                v.description("Builder fee in 0.1bps (1 = 0.0001%)."),
+              ),
+            })),
+            v.description("Builder fee."),
+          ),
+        }),
+        v.description("Action to perform."),
+      ),
+      /** Nonce (timestamp in ms) used to prevent replay attacks. */
+      nonce: Nonce,
+      /** ECDSA signature components. */
+      signature: 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("Place an order(s)."),
+  );
+})();
+export type OrderRequest = v.InferOutput<typeof OrderRequest>;
+
+/**
+ * Response for order placement.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#place-an-order
+ */
+export const OrderResponse = /* @__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("order"),
+            v.description("Type of response."),
+          ),
+          /** Specific data. */
+          data: v.pipe(
+            v.object({
+              /** Array of statuses or error messages. */
+              statuses: v.pipe(
+                v.array(
+                  v.union([
+                    v.object({
+                      /** Resting order status. */
+                      resting: v.pipe(
+                        v.object({
+                          /** Order ID. */
+                          oid: v.pipe(
+                            UnsignedInteger,
+                            v.description("Order ID."),
+                          ),
+                          /** Client Order ID. */
+                          cloid: v.pipe(
+                            v.optional(v.pipe(Hex, v.length(34))),
+                            v.description("Client Order ID."),
+                          ),
+                        }),
+                        v.description("Resting order status."),
+                      ),
+                    }),
+                    v.object({
+                      /** Filled order status. */
+                      filled: v.pipe(
+                        v.object({
+                          /** Total size filled. */
+                          totalSz: v.pipe(
+                            UnsignedDecimal,
+                            v.description("Total size filled."),
+                          ),
+                          /** Average price of fill. */
+                          avgPx: v.pipe(
+                            UnsignedDecimal,
+                            v.description("Average price of fill."),
+                          ),
+                          /** Order ID. */
+                          oid: v.pipe(
+                            UnsignedInteger,
+                            v.description("Order ID."),
+                          ),
+                          /** Client Order ID. */
+                          cloid: v.pipe(
+                            v.optional(v.pipe(Hex, v.length(34))),
+                            v.description("Client Order ID."),
+                          ),
+                        }),
+                        v.description("Filled order status."),
+                      ),
+                    }),
+                    v.object({
+                      /** Error message. */
+                      error: v.pipe(
+                        v.string(),
+                        v.description("Error message."),
+                      ),
+                    }),
+                  ]),
+                ),
+                v.description("Array of statuses or error messages."),
+              ),
+            }),
+            v.description("Specific data."),
+          ),
+        }),
+        v.description("Response details."),
+      ),
+    }),
+    v.description("Response for order placement."),
+  );
+})();
+export type OrderResponse = v.InferOutput<typeof OrderResponse>;
+
+// ============================================================
+// 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 OrderParameters = /* @__PURE__ */ (() => {
+  return v.omit(
+    v.object(OrderRequest.entries.action.entries),
+    ["type"],
+  );
+})();
+/** Action parameters for the {@linkcode order} function. */
+export type OrderParameters = v.InferInput<typeof OrderParameters>;
+
+/** Request options for the {@linkcode order} function. */
+export type OrderOptions = ExtractRequestOptions<v.InferInput<typeof OrderRequest>>;
+
+/** Successful variant of {@linkcode OrderResponse} without errors. */
+export type OrderSuccessResponse = ExcludeErrorResponse<OrderResponse>;
+
+/**
+ * Place an order(s).
+ *
+ * @param config - General configuration for Exchange API requests.
+ * @param params - Parameters specific to the API request.
+ * @param opts - Request execution options.
+ *
+ * @returns Successful variant of {@link OrderResponse} without error statuses.
+ *
+ * @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 { order } from "@nktkas/hyperliquid/api/exchange";
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ *
+ * const wallet = privateKeyToAccount("0x..."); // viem or ethers
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await order(
+ *   { transport, wallet },
+ *   {
+ *     orders: [
+ *       {
+ *         a: 0,
+ *         b: true,
+ *         p: "30000",
+ *         s: "0.1",
+ *         r: false,
+ *         t: { limit: { tif: "Gtc" } },
+ *         c: "0x...",
+ *       },
+ *     ],
+ *     grouping: "na",
+ *   },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#place-an-order
+ */
+export function order(
+  config: ExchangeConfig,
+  params: OrderParameters,
+  opts?: OrderOptions,
+): Promise<OrderSuccessResponse> {
+  const action = v.parse(OrderParameters, params);
+  return executeL1Action(config, { type: "order", ...action }, opts);
+}