@nktkas/hyperliquid 0.25.0-beta.4 → 0.25.1

package/src/src/api/exchange/~mod.ts

@@ -0,0 +1,84 @@
+/**
+ * This module re-exports all exchange-related API request functions and types.
+ *
+ * You can use raw functions to maximize tree-shaking in your app,
+ * or to access [valibot](https://github.com/fabian-hiller/valibot) schemas Request/Response.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ * import { order } from "@nktkas/hyperliquid/api/exchange";
+ * //       ^^^^^
+ * //       same name as in `ExchangeClient`
+ *
+ * const wallet = privateKeyToAccount("0x..."); // viem or ethers
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await order(
+ *   { transport, wallet }, // same params as in `ExchangeClient` or `MultiSignClient`
+ *   {
+ *     orders: [
+ *       {
+ *         a: 0,
+ *         b: true,
+ *         p: "30000",
+ *         s: "0.1",
+ *         r: false,
+ *         t: { limit: { tif: "Gtc" } },
+ *         c: "0x...",
+ *       },
+ *     ],
+ *     grouping: "na",
+ *   },
+ * );
+ * ```
+ *
+ * @module
+ */
+
+export { parser, SchemaError } from "../_common.js";
+export type { ExchangeRequestConfig } from "./_common.js";
+
+export * from "./approveAgent.js";
+export * from "./approveBuilderFee.js";
+export * from "./batchModify.js";
+export * from "./cancel.js";
+export * from "./cancelByCloid.js";
+export * from "./cDeposit.js";
+export * from "./claimRewards.js";
+export * from "./convertToMultiSigUser.js";
+export * from "./createSubAccount.js";
+export * from "./createVault.js";
+export * from "./cSignerAction.js";
+export * from "./cValidatorAction.js";
+export * from "./cWithdraw.js";
+export * from "./evmUserModify.js";
+export * from "./modify.js";
+export * from "./multiSig.js";
+export * from "./order.js";
+export * from "./noop.js";
+export * from "./perpDeploy.js";
+export * from "./registerReferrer.js";
+export * from "./reserveRequestWeight.js";
+export * from "./scheduleCancel.js";
+export * from "./sendAsset.js";
+export * from "./setDisplayName.js";
+export * from "./setReferrer.js";
+export * from "./spotDeploy.js";
+export * from "./spotSend.js";
+export * from "./spotUser.js";
+export * from "./subAccountModify.js";
+export * from "./subAccountSpotTransfer.js";
+export * from "./subAccountTransfer.js";
+export * from "./tokenDelegate.js";
+export * from "./twapCancel.js";
+export * from "./twapOrder.js";
+export * from "./updateIsolatedMargin.js";
+export * from "./updateLeverage.js";
+export * from "./usdClassTransfer.js";
+export * from "./usdSend.js";
+export * from "./vaultDistribute.js";
+export * from "./vaultModify.js";
+export * from "./vaultTransfer.js";
+export * from "./withdraw3.js";

package/src/src/api/info/_common.ts

@@ -0,0 +1,7 @@
+import type { IRequestTransport } from "../../transport/base.js";
+
+/** Configuration for Info API requests. */
+export interface InfoRequestConfig<T extends IRequestTransport = IRequestTransport> {
+  /** The transport used to connect to the Hyperliquid API. */
+  transport: T;
+}

package/src/src/api/info/activeAssetData.ts

@@ -0,0 +1,147 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser, UnsignedDecimal, UnsignedInteger } from "../_common.js";
+import type { InfoRequestConfig } from "./_common.js";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request user active asset data.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-users-active-asset-data
+ */
+export const ActiveAssetDataRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("activeAssetData"),
+        v.description("Type of request."),
+      ),
+      /** Asset symbol (e.g., BTC). */
+      coin: v.pipe(
+        v.string(),
+        v.description("Asset symbol (e.g., BTC)."),
+      ),
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+    }),
+    v.description("Request user active asset data."),
+  );
+})();
+export type ActiveAssetDataRequest = v.InferOutput<typeof ActiveAssetDataRequest>;
+
+/**
+ * User active asset data.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-users-active-asset-data
+ */
+export const ActiveAssetDataResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+      /** Asset symbol (e.g., BTC). */
+      coin: v.pipe(
+        v.string(),
+        v.description("Asset symbol (e.g., BTC)."),
+      ),
+      /** Leverage configuration. */
+      leverage: v.pipe(
+        v.union([
+          v.object({
+            /** Leverage type. */
+            type: v.pipe(
+              v.literal("isolated"),
+              v.description("Leverage type."),
+            ),
+            /** Leverage value used. */
+            value: v.pipe(
+              UnsignedInteger,
+              v.minValue(1),
+              v.description("Leverage value used."),
+            ),
+            /** Amount of USD used (1 = 1$). */
+            rawUsd: v.pipe(
+              UnsignedDecimal,
+              v.description("Amount of USD used (1 = 1$)."),
+            ),
+          }),
+          v.object({
+            /** Leverage type. */
+            type: v.pipe(
+              v.literal("cross"),
+              v.description("Leverage type."),
+            ),
+            /** Leverage value used. */
+            value: v.pipe(
+              UnsignedInteger,
+              v.minValue(1),
+              v.description("Leverage value used."),
+            ),
+          }),
+        ]),
+        v.description("Leverage configuration."),
+      ),
+      /** Maximum trade size range [min, max]. */
+      maxTradeSzs: v.pipe(
+        v.tuple([UnsignedDecimal, UnsignedDecimal]),
+        v.description("Maximum trade size range [min, max]."),
+      ),
+      /** Available to trade range [min, max]. */
+      availableToTrade: v.pipe(
+        v.tuple([UnsignedDecimal, UnsignedDecimal]),
+        v.description("Available to trade range [min, max]."),
+      ),
+      /** Mark price. */
+      markPx: v.pipe(
+        UnsignedDecimal,
+        v.description("Mark price."),
+      ),
+    }),
+    v.description("User active asset data."),
+  );
+})();
+export type ActiveAssetDataResponse = v.InferOutput<typeof ActiveAssetDataResponse>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode activeAssetData} function. */
+export type ActiveAssetDataParameters = Omit<v.InferInput<typeof ActiveAssetDataRequest>, "type">;
+
+/**
+ * Request user active asset data.
+ * @param config - General configuration for Info API requests.
+ * @param params - Parameters specific to the API request.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns User active asset data.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-users-active-asset-data
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { activeAssetData } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const data = await activeAssetData(
+ *   { transport },
+ *   { user: "0x...", coin: "ETH" },
+ * );
+ * ```
+ */
+export function activeAssetData(
+  config: InfoRequestConfig,
+  params: DeepImmutable<ActiveAssetDataParameters>,
+  signal?: AbortSignal,
+): Promise<ActiveAssetDataResponse> {
+  const request = parser(ActiveAssetDataRequest)({
+    type: "activeAssetData",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/src/api/info/allMids.ts

@@ -0,0 +1,88 @@
+import * as v from "valibot";
+import { type DeepImmutable, parser, UnsignedDecimal } from "../_common.js";
+import type { InfoRequestConfig } from "./_common.js";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request mid coin prices.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#retrieve-mids-for-all-coins
+ */
+export const AllMidsRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("allMids"),
+        v.description("Type of request."),
+      ),
+      /** DEX name (empty string for main dex). */
+      dex: v.pipe(
+        v.optional(v.string()),
+        v.description("DEX name (empty string for main dex)."),
+      ),
+    }),
+    v.description("Request mid coin prices."),
+  );
+})();
+export type AllMidsRequest = v.InferOutput<typeof AllMidsRequest>;
+
+/**
+ * Mapping of coin symbols to mid prices.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#retrieve-mids-for-all-coins
+ */
+export const AllMidsResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.record(v.string(), UnsignedDecimal),
+    v.description("Mapping of coin symbols to mid prices."),
+  );
+})();
+export type AllMidsResponse = v.InferOutput<typeof AllMidsResponse>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode allMids} function. */
+export type AllMidsParameters = Omit<v.InferInput<typeof AllMidsRequest>, "type">;
+
+/**
+ * Request mid coin prices.
+ * @param config - General configuration for Info API requests.
+ * @param params - Parameters specific to the API request.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns Mapping of coin symbols to mid prices.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#retrieve-mids-for-all-coins
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { allMids } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const data = await allMids({ transport });
+ * ```
+ */
+export function allMids(
+  config: InfoRequestConfig,
+  params?: DeepImmutable<AllMidsParameters>,
+  signal?: AbortSignal,
+): Promise<AllMidsResponse>;
+export function allMids(
+  config: InfoRequestConfig,
+  signal?: AbortSignal,
+): Promise<AllMidsResponse>;
+export function allMids(
+  config: InfoRequestConfig,
+  paramsOrSignal?: DeepImmutable<AllMidsParameters> | AbortSignal,
+  maybeSignal?: AbortSignal,
+): Promise<AllMidsResponse> {
+  const params = paramsOrSignal instanceof AbortSignal ? {} : paramsOrSignal;
+  const signal = paramsOrSignal instanceof AbortSignal ? paramsOrSignal : maybeSignal;
+
+  const request = parser(AllMidsRequest)({
+    type: "allMids",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/src/api/info/blockDetails.ts

@@ -0,0 +1,165 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, Hex, parser, UnsignedInteger } from "../_common.js";
+import type { InfoRequestConfig } from "./_common.js";
+import type { IRequestTransport } from "../../transport/base.js";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request block details by block height.
+ * @see null
+ */
+export const BlockDetailsRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("blockDetails"),
+        v.description("Type of request."),
+      ),
+      /** Block height. */
+      height: v.pipe(
+        UnsignedInteger,
+        v.description("Block height."),
+      ),
+    }),
+    v.description("Request block details by block height."),
+  );
+})();
+export type BlockDetailsRequest = v.InferOutput<typeof BlockDetailsRequest>;
+
+/**
+ * Response containing block information.
+ * @see null
+ */
+export const BlockDetailsResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of response. */
+      type: v.pipe(
+        v.literal("blockDetails"),
+        v.description("Type of response."),
+      ),
+      /** The details of a block. */
+      blockDetails: v.pipe(
+        v.object({
+          /** Block creation timestamp. */
+          blockTime: v.pipe(
+            UnsignedInteger,
+            v.description("Block creation timestamp."),
+          ),
+          /** Block hash. */
+          hash: v.pipe(
+            v.pipe(Hex, v.length(66)),
+            v.description("Block hash."),
+          ),
+          /** Block height in chain. */
+          height: v.pipe(
+            UnsignedInteger,
+            v.description("Block height in chain."),
+          ),
+          /** Total transactions in block. */
+          numTxs: v.pipe(
+            UnsignedInteger,
+            v.description("Total transactions in block."),
+          ),
+          /** Block proposer address. */
+          proposer: v.pipe(
+            Address,
+            v.description("Block proposer address."),
+          ),
+          /** Array of transactions in the block. */
+          txs: v.pipe(
+            v.array(
+              /** Transaction details. */
+              v.pipe(
+                v.object({
+                  /** Action performed in transaction. */
+                  action: v.pipe(
+                    v.looseObject({
+                      /** Action type. */
+                      type: v.pipe(
+                        v.string(),
+                        v.description("Action type."),
+                      ),
+                    }),
+                    v.description("Action performed in transaction."),
+                  ),
+                  /** Block number where transaction was included. */
+                  block: v.pipe(
+                    UnsignedInteger,
+                    v.description("Block number where transaction was included."),
+                  ),
+                  /** Error message if transaction failed. */
+                  error: v.pipe(
+                    v.nullable(v.string()),
+                    v.description("Error message if transaction failed."),
+                  ),
+                  /** Transaction hash. */
+                  hash: v.pipe(
+                    v.pipe(Hex, v.length(66)),
+                    v.description("Transaction hash."),
+                  ),
+                  /** Transaction creation timestamp. */
+                  time: v.pipe(
+                    UnsignedInteger,
+                    v.description("Transaction creation timestamp."),
+                  ),
+                  /** Creator's address. */
+                  user: v.pipe(
+                    Address,
+                    v.description("Creator's address."),
+                  ),
+                }),
+                v.description("Transaction details."),
+              ),
+            ),
+            v.description("Array of transactions in the block."),
+          ),
+        }),
+        v.description("The details of a block."),
+      ),
+    }),
+    v.description("Response containing block information."),
+  );
+})();
+export type BlockDetailsResponse = v.InferOutput<typeof BlockDetailsResponse>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode blockDetails} function. */
+export type BlockDetailsParameters = Omit<v.InferInput<typeof BlockDetailsRequest>, "type">;
+
+/**
+ * Request block details by block height.
+ * @param config - General configuration for Info API requests.
+ * @param params - Parameters specific to the API request.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns Response containing block information.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see null
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { blockDetails } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // only `HttpTransport` supports this API
+ * const data = await blockDetails(
+ *   { transport },
+ *   { height: 123 },
+ * );
+ * ```
+ */
+export function blockDetails<T extends IRequestTransport>(
+  config: T extends { request(endpoint: "explorer", ...args: unknown[]): unknown } ? InfoRequestConfig<T> : never,
+  params: DeepImmutable<BlockDetailsParameters>,
+  signal?: AbortSignal,
+): Promise<BlockDetailsResponse> {
+  const request = parser(BlockDetailsRequest)({
+    type: "blockDetails",
+    ...params,
+  });
+  return config.transport.request("explorer", request, signal);
+}

package/src/src/api/info/candleSnapshot.ts

@@ -0,0 +1,187 @@
+import * as v from "valibot";
+import { type DeepImmutable, parser, UnsignedDecimal, UnsignedInteger } from "../_common.js";
+import type { InfoRequestConfig } from "./_common.js";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request candlestick snapshots.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#candle-snapshot
+ */
+export const CandleSnapshotRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("candleSnapshot"),
+        v.description("Type of request."),
+      ),
+      /** Request parameters. */
+      req: v.pipe(
+        v.object({
+          /** Asset symbol (e.g., BTC). */
+          coin: v.pipe(
+            v.string(),
+            v.description("Asset symbol (e.g., BTC)."),
+          ),
+          /** Time interval. */
+          interval: v.pipe(
+            v.union([
+              v.literal("1m"),
+              v.literal("3m"),
+              v.literal("5m"),
+              v.literal("15m"),
+              v.literal("30m"),
+              v.literal("1h"),
+              v.literal("2h"),
+              v.literal("4h"),
+              v.literal("8h"),
+              v.literal("12h"),
+              v.literal("1d"),
+              v.literal("3d"),
+              v.literal("1w"),
+              v.literal("1M"),
+            ]),
+            v.description("Time interval."),
+          ),
+          /** Start time (in ms since epoch). */
+          startTime: v.pipe(
+            UnsignedInteger,
+            v.description("Start time (in ms since epoch)."),
+          ),
+          /** End time (in ms since epoch). */
+          endTime: v.pipe(
+            v.nullish(UnsignedInteger),
+            v.description("End time (in ms since epoch)."),
+          ),
+        }),
+        v.description("Request parameters."),
+      ),
+    }),
+    v.description("Request candlestick snapshots."),
+  );
+})();
+export type CandleSnapshotRequest = v.InferOutput<typeof CandleSnapshotRequest>;
+
+/**
+ * Array of candlestick data points.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#candle-snapshot
+ */
+export const CandleSnapshotResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.array(
+      /** Candlestick data point. */
+      v.pipe(
+        v.object({
+          /** Opening timestamp (ms since epoch). */
+          t: v.pipe(
+            UnsignedInteger,
+            v.description("Opening timestamp (ms since epoch)."),
+          ),
+          /** Closing timestamp (ms since epoch). */
+          T: v.pipe(
+            UnsignedInteger,
+            v.description("Closing timestamp (ms since epoch)."),
+          ),
+          /** Asset symbol. */
+          s: v.pipe(
+            v.string(),
+            v.description("Asset symbol."),
+          ),
+          /** Candle interval. */
+          i: v.pipe(
+            v.union([
+              v.literal("1m"),
+              v.literal("3m"),
+              v.literal("5m"),
+              v.literal("15m"),
+              v.literal("30m"),
+              v.literal("1h"),
+              v.literal("2h"),
+              v.literal("4h"),
+              v.literal("8h"),
+              v.literal("12h"),
+              v.literal("1d"),
+              v.literal("3d"),
+              v.literal("1w"),
+              v.literal("1M"),
+            ]),
+            v.description("Candle interval."),
+          ),
+          /** Opening price. */
+          o: v.pipe(
+            UnsignedDecimal,
+            v.description("Opening price."),
+          ),
+          /** Closing price. */
+          c: v.pipe(
+            UnsignedDecimal,
+            v.description("Closing price."),
+          ),
+          /** Highest price. */
+          h: v.pipe(
+            UnsignedDecimal,
+            v.description("Highest price."),
+          ),
+          /** Lowest price. */
+          l: v.pipe(
+            UnsignedDecimal,
+            v.description("Lowest price."),
+          ),
+          /** Total volume traded in base currency. */
+          v: v.pipe(
+            UnsignedDecimal,
+            v.description("Total volume traded in base currency."),
+          ),
+          /** Number of trades executed. */
+          n: v.pipe(
+            UnsignedInteger,
+            v.description("Number of trades executed."),
+          ),
+        }),
+        v.description("Candlestick data point."),
+      ),
+    ),
+    v.description("Array of candlestick data points."),
+  );
+})();
+export type CandleSnapshotResponse = v.InferOutput<typeof CandleSnapshotResponse>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode candleSnapshot} function. */
+export type CandleSnapshotParameters = v.InferInput<typeof CandleSnapshotRequest>["req"];
+
+/**
+ * Request candlestick snapshots.
+ * @param config - General configuration for Info API requests.
+ * @param params - Parameters specific to the API request.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns Array of candlestick data points.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#candle-snapshot
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { candleSnapshot } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const data = await candleSnapshot(
+ *   { transport },
+ *   { coin: "ETH", interval: "1h", startTime: Date.now() - 1000 * 60 * 60 * 24 },
+ * );
+ * ```
+ */
+export function candleSnapshot(
+  config: InfoRequestConfig,
+  params: DeepImmutable<CandleSnapshotParameters>,
+  signal?: AbortSignal,
+): Promise<CandleSnapshotResponse> {
+  const request = parser(CandleSnapshotRequest)({
+    type: "candleSnapshot",
+    req: params,
+  });
+  return config.transport.request("info", request, signal);
+}