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

package/src/src/api/info/mod.ts

@@ -0,0 +1,95 @@
+/**
+ * This module re-exports all info-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 { clearinghouseState } from "@nktkas/hyperliquid/api/info";
+ * //       ^^^^^^^^^^^^^^^^^^
+ * //       same name as in `InfoClient`
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await clearinghouseState(
+ *   { transport }, // same params as in `InfoClient`
+ *   { user: "0x..." },
+ * );
+ * ```
+ *
+ * @module
+ */
+
+export type { InfoConfig } from "./_methods/_types.js";
+
+export * from "./_methods/activeAssetData.js";
+export * from "./_methods/alignedQuoteTokenInfo.js";
+export * from "./_methods/allMids.js";
+export * from "./_methods/allPerpMetas.js";
+export * from "./_methods/blockDetails.js";
+export * from "./_methods/candleSnapshot.js";
+export * from "./_methods/clearinghouseState.js";
+export * from "./_methods/delegations.js";
+export * from "./_methods/delegatorHistory.js";
+export * from "./_methods/delegatorRewards.js";
+export * from "./_methods/delegatorSummary.js";
+export * from "./_methods/exchangeStatus.js";
+export * from "./_methods/extraAgents.js";
+export * from "./_methods/frontendOpenOrders.js";
+export * from "./_methods/fundingHistory.js";
+export * from "./_methods/gossipRootIps.js";
+export * from "./_methods/historicalOrders.js";
+export * from "./_methods/isVip.js";
+export * from "./_methods/l2Book.js";
+export * from "./_methods/l3Orders.js"
+export * from "./_methods/l4Orders.js";
+export * from "./_methods/leadingVaults.js";
+export * from "./_methods/legalCheck.js";
+export * from "./_methods/liquidatable.js";
+export * from "./_methods/marginTable.js";
+export * from "./_methods/maxBuilderFee.js";
+export * from "./_methods/maxMarketOrderNtls.js";
+export * from "./_methods/meta.js";
+export * from "./_methods/metaAndAssetCtxs.js";
+export * from "./_methods/openOrders.js";
+export * from "./_methods/orderStatus.js";
+export * from "./_methods/perpDeployAuctionStatus.js";
+export * from "./_methods/perpDexLimits.js";
+export * from "./_methods/perpDexs.js";
+export * from "./_methods/perpDexStatus.js";
+export * from "./_methods/perpsAtOpenInterestCap.js";
+export * from "./_methods/portfolio.js";
+export * from "./_methods/predictedFundings.js";
+export * from "./_methods/preTransferCheck.js";
+export * from "./_methods/recentTrades.js";
+export * from "./_methods/referral.js";
+export * from "./_methods/spotClearinghouseState.js";
+export * from "./_methods/spotDeployState.js";
+export * from "./_methods/spotMeta.js";
+export * from "./_methods/spotMetaAndAssetCtxs.js";
+export * from "./_methods/spotPairDeployAuctionStatus.js";
+export * from "./_methods/subAccounts.js";
+export * from "./_methods/subAccounts2.js";
+export * from "./_methods/tokenDetails.js";
+export * from "./_methods/twapHistory.js";
+export * from "./_methods/txDetails.js";
+export * from "./_methods/userDetails.js";
+export * from "./_methods/userDexAbstraction.js";
+export * from "./_methods/userFees.js";
+export * from "./_methods/userFills.js";
+export * from "./_methods/userFillsByTime.js";
+export * from "./_methods/userFunding.js";
+export * from "./_methods/userNonFundingLedgerUpdates.js";
+export * from "./_methods/userRateLimit.js";
+export * from "./_methods/userRole.js";
+export * from "./_methods/userToMultiSigSigners.js";
+export * from "./_methods/userTwapSliceFills.js";
+export * from "./_methods/userTwapSliceFillsByTime.js";
+export * from "./_methods/userVaultEquities.js";
+export * from "./_methods/validatorL1Votes.js";
+export * from "./_methods/validatorSummaries.js";
+export * from "./_methods/vaultDetails.js";
+export * from "./_methods/vaultSummaries.js";
+export * from "./_methods/webData2.js";

package/src/src/api/subscription/_methods/_types.ts

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

package/src/src/api/subscription/_methods/activeAssetCtx.ts

@@ -0,0 +1,149 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Decimal, UnsignedDecimal } from "../../_schemas.js";
+
+/** Subscription to context events for a specific perpetual asset. */
+export const ActiveAssetCtxRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of subscription. */
+      type: v.pipe(
+        v.literal("activeAssetCtx"),
+        v.description("Type of subscription."),
+      ),
+      /** Asset symbol (e.g., BTC). */
+      coin: v.pipe(
+        v.string(),
+        v.description("Asset symbol (e.g., BTC)."),
+      ),
+    }),
+    v.description("Subscription to context events for a specific perpetual asset."),
+  );
+})();
+export type ActiveAssetCtxRequest = v.InferOutput<typeof ActiveAssetCtxRequest>;
+
+/** Event of active perpetual asset context. */
+export const ActiveAssetCtxEvent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Asset symbol (e.g., BTC). */
+      coin: v.pipe(
+        v.string(),
+        v.description("Asset symbol (e.g., BTC)."),
+      ),
+      /** Context for a specific perpetual asset. */
+      ctx: v.pipe(
+        v.object({
+          /** Previous day's closing price. */
+          prevDayPx: v.pipe(
+            UnsignedDecimal,
+            v.description("Previous day's closing price."),
+          ),
+          /** Daily notional volume. */
+          dayNtlVlm: v.pipe(
+            UnsignedDecimal,
+            v.description("Daily notional volume."),
+          ),
+          /** Mark price. */
+          markPx: v.pipe(
+            UnsignedDecimal,
+            v.description("Mark price."),
+          ),
+          /** Mid price. */
+          midPx: v.pipe(
+            v.nullable(UnsignedDecimal),
+            v.description("Mid price."),
+          ),
+          /** Funding rate. */
+          funding: v.pipe(
+            Decimal,
+            v.description("Funding rate."),
+          ),
+          /** Total open interest. */
+          openInterest: v.pipe(
+            UnsignedDecimal,
+            v.description("Total open interest."),
+          ),
+          /** Premium price. */
+          premium: v.pipe(
+            v.nullable(Decimal),
+            v.description("Premium price."),
+          ),
+          /** Oracle price. */
+          oraclePx: v.pipe(
+            UnsignedDecimal,
+            v.description("Oracle price."),
+          ),
+          /** Array of impact prices. */
+          impactPxs: v.pipe(
+            v.nullable(v.array(v.string())),
+            v.description("Array of impact prices."),
+          ),
+          /** Daily volume in base currency. */
+          dayBaseVlm: v.pipe(
+            UnsignedDecimal,
+            v.description("Daily volume in base currency."),
+          ),
+        }),
+        v.description("Context for a specific perpetual asset."),
+      ),
+    }),
+    v.description("Event of active perpetual asset context."),
+  );
+})();
+export type ActiveAssetCtxEvent = v.InferOutput<typeof ActiveAssetCtxEvent>;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import type { SubscriptionConfig } from "./_types.js";
+import type { WebSocketSubscription } from "../../../transport/websocket/mod.js";
+
+/** Request parameters for the {@linkcode activeAssetCtx} function. */
+export type ActiveAssetCtxParameters = Omit<v.InferInput<typeof ActiveAssetCtxRequest>, "type">;
+
+/**
+ * Subscribe to context updates for a specific perpetual asset.
+ *
+ * @param config - General configuration for Subscription API subscriptions.
+ * @param params - Parameters specific to the API subscription.
+ * @param listener - A callback function to be called when the event is received.
+ *
+ * @returns A request-promise that resolves with a {@link WebSocketSubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValiError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { WebSocketTransport } from "@nktkas/hyperliquid";
+ * import { activeAssetCtx } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport(); // only `WebSocketTransport`
+ *
+ * const sub = await activeAssetCtx(
+ *   { transport },
+ *   { coin: "ETH" },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function activeAssetCtx(
+  config: SubscriptionConfig,
+  params: ActiveAssetCtxParameters,
+  listener: (data: ActiveAssetCtxEvent) => void,
+): Promise<WebSocketSubscription> {
+  const payload = v.parse(ActiveAssetCtxRequest, { type: "activeAssetCtx", ...params });
+  return config.transport.subscribe<ActiveAssetCtxEvent>(payload.type, payload, (e) => {
+    if (e.detail.coin === payload.coin) {
+      listener(e.detail);
+    }
+  });
+}

package/src/src/api/subscription/_methods/activeAssetData.ts

@@ -0,0 +1,93 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+import { ActiveAssetDataResponse } from "../../info/_methods/activeAssetData.js";
+
+/** Subscription to active asset data events for a specific user and coin. */
+export const ActiveAssetDataRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of subscription. */
+      type: v.pipe(
+        v.literal("activeAssetData"),
+        v.description("Type of subscription."),
+      ),
+      /** 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("Subscription to active asset data events for a specific user and coin."),
+  );
+})();
+export type ActiveAssetDataRequest = v.InferOutput<typeof ActiveAssetDataRequest>;
+
+/** Event of user active asset data. */
+export const ActiveAssetDataEvent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    ActiveAssetDataResponse,
+    v.description("Event of user active asset data."),
+  );
+})();
+export type ActiveAssetDataEvent = v.InferOutput<typeof ActiveAssetDataEvent>;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import type { SubscriptionConfig } from "./_types.js";
+import type { WebSocketSubscription } from "../../../transport/websocket/mod.js";
+
+/** Request parameters for the {@linkcode activeAssetData} function. */
+export type ActiveAssetDataParameters = Omit<v.InferInput<typeof ActiveAssetDataRequest>, "type">;
+
+/**
+ * Subscribe to trading data updates for a specific asset and user.
+ *
+ * @param config - General configuration for Subscription API subscriptions.
+ * @param params - Parameters specific to the API subscription.
+ * @param listener - A callback function to be called when the event is received.
+ *
+ * @returns A request-promise that resolves with a {@link WebSocketSubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValiError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { WebSocketTransport } from "@nktkas/hyperliquid";
+ * import { activeAssetData } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport(); // only `WebSocketTransport`
+ *
+ * const sub = await activeAssetData(
+ *   { transport },
+ *   { coin: "ETH", user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function activeAssetData(
+  config: SubscriptionConfig,
+  params: ActiveAssetDataParameters,
+  listener: (data: ActiveAssetDataEvent) => void,
+): Promise<WebSocketSubscription> {
+  const payload = v.parse(ActiveAssetDataRequest, { type: "activeAssetData", ...params });
+  return config.transport.subscribe<ActiveAssetDataEvent>(payload.type, payload, (e) => {
+    if (e.detail.coin === payload.coin && e.detail.user === payload.user) {
+      listener(e.detail);
+    }
+  });
+}

package/src/src/api/subscription/_methods/activeSpotAssetCtx.ts

@@ -0,0 +1,138 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { UnsignedDecimal } from "../../_schemas.js";
+
+/** Subscription to context events for a specific spot asset. */
+export const ActiveSpotAssetCtxRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of subscription. */
+      type: v.pipe(
+        v.literal("activeAssetCtx"),
+        v.description("Type of subscription."),
+      ),
+      /** Asset ID (e.g., @1). */
+      coin: v.pipe(
+        v.string(),
+        v.description("Asset ID (e.g., @1)."),
+      ),
+    }),
+    v.description("Subscription to context events for a specific spot asset."),
+  );
+})();
+export type ActiveSpotAssetCtxRequest = v.InferOutput<typeof ActiveSpotAssetCtxRequest>;
+
+/** Event of active spot asset context. */
+export const ActiveSpotAssetCtxEvent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Asset ID (e.g., @1). */
+      coin: v.pipe(
+        v.string(),
+        v.description("Asset ID (e.g., @1)."),
+      ),
+      /** Context for a specific spot asset. */
+      ctx: v.pipe(
+        v.object({
+          /** Previous day's closing price. */
+          prevDayPx: v.pipe(
+            UnsignedDecimal,
+            v.description("Previous day's closing price."),
+          ),
+          /** Daily notional volume. */
+          dayNtlVlm: v.pipe(
+            UnsignedDecimal,
+            v.description("Daily notional volume."),
+          ),
+          /** Mark price. */
+          markPx: v.pipe(
+            UnsignedDecimal,
+            v.description("Mark price."),
+          ),
+          /** Mid price. */
+          midPx: v.pipe(
+            v.nullable(UnsignedDecimal),
+            v.description("Mid price."),
+          ),
+          /** Circulating supply. */
+          circulatingSupply: v.pipe(
+            UnsignedDecimal,
+            v.description("Circulating supply."),
+          ),
+          /** Asset symbol. */
+          coin: v.pipe(
+            v.string(),
+            v.description("Asset symbol."),
+          ),
+          /** Total supply. */
+          totalSupply: v.pipe(
+            UnsignedDecimal,
+            v.description("Total supply."),
+          ),
+          /** Daily volume in base currency. */
+          dayBaseVlm: v.pipe(
+            UnsignedDecimal,
+            v.description("Daily volume in base currency."),
+          ),
+        }),
+        v.description("Context for a specific spot asset."),
+      ),
+    }),
+    v.description("Event of active spot asset context."),
+  );
+})();
+export type ActiveSpotAssetCtxEvent = v.InferOutput<typeof ActiveSpotAssetCtxEvent>;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import type { SubscriptionConfig } from "./_types.js";
+import type { WebSocketSubscription } from "../../../transport/websocket/mod.js";
+
+/** Request parameters for the {@linkcode activeSpotAssetCtx} function. */
+export type ActiveSpotAssetCtxParameters = Omit<v.InferInput<typeof ActiveSpotAssetCtxRequest>, "type">;
+
+/**
+ * Subscribe to context updates for a specific spot asset.
+ *
+ * @param config - General configuration for Subscription API subscriptions.
+ * @param params - Parameters specific to the API subscription.
+ * @param listener - A callback function to be called when the event is received.
+ * @returns A request-promise that resolves with a {@link WebSocketSubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValiError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { WebSocketTransport } from "@nktkas/hyperliquid";
+ * import { activeSpotAssetCtx } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport(); // only `WebSocketTransport`
+ *
+ * const sub = await activeSpotAssetCtx(
+ *   { transport },
+ *   { coin: "@1" },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function activeSpotAssetCtx(
+  config: SubscriptionConfig,
+  params: ActiveSpotAssetCtxParameters,
+  listener: (data: ActiveSpotAssetCtxEvent) => void,
+): Promise<WebSocketSubscription> {
+  const payload = v.parse(ActiveSpotAssetCtxRequest, { type: "activeAssetCtx", ...params });
+  return config.transport.subscribe<ActiveSpotAssetCtxEvent>("activeSpotAssetCtx", payload, (e) => {
+    if (e.detail.coin === payload.coin) {
+      listener(e.detail);
+    }
+  });
+}

package/src/src/api/subscription/_methods/allDexsAssetCtxs.ts

@@ -0,0 +1,140 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Decimal, UnsignedDecimal } from "../../_schemas.js";
+
+/** Subscription to asset context events for all DEXs. */
+export const AllDexsAssetCtxsRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of subscription. */
+      type: v.pipe(
+        v.literal("allDexsAssetCtxs"),
+        v.description("Type of subscription."),
+      ),
+    }),
+    v.description("Subscription to asset context events for all DEXs."),
+  );
+})();
+export type AllDexsAssetCtxsRequest = v.InferOutput<typeof AllDexsAssetCtxsRequest>;
+
+/** Event of asset contexts for all DEXs. */
+export const AllDexsAssetCtxsEvent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Array of tuples of dex names and contexts for each perpetual asset. */
+      ctxs: v.pipe(
+        v.array(
+          v.tuple([
+            v.string(),
+            v.array(
+              v.object({
+                /** Previous day's closing price. */
+                prevDayPx: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Previous day's closing price."),
+                ),
+                /** Daily notional volume. */
+                dayNtlVlm: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Daily notional volume."),
+                ),
+                /** Mark price. */
+                markPx: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Mark price."),
+                ),
+                /** Mid price. */
+                midPx: v.pipe(
+                  v.nullable(UnsignedDecimal),
+                  v.description("Mid price."),
+                ),
+                /** Funding rate. */
+                funding: v.pipe(
+                  Decimal,
+                  v.description("Funding rate."),
+                ),
+                /** Total open interest. */
+                openInterest: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Total open interest."),
+                ),
+                /** Premium price. */
+                premium: v.pipe(
+                  v.nullable(Decimal),
+                  v.description("Premium price."),
+                ),
+                /** Oracle price. */
+                oraclePx: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Oracle price."),
+                ),
+                /** Array of impact prices. */
+                impactPxs: v.pipe(
+                  v.nullable(v.array(v.string())),
+                  v.description("Array of impact prices."),
+                ),
+                /** Daily volume in base currency. */
+                dayBaseVlm: v.pipe(
+                  UnsignedDecimal,
+                  v.description("Daily volume in base currency."),
+                ),
+              }),
+            ),
+          ]),
+        ),
+        v.description("Array of tuples of dex names and contexts for each perpetual asset."),
+      ),
+    }),
+    v.description("Event of asset contexts for all DEXs."),
+  );
+})();
+export type AllDexsAssetCtxsEvent = v.InferOutput<typeof AllDexsAssetCtxsEvent>;
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import type { SubscriptionConfig } from "./_types.js";
+import type { WebSocketSubscription } from "../../../transport/websocket/mod.js";
+
+/**
+ * Subscribe to asset contexts for all DEXs.
+ *
+ * @param config - General configuration for Subscription API subscriptions.
+ * @param listener - A callback function to be called when the event is received.
+ *
+ * @returns A request-promise that resolves with a {@link WebSocketSubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValiError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { WebSocketTransport } from "@nktkas/hyperliquid";
+ * import { allDexsAssetCtxs } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport(); // only `WebSocketTransport`
+ *
+ * const sub = await allDexsAssetCtxs(
+ *   { transport },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function allDexsAssetCtxs(
+  config: SubscriptionConfig,
+  listener: (data: AllDexsAssetCtxsEvent) => void,
+): Promise<WebSocketSubscription> {
+  const payload = v.parse(AllDexsAssetCtxsRequest, {
+    type: "allDexsAssetCtxs",
+  });
+  return config.transport.subscribe<AllDexsAssetCtxsEvent>(payload.type, payload, (e) => {
+    listener(e.detail);
+  });
+}