@nktkas/hyperliquid 0.31.0 → 0.32.0

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

@@ -0,0 +1,151 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+import type { TwapHistoryResponse } from "../../info/_methods/twapHistory.js";
+import type { UserFillsResponse } from "../../info/_methods/userFills.js";
+import type { UserTwapSliceFillsResponse } from "../../info/_methods/userTwapSliceFills.js";
+
+/**
+ * Subscription to user events for a specific user.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export const UserEventsRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of subscription. */
+    type: v.literal("userEvents"),
+    /** User address. */
+    user: Address,
+  });
+})();
+export type UserEventsRequest = v.InferOutput<typeof UserEventsRequest>;
+
+/**
+ * Event of one of possible user events.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export type UserEventsEvent =
+  | {
+    /** Array of user trade fills. */
+    fills: UserFillsResponse;
+  }
+  | {
+    /** Funding update details. */
+    funding: {
+      /** Asset symbol. */
+      coin: string;
+      /**
+       * Amount transferred in USDC.
+       * @pattern ^-?[0-9]+(\.[0-9]+)?$
+       */
+      usdc: string;
+      /**
+       * Signed position size.
+       * @pattern ^-?[0-9]+(\.[0-9]+)?$
+       */
+      szi: string;
+      /**
+       * Applied funding rate.
+       * @pattern ^-?[0-9]+(\.[0-9]+)?$
+       */
+      fundingRate: string;
+      /** Number of samples. */
+      nSamples: number | null;
+    };
+  }
+  | {
+    /** Liquidation details. */
+    liquidation: {
+      /** Unique liquidation ID. */
+      lid: number;
+      /**
+       * Address of the liquidator.
+       * @pattern ^0x[a-fA-F0-9]{40}$
+       */
+      liquidator: `0x${string}`;
+      /**
+       * Address of the liquidated user.
+       * @pattern ^0x[a-fA-F0-9]{40}$
+       */
+      liquidated_user: `0x${string}`;
+      /**
+       * Notional position size that was liquidated.
+       * @pattern ^[0-9]+(\.[0-9]+)?$
+       */
+      liquidated_ntl_pos: string;
+      /**
+       * Account value at time of liquidation.
+       * @pattern ^[0-9]+(\.[0-9]+)?$
+       */
+      liquidated_account_value: string;
+    };
+  }
+  | {
+    /** Array of non-user initiated order cancellations. */
+    nonUserCancel: {
+      /** Asset symbol (e.g., BTC). */
+      coin: string;
+      /** Order ID. */
+      oid: number;
+    }[];
+  }
+  | {
+    /** Array of user's TWAP history. */
+    twapHistory: TwapHistoryResponse;
+  }
+  | {
+    /** Array of user's TWAP slice fills. */
+    twapSliceFills: UserTwapSliceFillsResponse;
+  };
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { ISubscription } from "../../../transport/mod.js";
+import type { SubscriptionConfig } from "./_types.js";
+
+/** Request parameters for the {@linkcode userEvents} function. */
+export type UserEventsParameters = Omit<v.InferInput<typeof UserEventsRequest>, "type">;
+
+/**
+ * Subscribe to non-order events for a specific 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.
+ * @return A request-promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValidationError} 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 { userEvents } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport();
+ *
+ * const sub = await userEvents(
+ *   { transport },
+ *   { user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function userEvents(
+  config: SubscriptionConfig,
+  params: UserEventsParameters,
+  listener: (data: UserEventsEvent) => void,
+): Promise<ISubscription> {
+  const payload = parse(UserEventsRequest, { type: "userEvents", ...params });
+  return config.transport.subscribe<UserEventsEvent>("user", payload, (e) => {
+    listener(e.detail);
+  });
+}

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

@@ -0,0 +1,95 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+import type { UserFillsResponse } from "../../info/_methods/userFills.js";
+
+/**
+ * Subscription to user fill events for a specific user.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export const UserFillsRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of subscription. */
+    type: v.literal("userFills"),
+    /** User address. */
+    user: Address,
+    /** If true, partial fills are aggregated when a crossing order fills multiple resting orders. */
+    aggregateByTime: v.optional(v.boolean()),
+  });
+})();
+export type UserFillsRequest = v.InferOutput<typeof UserFillsRequest>;
+
+/**
+ * Event of user trade fill.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export type UserFillsEvent = {
+  /**
+   * User address.
+   * @pattern ^0x[a-fA-F0-9]{40}$
+   */
+  user: `0x${string}`;
+  /** Array of user trade fills. */
+  fills: UserFillsResponse;
+  /** Whether this is an initial snapshot. */
+  isSnapshot?: true;
+};
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { ISubscription } from "../../../transport/mod.js";
+import type { SubscriptionConfig } from "./_types.js";
+
+/** Request parameters for the {@linkcode userFills} function. */
+export type UserFillsParameters = Omit<v.InferInput<typeof UserFillsRequest>, "type">;
+
+/**
+ * Subscribe to trade fill updates for a specific 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.
+ * @return A request-promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValidationError} 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 { userFills } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport();
+ *
+ * const sub = await userFills(
+ *   { transport },
+ *   { user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function userFills(
+  config: SubscriptionConfig,
+  params: UserFillsParameters,
+  listener: (data: UserFillsEvent) => void,
+): Promise<ISubscription> {
+  const payload = parse(UserFillsRequest, {
+    type: "userFills",
+    ...params,
+    aggregateByTime: params.aggregateByTime ?? false,
+  });
+  return config.transport.subscribe<UserFillsEvent>(payload.type, payload, (e) => {
+    if (e.detail.user === payload.user) {
+      listener(e.detail);
+    }
+  });
+}

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

@@ -0,0 +1,110 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+
+/**
+ * Subscription to user funding events for a specific user.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export const UserFundingsRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of subscription. */
+    type: v.literal("userFundings"),
+    /** User address. */
+    user: Address,
+  });
+})();
+export type UserFundingsRequest = v.InferOutput<typeof UserFundingsRequest>;
+
+/**
+ * Event of user fundings.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export type UserFundingsEvent = {
+  /**
+   * User address.
+   * @pattern ^0x[a-fA-F0-9]{40}$
+   */
+  user: `0x${string}`;
+  /** Array of user funding ledger updates. */
+  fundings: {
+    /** Timestamp of the update (in ms since epoch). */
+    time: number;
+    /** Asset symbol. */
+    coin: string;
+    /**
+     * Amount transferred in USDC.
+     * @pattern ^-?[0-9]+(\.[0-9]+)?$
+     */
+    usdc: string;
+    /**
+     * Signed position size.
+     * @pattern ^-?[0-9]+(\.[0-9]+)?$
+     */
+    szi: string;
+    /**
+     * Applied funding rate.
+     * @pattern ^-?[0-9]+(\.[0-9]+)?$
+     */
+    fundingRate: string;
+    /** Number of samples. */
+    nSamples: number | null;
+  }[];
+  /** Whether this is an initial snapshot. */
+  isSnapshot?: true | undefined;
+};
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { ISubscription } from "../../../transport/mod.js";
+import type { SubscriptionConfig } from "./_types.js";
+
+/** Request parameters for the {@linkcode userFundings} function. */
+export type UserFundingsParameters = Omit<v.InferInput<typeof UserFundingsRequest>, "type">;
+
+/**
+ * Subscribe to funding payment updates for a specific 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.
+ * @return A request-promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValidationError} 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 { userFundings } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport();
+ *
+ * const sub = await userFundings(
+ *   { transport },
+ *   { user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function userFundings(
+  config: SubscriptionConfig,
+  params: UserFundingsParameters,
+  listener: (data: UserFundingsEvent) => void,
+): Promise<ISubscription> {
+  const payload = parse(UserFundingsRequest, { type: "userFundings", ...params });
+  return config.transport.subscribe<UserFundingsEvent>(payload.type, payload, (e) => {
+    if (e.detail.user === payload.user) {
+      listener(e.detail);
+    }
+  });
+}

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

@@ -0,0 +1,89 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+import type { HistoricalOrdersResponse } from "../../info/_methods/historicalOrders.js";
+
+/**
+ * Subscription to user historical orders for a specific user.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export const UserHistoricalOrdersRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of subscription. */
+    type: v.literal("userHistoricalOrders"),
+    /** User address. */
+    user: Address,
+  });
+})();
+export type UserHistoricalOrdersRequest = v.InferOutput<typeof UserHistoricalOrdersRequest>;
+
+/**
+ * Event of user historical orders.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export type UserHistoricalOrdersEvent = {
+  /**
+   * User address.
+   * @pattern ^0x[a-fA-F0-9]{40}$
+   */
+  user: `0x${string}`;
+  /** Array of frontend orders with current processing status. */
+  orderHistory: HistoricalOrdersResponse;
+  /** Whether this is an initial snapshot. */
+  isSnapshot?: true;
+};
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { ISubscription } from "../../../transport/mod.js";
+import type { SubscriptionConfig } from "./_types.js";
+
+/** Request parameters for the {@linkcode userHistoricalOrders} function. */
+export type UserHistoricalOrdersParameters = Omit<v.InferInput<typeof UserHistoricalOrdersRequest>, "type">;
+
+/**
+ * Subscribe to historical order updates for a specific 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.
+ * @return A request-promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValidationError} 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 { userHistoricalOrders } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport();
+ *
+ * const sub = await userHistoricalOrders(
+ *   { transport },
+ *   { user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function userHistoricalOrders(
+  config: SubscriptionConfig,
+  params: UserHistoricalOrdersParameters,
+  listener: (data: UserHistoricalOrdersEvent) => void,
+): Promise<ISubscription> {
+  const payload = parse(UserHistoricalOrdersRequest, { type: "userHistoricalOrders", ...params });
+  return config.transport.subscribe<UserHistoricalOrdersEvent>(payload.type, payload, (e) => {
+    if (e.detail.user === payload.user) {
+      listener(e.detail);
+    }
+  });
+}

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

@@ -0,0 +1,92 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+import type { UserNonFundingLedgerUpdatesResponse } from "../../info/_methods/userNonFundingLedgerUpdates.js";
+
+/**
+ * Subscription to user non-funding ledger updates for a specific user.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export const UserNonFundingLedgerUpdatesRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of subscription. */
+    type: v.literal("userNonFundingLedgerUpdates"),
+    /** User address. */
+    user: Address,
+  });
+})();
+export type UserNonFundingLedgerUpdatesRequest = v.InferOutput<typeof UserNonFundingLedgerUpdatesRequest>;
+
+/**
+ * Event of user non-funding ledger updates.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export type UserNonFundingLedgerUpdatesEvent = {
+  /**
+   * User address.
+   * @pattern ^0x[a-fA-F0-9]{40}$
+   */
+  user: `0x${string}`;
+  /** Array of user's non-funding ledger update. */
+  nonFundingLedgerUpdates: UserNonFundingLedgerUpdatesResponse;
+  /** Whether this is an initial snapshot. */
+  isSnapshot?: true;
+};
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { ISubscription } from "../../../transport/mod.js";
+import type { SubscriptionConfig } from "./_types.js";
+
+/** Request parameters for the {@linkcode userNonFundingLedgerUpdates} function. */
+export type UserNonFundingLedgerUpdatesParameters = Omit<
+  v.InferInput<typeof UserNonFundingLedgerUpdatesRequest>,
+  "type"
+>;
+
+/**
+ * Subscribe to non-funding ledger updates for a specific 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.
+ * @return A request-promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValidationError} 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 { userNonFundingLedgerUpdates } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport();
+ *
+ * const sub = await userNonFundingLedgerUpdates(
+ *   { transport },
+ *   { user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function userNonFundingLedgerUpdates(
+  config: SubscriptionConfig,
+  params: UserNonFundingLedgerUpdatesParameters,
+  listener: (data: UserNonFundingLedgerUpdatesEvent) => void,
+): Promise<ISubscription> {
+  const payload = parse(UserNonFundingLedgerUpdatesRequest, { type: "userNonFundingLedgerUpdates", ...params });
+  return config.transport.subscribe<UserNonFundingLedgerUpdatesEvent>(payload.type, payload, (e) => {
+    if (e.detail.user === payload.user) {
+      listener(e.detail);
+    }
+  });
+}

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

@@ -0,0 +1,89 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+import type { TwapHistoryResponse } from "../../info/_methods/twapHistory.js";
+
+/**
+ * Subscription to user TWAP history events for a specific user.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export const UserTwapHistoryRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of subscription. */
+    type: v.literal("userTwapHistory"),
+    /** User address. */
+    user: Address,
+  });
+})();
+export type UserTwapHistoryRequest = v.InferOutput<typeof UserTwapHistoryRequest>;
+
+/**
+ * Event of user TWAP history.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export type UserTwapHistoryEvent = {
+  /**
+   * User address.
+   * @pattern ^0x[a-fA-F0-9]{40}$
+   */
+  user: `0x${string}`;
+  /** Array of user's TWAP history. */
+  history: TwapHistoryResponse;
+  /** Whether this is an initial snapshot. */
+  isSnapshot?: true;
+};
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { ISubscription } from "../../../transport/mod.js";
+import type { SubscriptionConfig } from "./_types.js";
+
+/** Request parameters for the {@linkcode userTwapHistory} function. */
+export type UserTwapHistoryParameters = Omit<v.InferInput<typeof UserTwapHistoryRequest>, "type">;
+
+/**
+ * Subscribe to TWAP order history updates for a specific 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.
+ * @return A request-promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+ *
+ * @throws {ValidationError} 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 { userTwapHistory } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport();
+ *
+ * const sub = await userTwapHistory(
+ *   { transport },
+ *   { user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ */
+export function userTwapHistory(
+  config: SubscriptionConfig,
+  params: UserTwapHistoryParameters,
+  listener: (data: UserTwapHistoryEvent) => void,
+): Promise<ISubscription> {
+  const payload = parse(UserTwapHistoryRequest, { type: "userTwapHistory", ...params });
+  return config.transport.subscribe<UserTwapHistoryEvent>(payload.type, payload, (e) => {
+    if (e.detail.user === payload.user) {
+      listener(e.detail);
+    }
+  });
+}