@nktkas/hyperliquid 0.25.1 → 0.25.3

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

@@ -1,8 +1,10 @@
 import * as v from "valibot";
-import { Address, Decimal, type DeepImmutable, Hex, parser, UnsignedDecimal, UnsignedInteger } from "../_common.js";
-import type { SubscriptionRequestConfig } from "./_common.js";
+import { Address, Decimal, type DeepImmutable, parser, UnsignedDecimal, UnsignedInteger } from "../_base.js";
+import type { SubscriptionRequestConfig } from "./_base.js";
 import type { Subscription } from "../../transport/base.js";
 
+import { FillSchema, TwapFillSchema, TwapStateSchema, TwapStatusSchema } from "../_common_schemas.js";
+
 // -------------------- Schemas --------------------
 
 /** Subscription to user events for a specific user. */
@@ -31,117 +33,7 @@ export const FillEvent = /* @__PURE__ */ (() => {
     v.object({
       /** Array of user trade fills. */
       fills: v.pipe(
-        v.array(
-          /** Trade fill record. */
-          v.pipe(
-            v.object({
-              /** Asset symbol. */
-              coin: v.pipe(
-                v.string(),
-                v.description("Asset symbol."),
-              ),
-              /** Price. */
-              px: v.pipe(
-                UnsignedDecimal,
-                v.description("Price."),
-              ),
-              /** Size. */
-              sz: v.pipe(
-                UnsignedDecimal,
-                v.description("Size."),
-              ),
-              /** Order side ("B" = Bid/Buy, "A" = Ask/Sell). */
-              side: v.pipe(
-                v.union([v.literal("B"), v.literal("A")]),
-                v.description('Order side ("B" = Bid/Buy, "A" = Ask/Sell).'),
-              ),
-              /** Timestamp when the trade occurred (in ms since epoch). */
-              time: v.pipe(
-                UnsignedInteger,
-                v.description("Timestamp when the trade occurred (in ms since epoch)."),
-              ),
-              /** Start position size. */
-              startPosition: v.pipe(
-                Decimal,
-                v.description("Start position size."),
-              ),
-              /** Direction indicator for frontend display. */
-              dir: v.pipe(
-                v.string(),
-                v.description("Direction indicator for frontend display."),
-              ),
-              /** Realized PnL. */
-              closedPnl: v.pipe(
-                Decimal,
-                v.description("Realized PnL."),
-              ),
-              /** L1 transaction hash. */
-              hash: v.pipe(
-                v.pipe(Hex, v.length(66)),
-                v.description("L1 transaction hash."),
-              ),
-              /** Order ID. */
-              oid: v.pipe(
-                UnsignedInteger,
-                v.description("Order ID."),
-              ),
-              /** Indicates if the fill was a taker order. */
-              crossed: v.pipe(
-                v.boolean(),
-                v.description("Indicates if the fill was a taker order."),
-              ),
-              /** Fee charged or rebate received (negative indicates rebate). */
-              fee: v.pipe(
-                Decimal,
-                v.description("Fee charged or rebate received (negative indicates rebate)."),
-              ),
-              /** Unique transaction identifier for a partial fill of an order. */
-              tid: v.pipe(
-                UnsignedInteger,
-                v.description("Unique transaction identifier for a partial fill of an order."),
-              ),
-              /** Client Order ID. */
-              cloid: v.pipe(
-                v.optional(v.pipe(Hex, v.length(34))),
-                v.description("Client Order ID."),
-              ),
-              /** Liquidation details. */
-              liquidation: v.pipe(
-                v.optional(
-                  v.object({
-                    /** Address of the liquidated user. */
-                    liquidatedUser: v.pipe(
-                      Address,
-                      v.description("Address of the liquidated user."),
-                    ),
-                    /** Mark price at the time of liquidation. */
-                    markPx: v.pipe(
-                      UnsignedDecimal,
-                      v.description("Mark price at the time of liquidation."),
-                    ),
-                    /** Liquidation method. */
-                    method: v.pipe(
-                      v.union([v.literal("market"), v.literal("backstop")]),
-                      v.description("Liquidation method."),
-                    ),
-                  }),
-                ),
-                v.description("Liquidation details."),
-              ),
-              /** Token in which the fee is denominated (e.g., "USDC"). */
-              feeToken: v.pipe(
-                v.string(),
-                v.description('Token in which the fee is denominated (e.g., "USDC").'),
-              ),
-              /** ID of the TWAP. */
-              twapId: v.pipe(
-                v.union([UnsignedInteger, v.null()]),
-                v.description("ID of the TWAP."),
-              ),
-            }),
-            v.description("Trade fill record."),
-          ),
-        ),
+        v.array(FillSchema),
         v.description("Array of user trade fills."),
       ),
     }),
@@ -179,7 +71,7 @@ export const FundingEvent = /* @__PURE__ */ (() => {
           ),
           /** Number of samples. */
           nSamples: v.pipe(
-            v.union([UnsignedInteger, v.null()]),
+            v.nullable(UnsignedInteger),
             v.description("Number of samples."),
           ),
         }),
@@ -280,101 +172,13 @@ export const TwapHistoryEvent = /* @__PURE__ */ (() => {
                 v.description("Creation time of the history record (in seconds since epoch)."),
               ),
               /** State of the TWAP order. */
-              state: v.pipe(
-                v.object({
-                  /** Asset symbol. */
-                  coin: v.pipe(
-                    v.string(),
-                    v.description("Asset symbol."),
-                  ),
-                  /** Executed notional value. */
-                  executedNtl: v.pipe(
-                    UnsignedDecimal,
-                    v.description("Executed notional value."),
-                  ),
-                  /** Executed size. */
-                  executedSz: v.pipe(
-                    UnsignedDecimal,
-                    v.description("Executed size."),
-                  ),
-                  /** Duration in minutes. */
-                  minutes: v.pipe(
-                    UnsignedInteger,
-                    v.description("Duration in minutes."),
-                  ),
-                  /** Indicates if the TWAP randomizes execution. */
-                  randomize: v.pipe(
-                    v.boolean(),
-                    v.description("Indicates if the TWAP randomizes execution."),
-                  ),
-                  /** Indicates if the order is reduce-only. */
-                  reduceOnly: v.pipe(
-                    v.boolean(),
-                    v.description("Indicates if the order is reduce-only."),
-                  ),
-                  /** Order side ("B" = Bid/Buy, "A" = Ask/Sell). */
-                  side: v.pipe(
-                    v.union([v.literal("B"), v.literal("A")]),
-                    v.description('Order side ("B" = Bid/Buy, "A" = Ask/Sell).'),
-                  ),
-                  /** Order size. */
-                  sz: v.pipe(
-                    UnsignedDecimal,
-                    v.description("Order size."),
-                  ),
-                  /** Start time of the TWAP order (in ms since epoch). */
-                  timestamp: v.pipe(
-                    UnsignedInteger,
-                    v.description("Start time of the TWAP order (in ms since epoch)."),
-                  ),
-                  /** User address. */
-                  user: v.pipe(
-                    Address,
-                    v.description("User address."),
-                  ),
-                }),
-                v.description("State of the TWAP order."),
-              ),
-              /**
-               * Current status of the TWAP order.
-               * - `"finished"`: Fully executed.
-               * - `"activated"`: Active and executing.
-               * - `"terminated"`: Terminated.
-               * - `"error"`: An error occurred.
-               */
-              status: v.pipe(
-                v.union([
-                  v.object({
-                    /** Status of the TWAP order. */
-                    status: v.pipe(
-                      v.union([
-                        v.literal("finished"),
-                        v.literal("activated"),
-                        v.literal("terminated"),
-                      ]),
-                      v.description("Status of the TWAP order."),
-                    ),
-                  }),
-                  v.object({
-                    /** Status of the TWAP order. */
-                    status: v.pipe(
-                      v.literal("error"),
-                      v.description("Status of the TWAP order."),
-                    ),
-                    /** Error message. */
-                    description: v.pipe(
-                      v.string(),
-                      v.description("Error message."),
-                    ),
-                  }),
-                ]),
-                v.description(
-                  "Current status of the TWAP order." +
-                    '\n- `"finished"`: Fully executed. ' +
-                    '\n- `"activated"`: Active and executing. ' +
-                    '\n- `"terminated"`: Terminated. ' +
-                    '\n- `"error"`: An error occurred.',
-                ),
+              state: TwapStateSchema,
+              /** Current status of the TWAP order. */
+              status: TwapStatusSchema,
+              /** TWAP ID. */
+              twapId: v.pipe(
+                UnsignedInteger,
+                v.description("TWAP ID."),
               ),
             }),
             v.description("TWAP history record."),
@@ -394,89 +198,7 @@ export const TwapSliceFillsEvent = /* @__PURE__ */ (() => {
     v.object({
       /** Array of TWAP slice fills. */
       twapSliceFills: v.pipe(
-        v.array(
-          /** Fill details for the TWAP slice. */
-          v.pipe(
-            v.object({
-              /** Asset symbol. */
-              coin: v.pipe(
-                v.string(),
-                v.description("Asset symbol."),
-              ),
-              /** Price. */
-              px: v.pipe(
-                UnsignedDecimal,
-                v.description("Price."),
-              ),
-              /** Size. */
-              sz: v.pipe(
-                UnsignedDecimal,
-                v.description("Size."),
-              ),
-              /** Order side ("B" = Bid/Buy, "A" = Ask/Sell). */
-              side: v.pipe(
-                v.union([v.literal("B"), v.literal("A")]),
-                v.description('Order side ("B" = Bid/Buy, "A" = Ask/Sell).'),
-              ),
-              /** Timestamp when the trade occurred (in ms since epoch). */
-              time: v.pipe(
-                UnsignedInteger,
-                v.description("Timestamp when the trade occurred (in ms since epoch)."),
-              ),
-              /** Start position size. */
-              startPosition: v.pipe(
-                Decimal,
-                v.description("Start position size."),
-              ),
-              /** Direction indicator for frontend display. */
-              dir: v.pipe(
-                v.string(),
-                v.description("Direction indicator for frontend display."),
-              ),
-              /** Realized PnL. */
-              closedPnl: v.pipe(
-                Decimal,
-                v.description("Realized PnL."),
-              ),
-              /** L1 transaction hash. */
-              hash: v.pipe(
-                v.pipe(Hex, v.length(66)),
-                v.description("L1 transaction hash."),
-              ),
-              /** Order ID. */
-              oid: v.pipe(
-                UnsignedInteger,
-                v.description("Order ID."),
-              ),
-              /** Indicates if the fill was a taker order. */
-              crossed: v.pipe(
-                v.boolean(),
-                v.description("Indicates if the fill was a taker order."),
-              ),
-              /** Fee charged or rebate received (negative indicates rebate). */
-              fee: v.pipe(
-                Decimal,
-                v.description("Fee charged or rebate received (negative indicates rebate)."),
-              ),
-              /** Unique transaction identifier for a partial fill of an order. */
-              tid: v.pipe(
-                UnsignedInteger,
-                v.description("Unique transaction identifier for a partial fill of an order."),
-              ),
-              /** Token in which the fee is denominated (e.g., "USDC"). */
-              feeToken: v.pipe(
-                v.string(),
-                v.description('Token in which the fee is denominated (e.g., "USDC").'),
-              ),
-              /** ID of the TWAP. */
-              twapId: v.pipe(
-                v.union([UnsignedInteger, v.null()]),
-                v.description("ID of the TWAP."),
-              ),
-            }),
-            v.description("Fill details for the TWAP slice."),
-          ),
-        ),
+        v.array(TwapFillSchema),
         v.description("Array of TWAP slice fills."),
       ),
     }),

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

@@ -1,8 +1,10 @@
 import * as v from "valibot";
-import { Address, Decimal, type DeepImmutable, Hex, parser, UnsignedDecimal, UnsignedInteger } from "../_common.js";
-import type { SubscriptionRequestConfig } from "./_common.js";
+import { Address, type DeepImmutable, parser } from "../_base.js";
+import type { SubscriptionRequestConfig } from "./_base.js";
 import type { Subscription } from "../../transport/base.js";
 
+import { FillSchema } from "../_common_schemas.js";
+
 // -------------------- Schemas --------------------
 
 /** Subscription to user fill events for a specific user. */
@@ -41,117 +43,7 @@ export const UserFillsEvent = /* @__PURE__ */ (() => {
       ),
       /** Array of user trade fills. */
       fills: v.pipe(
-        v.array(
-          /** Trade fill record. */
-          v.pipe(
-            v.object({
-              /** Asset symbol. */
-              coin: v.pipe(
-                v.string(),
-                v.description("Asset symbol."),
-              ),
-              /** Price. */
-              px: v.pipe(
-                UnsignedDecimal,
-                v.description("Price."),
-              ),
-              /** Size. */
-              sz: v.pipe(
-                UnsignedDecimal,
-                v.description("Size."),
-              ),
-              /** Order side ("B" = Bid/Buy, "A" = Ask/Sell). */
-              side: v.pipe(
-                v.union([v.literal("B"), v.literal("A")]),
-                v.description('Order side ("B" = Bid/Buy, "A" = Ask/Sell).'),
-              ),
-              /** Timestamp when the trade occurred (in ms since epoch). */
-              time: v.pipe(
-                UnsignedInteger,
-                v.description("Timestamp when the trade occurred (in ms since epoch)."),
-              ),
-              /** Start position size. */
-              startPosition: v.pipe(
-                Decimal,
-                v.description("Start position size."),
-              ),
-              /** Direction indicator for frontend display. */
-              dir: v.pipe(
-                v.string(),
-                v.description("Direction indicator for frontend display."),
-              ),
-              /** Realized PnL. */
-              closedPnl: v.pipe(
-                Decimal,
-                v.description("Realized PnL."),
-              ),
-              /** L1 transaction hash. */
-              hash: v.pipe(
-                v.pipe(Hex, v.length(66)),
-                v.description("L1 transaction hash."),
-              ),
-              /** Order ID. */
-              oid: v.pipe(
-                UnsignedInteger,
-                v.description("Order ID."),
-              ),
-              /** Indicates if the fill was a taker order. */
-              crossed: v.pipe(
-                v.boolean(),
-                v.description("Indicates if the fill was a taker order."),
-              ),
-              /** Fee charged or rebate received (negative indicates rebate). */
-              fee: v.pipe(
-                Decimal,
-                v.description("Fee charged or rebate received (negative indicates rebate)."),
-              ),
-              /** Unique transaction identifier for a partial fill of an order. */
-              tid: v.pipe(
-                UnsignedInteger,
-                v.description("Unique transaction identifier for a partial fill of an order."),
-              ),
-              /** Client Order ID. */
-              cloid: v.pipe(
-                v.optional(v.pipe(Hex, v.length(34))),
-                v.description("Client Order ID."),
-              ),
-              /** Liquidation details. */
-              liquidation: v.pipe(
-                v.optional(
-                  v.object({
-                    /** Address of the liquidated user. */
-                    liquidatedUser: v.pipe(
-                      Address,
-                      v.description("Address of the liquidated user."),
-                    ),
-                    /** Mark price at the time of liquidation. */
-                    markPx: v.pipe(
-                      UnsignedDecimal,
-                      v.description("Mark price at the time of liquidation."),
-                    ),
-                    /** Liquidation method. */
-                    method: v.pipe(
-                      v.union([v.literal("market"), v.literal("backstop")]),
-                      v.description("Liquidation method."),
-                    ),
-                  }),
-                ),
-                v.description("Liquidation details."),
-              ),
-              /** Token in which the fee is denominated (e.g., "USDC"). */
-              feeToken: v.pipe(
-                v.string(),
-                v.description('Token in which the fee is denominated (e.g., "USDC").'),
-              ),
-              /** ID of the TWAP. */
-              twapId: v.pipe(
-                v.union([UnsignedInteger, v.null()]),
-                v.description("ID of the TWAP."),
-              ),
-            }),
-            v.description("Trade fill record."),
-          ),
-        ),
+        v.array(FillSchema),
         v.description("Array of user trade fills."),
       ),
       /** Whether this is an initial snapshot. */
@@ -205,7 +97,7 @@ export function userFills(
     aggregateByTime: params.aggregateByTime ?? false,
   });
   return config.transport.subscribe<UserFillsEvent>(payload.type, payload, (e) => {
-    if (e.detail.user === payload.user.toLowerCase()) {
+    if (e.detail.user === payload.user) {
       listener(e.detail);
     }
   });

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

@@ -1,6 +1,6 @@
 import * as v from "valibot";
-import { Address, Decimal, type DeepImmutable, parser, UnsignedInteger } from "../_common.js";
-import type { SubscriptionRequestConfig } from "./_common.js";
+import { Address, Decimal, type DeepImmutable, parser, UnsignedInteger } from "../_base.js";
+import type { SubscriptionRequestConfig } from "./_base.js";
 import type { Subscription } from "../../transport/base.js";
 
 // -------------------- Schemas --------------------
@@ -67,7 +67,7 @@ export const UserFundingsEvent = /* @__PURE__ */ (() => {
               ),
               /** Number of samples. */
               nSamples: v.pipe(
-                v.union([UnsignedInteger, v.null()]),
+                v.nullable(UnsignedInteger),
                 v.description("Number of samples."),
               ),
             }),
@@ -123,7 +123,7 @@ export function userFundings(
 ): Promise<Subscription> {
   const payload = parser(UserFundingsRequest)({ type: "userFundings", ...params });
   return config.transport.subscribe<UserFundingsEvent>(payload.type, payload, (e) => {
-    if (e.detail.user === payload.user.toLowerCase()) {
+    if (e.detail.user === payload.user) {
       listener(e.detail);
     }
   });

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

@@ -0,0 +1,111 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser, UnsignedInteger } from "../_base.js";
+import type { SubscriptionRequestConfig } from "./_base.js";
+import type { Subscription } from "../../transport/base.js";
+
+import { DetailedOrderSchema, OrderProcessingStatusSchema } from "../_common_schemas.js";
+
+// -------------------- Schemas --------------------
+
+/** Subscription to user historical orders for a specific user. */
+export const UserHistoricalOrdersRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of subscription. */
+      type: v.pipe(
+        v.literal("userHistoricalOrders"),
+        v.description("Type of subscription."),
+      ),
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+    }),
+    v.description("Subscription to user historical orders for a specific user."),
+  );
+})();
+export type UserHistoricalOrdersRequest = v.InferOutput<typeof UserHistoricalOrdersRequest>;
+
+/** Event of user historical orders. */
+export const UserHistoricalOrdersEvent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+      /** Array of frontend orders with current processing status. */
+      orderHistory: v.pipe(
+        v.array(
+          /** Frontend order with current processing status. */
+          v.pipe(
+            v.object({
+              /** Order details. */
+              order: DetailedOrderSchema,
+              /** Order processing status. */
+              status: OrderProcessingStatusSchema,
+              /** Timestamp when the status was last updated (in ms since epoch). */
+              statusTimestamp: v.pipe(
+                UnsignedInteger,
+                v.description("Timestamp when the status was last updated (in ms since epoch)."),
+              ),
+            }),
+            v.description("Frontend order with current processing status."),
+          ),
+        ),
+        v.description("Array of frontend orders with current processing status."),
+      ),
+      /** Whether this is an initial snapshot. */
+      isSnapshot: v.pipe(
+        v.optional(v.literal(true)),
+        v.description("Whether this is an initial snapshot."),
+      ),
+    }),
+    v.description("Event of user historical orders."),
+  );
+})();
+export type UserHistoricalOrdersEvent = v.InferOutput<typeof UserHistoricalOrdersEvent>;
+
+// -------------------- Function --------------------
+
+/** 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.
+ * @returns A request-promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ * @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),
+ * );
+ * ```
+ */
+export function userHistoricalOrders(
+  config: SubscriptionRequestConfig,
+  params: DeepImmutable<UserHistoricalOrdersParameters>,
+  listener: (data: UserHistoricalOrdersEvent) => void,
+): Promise<Subscription> {
+  const payload = parser(UserHistoricalOrdersRequest)({ type: "userHistoricalOrders", ...params });
+  return config.transport.subscribe<UserHistoricalOrdersEvent>(payload.type, payload, (e) => {
+    if (e.detail.user === payload.user) {
+      listener(e.detail);
+    }
+  });
+}