@hfunlabs/hyperliquid 0.29.1-hfunlabs.1 → 0.30.2-hfunlabs.2

package/src/src/transport/websocket/_postRequest.ts

@@ -1,5 +1,5 @@
-import { TransportError } from "../../_errors.js";
-import { Promise_ } from "../_polyfills.js";
+import { TransportError } from "../_base.js";
+import { AbortSignal_, Promise_ } from "../_polyfills.js";
 import type { ReconnectingWebSocket } from "@nktkas/rews";
 import type { HyperliquidEventTarget } from "./_hyperliquidEventTarget.js";
 
@@ -33,32 +33,38 @@ export class WebSocketRequestError extends TransportError {
 }
 
 /**
- * Manages WebSocket requests to the Hyperliquid API.
+ * Manages WebSocket post requests to the Hyperliquid API.
  * Handles request creation, sending, and mapping responses to their corresponding requests.
  */
-export class WebSocketAsyncRequest {
-  protected socket: ReconnectingWebSocket;
-  protected lastId = 0;
-  protected queue: PendingRequest[] = [];
+export class WebSocketPostRequest {
+  /** Timeout for requests in ms. Set to `null` to disable. */
+  timeout: number | null;
+
+  protected _socket: ReconnectingWebSocket;
+  protected _lastId = 0;
+  protected _queue: PendingRequest[] = [];
 
   /**
    * Creates a new WebSocket async request handler.
+   *
    * @param socket - WebSocket connection instance for sending requests to the Hyperliquid WebSocket API
    * @param hlEvents - Used to recognize Hyperliquid responses and match them with sent requests
+   * @param timeout - Timeout for requests in ms. Set to `null` to disable.
    */
-  constructor(socket: ReconnectingWebSocket, hlEvents: HyperliquidEventTarget) {
-    this.socket = socket;
+  constructor(socket: ReconnectingWebSocket, hlEvents: HyperliquidEventTarget, timeout: number | null) {
+    this.timeout = timeout;
+    this._socket = socket;
 
     // Monitor responses and match the pending request
     hlEvents.addEventListener("subscriptionResponse", (event) => {
-      this.queue
+      this._queue
         // NOTE: API may add new fields over time, so perform a loose check of the payload.
         .find((x) => typeof x.id === "string" && isSubset(JSON.parse(x.id), event.detail))
         ?.resolve(event.detail);
     });
     hlEvents.addEventListener("post", (event) => {
       if (event.detail.response.type === "error") {
-        this.queue
+        this._queue
           .find((x) => x.id === event.detail.id)
           ?.reject(new WebSocketRequestError(event.detail.response.payload));
         return;
@@ -66,10 +72,10 @@ export class WebSocketAsyncRequest {
       const data = event.detail.response.type === "info"
         ? event.detail.response.payload.data
         : event.detail.response.payload;
-      this.queue.find((x) => x.id === event.detail.id)?.resolve(data);
+      this._queue.find((x) => x.id === event.detail.id)?.resolve(data);
     });
     hlEvents.addEventListener("pong", () => {
-      this.queue.find((x) => x.id === "ping")?.resolve();
+      this._queue.find((x) => x.id === "ping")?.resolve();
     });
     hlEvents.addEventListener("error", (event) => {
       try {
@@ -77,7 +83,7 @@ export class WebSocketAsyncRequest {
         const idMatch = event.detail.match(/id=(\d+)$/);
         if (idMatch) {
           const id = parseInt(idMatch[1], 10);
-          this.queue.find((x) => x.id === id)
+          this._queue.find((x) => x.id === id)
             ?.reject(new WebSocketRequestError(event.detail));
           return;
         }
@@ -90,7 +96,7 @@ export class WebSocketAsyncRequest {
 
         // For `post` requests
         if ("id" in parsedRequest && typeof parsedRequest.id === "number") {
-          this.queue.find((x) => x.id === parsedRequest.id)
+          this._queue.find((x) => x.id === parsedRequest.id)
             ?.reject(new WebSocketRequestError(event.detail));
           return;
         }
@@ -100,8 +106,8 @@ export class WebSocketAsyncRequest {
           "subscription" in parsedRequest &&
           typeof parsedRequest.subscription === "object" && parsedRequest.subscription !== null
         ) {
-          const id = WebSocketAsyncRequest.requestToId(parsedRequest);
-          this.queue.find((x) => x.id === id)
+          const id = WebSocketPostRequest.requestToId(parsedRequest);
+          this._queue.find((x) => x.id === id)
             ?.reject(new WebSocketRequestError(event.detail));
           return;
         }
@@ -111,29 +117,29 @@ export class WebSocketAsyncRequest {
           event.detail.startsWith("Already subscribed") ||
           event.detail.startsWith("Invalid subscription")
         ) {
-          const id = WebSocketAsyncRequest.requestToId({
+          const id = WebSocketPostRequest.requestToId({
             method: "subscribe",
             subscription: parsedRequest,
           });
-          this.queue.find((x) => x.id === id)
+          this._queue.find((x) => x.id === id)
             ?.reject(new WebSocketRequestError(event.detail));
           return;
         }
 
         // For `Already unsubscribed` requests
         if (event.detail.startsWith("Already unsubscribed")) {
-          const id = WebSocketAsyncRequest.requestToId({
+          const id = WebSocketPostRequest.requestToId({
             method: "unsubscribe",
             subscription: parsedRequest,
           });
-          this.queue.find((x) => x.id === id)
+          this._queue.find((x) => x.id === id)
             ?.reject(new WebSocketRequestError(event.detail));
           return;
         }
 
         // For unknown requests
-        const id = WebSocketAsyncRequest.requestToId(parsedRequest);
-        this.queue.find((x) => x.id === id)
+        const id = WebSocketPostRequest.requestToId(parsedRequest);
+        this._queue.find((x) => x.id === id)
           ?.reject(new WebSocketRequestError(event.detail));
       } catch {
         // Ignore JSON parsing errors
@@ -142,10 +148,10 @@ export class WebSocketAsyncRequest {
 
     // Throws all pending requests if the connection is dropped
     const handleClose = () => {
-      this.queue.forEach(({ reject }) => {
-        reject(new WebSocketRequestError("WebSocket connection closed."));
+      this._queue.forEach(({ reject }) => {
+        reject(new WebSocketRequestError("WebSocket connection closed"));
       });
-      this.queue = [];
+      this._queue = [];
     };
     socket.addEventListener("close", handleClose);
     socket.addEventListener("error", handleClose);
@@ -153,6 +159,7 @@ export class WebSocketAsyncRequest {
 
   /**
    * Sends a request to the Hyperliquid API.
+   *
    * @returns A promise that resolves with the parsed JSON response body.
    */
   async request(method: "ping", signal?: AbortSignal): Promise<void>;
@@ -162,46 +169,59 @@ export class WebSocketAsyncRequest {
     payloadOrSignal?: unknown | AbortSignal,
     maybeSignal?: AbortSignal,
   ): Promise<T> {
-    const payload = payloadOrSignal instanceof AbortSignal ? undefined : payloadOrSignal;
-    const signal = payloadOrSignal instanceof AbortSignal ? payloadOrSignal : maybeSignal;
+    try {
+      const payload = payloadOrSignal instanceof AbortSignal ? undefined : payloadOrSignal;
+      const userSignal = payloadOrSignal instanceof AbortSignal ? payloadOrSignal : maybeSignal;
 
-    // Reject the request if the signal is aborted
-    if (signal?.aborted) return Promise.reject(signal.reason);
-    // or if the WebSocket connection is permanently closed
-    if (this.socket.terminationSignal.aborted) {
-      return Promise.reject(this.socket.terminationSignal.reason);
-    }
+      const timeoutSignal = this.timeout ? AbortSignal_.timeout(this.timeout) : undefined;
+      const signal = userSignal && timeoutSignal
+        ? AbortSignal_.any([userSignal, timeoutSignal])
+        : userSignal ?? timeoutSignal;
 
-    // Create a request
-    let id: string | number;
-    let request: SubscribeUnsubscribeRequest | PostRequest | PingRequest;
-    if (method === "post") {
-      id = ++this.lastId;
-      request = { method, id, request: payload };
-    } else if (method === "ping") {
-      id = "ping";
-      request = { method };
-    } else {
-      request = { method, subscription: payload };
-      id = WebSocketAsyncRequest.requestToId(request);
-    }
+      // Reject the request if the signal is aborted
+      if (signal?.aborted) return Promise.reject(signal.reason);
+      // or if the WebSocket connection is permanently closed
+      if (this._socket.terminationSignal.aborted) {
+        return Promise.reject(this._socket.terminationSignal.reason);
+      }
 
-    // Send the request
-    this.socket.send(JSON.stringify(request));
+      // Create a request
+      let id: string | number;
+      let request: SubscribeUnsubscribeRequest | PostRequest | PingRequest;
+      if (method === "post") {
+        id = ++this._lastId;
+        request = { method, id, request: payload };
+      } else if (method === "ping") {
+        id = "ping";
+        request = { method };
+      } else {
+        request = { method, subscription: payload };
+        id = WebSocketPostRequest.requestToId(request);
+      }
 
-    // Wait for a response
-    const { promise, resolve, reject } = Promise_.withResolvers<T>();
-    this.queue.push({ id, resolve, reject });
+      // Send the request
+      this._socket.send(JSON.stringify(request));
 
-    const onAbort = () => reject(signal?.reason);
-    signal?.addEventListener("abort", onAbort, { once: true });
+      // Wait for a response
+      const { promise, resolve, reject } = Promise_.withResolvers<T>();
+      this._queue.push({ id, resolve, reject });
 
-    return await promise.finally(() => {
-      const index = this.queue.findIndex((item) => item.id === id);
-      if (index !== -1) this.queue.splice(index, 1);
+      const onAbort = () => reject(signal?.reason);
+      signal?.addEventListener("abort", onAbort, { once: true });
 
-      signal?.removeEventListener("abort", onAbort);
-    });
+      return await promise.finally(() => {
+        const index = this._queue.findIndex((item) => item.id === id);
+        if (index !== -1) this._queue.splice(index, 1);
+
+        signal?.removeEventListener("abort", onAbort);
+      });
+    } catch (error) {
+      if (error instanceof TransportError) throw error; // Re-throw known errors
+      throw new WebSocketRequestError(
+        `Unknown error while making a WebSocket request: ${error}`,
+        { cause: error },
+      );
+    }
   }
 
   /** Normalizes an object and then converts it to a string. */
@@ -235,8 +255,8 @@ function recursiveHexToLowercase(value: unknown): unknown {
   }
   if (typeof value === "object" && value !== null) {
     const result: Record<string, unknown> = {};
-    for (const k in value) {
-      result[k] = recursiveHexToLowercase((value as Record<string, unknown>)[k]);
+    for (const key in value) {
+      result[key] = recursiveHexToLowercase((value as Record<string, unknown>)[key]);
     }
     return result;
   }

package/src/src/transport/websocket/_subscriptionManager.ts

@@ -1,6 +1,7 @@
 import type { ReconnectingWebSocket } from "@nktkas/rews";
+import type { ISubscription } from "../_base.js";
 import type { HyperliquidEventTarget } from "./_hyperliquidEventTarget.js";
-import { WebSocketAsyncRequest, WebSocketRequestError } from "./_postRequest.js";
+import { WebSocketPostRequest, WebSocketRequestError } from "./_postRequest.js";
 
 /** Maximum number of subscriptions allowed by Hyperliquid. */
 const MAX_SUBSCRIPTIONS = 1000;
@@ -8,15 +9,6 @@ const MAX_SUBSCRIPTIONS = 1000;
 /** Maximum number of unique user subscriptions allowed by Hyperliquid. */
 const MAX_UNIQUE_USER_SUBSCRIPTIONS = 10;
 
-/** WebSocket subscription with failure signal. */
-export interface WebSocketSubscription {
-  /** Removes the event listener and unsubscribes from the event channel. */
-  unsubscribe(): Promise<void>;
-
-  /** [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that is aborted if the subscription fails to restore after reconnection. */
-  failureSignal: AbortSignal;
-}
-
 /** Internal state for managing a subscription. */
 interface SubscriptionState {
   /** Map of event listeners to their unsubscribe functions. */
@@ -38,18 +30,18 @@ export class WebSocketSubscriptionManager {
   resubscribe: boolean;
 
   protected _socket: ReconnectingWebSocket;
-  protected _wsRequester: WebSocketAsyncRequest;
+  protected _postRequest: WebSocketPostRequest;
   protected _hlEvents: HyperliquidEventTarget;
   protected _subscriptions: Map<string, SubscriptionState> = new Map();
 
   constructor(
     socket: ReconnectingWebSocket,
-    wsRequester: WebSocketAsyncRequest,
+    postRequest: WebSocketPostRequest,
     hlEvents: HyperliquidEventTarget,
     resubscribe: boolean,
   ) {
     this._socket = socket;
-    this._wsRequester = wsRequester;
+    this._postRequest = postRequest;
     this._hlEvents = hlEvents;
     this.resubscribe = resubscribe;
 
@@ -71,7 +63,7 @@ export class WebSocketSubscriptionManager {
    * @param payload - A payload to send with the subscription request.
    * @param listener - A function to call when the event is dispatched.
    *
-   * @returns A promise that resolves with a {@link WebSocketSubscription} object to manage the subscription lifecycle.
+   * @returns A promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
    *
    * @throws {WebSocketRequestError} - An error that occurs when a WebSocket request fails.
    */
@@ -79,24 +71,24 @@ export class WebSocketSubscriptionManager {
     channel: string,
     payload: unknown,
     listener: (data: CustomEvent<T>) => void,
-  ): Promise<WebSocketSubscription> {
+  ): Promise<ISubscription> {
     // Create a unique identifier for the subscription
-    const id = WebSocketAsyncRequest.requestToId(payload);
+    const id = WebSocketPostRequest.requestToId(payload);
 
     // Initialize new subscription, if it doesn't exist
     let subscription = this._subscriptions.get(id);
     if (!subscription) {
       // Check unique subscription limits
       if (this._subscriptions.size >= MAX_SUBSCRIPTIONS) {
-        throw new WebSocketRequestError("Cannot subscribe to more than 1000 channels.");
+        throw new WebSocketRequestError("Cannot subscribe to more than 1000 channels");
       }
       // Check unique user subscription limits
       if (this._hasUserParam(payload) && this._countUniqueUserSubscriptions() >= MAX_UNIQUE_USER_SUBSCRIPTIONS) {
-        throw new WebSocketRequestError("Cannot track more than 10 unique users.");
+        throw new WebSocketRequestError("Cannot track more than 10 unique users");
       }
 
       // Send subscription request
-      const promise = this._wsRequester.request("subscribe", payload)
+      const promise = this._postRequest.request("subscribe", payload)
         .finally(() => subscription!.promiseFinished = true);
 
       // Cache subscription info
@@ -126,7 +118,7 @@ export class WebSocketSubscriptionManager {
 
           // If the socket is open, send unsubscription request
           if (this._socket.readyState === 1) { // OPEN
-            await this._wsRequester.request("unsubscribe", payload);
+            await this._postRequest.request("unsubscribe", payload);
           }
         }
       };
@@ -156,7 +148,7 @@ export class WebSocketSubscriptionManager {
       for (const [id, subscription] of this._subscriptions.entries()) {
         // reconnect only previously connected subscriptions to avoid double subscriptions due to message buffering
         if (subscription.promiseFinished) {
-          subscription.promise = this._wsRequester.request("subscribe", JSON.parse(id))
+          subscription.promise = this._postRequest.request("subscribe", JSON.parse(id))
             .catch((error) => subscription.failureController.abort(error))
             .finally(() => subscription.promiseFinished = true);
           subscription.promiseFinished = false;

package/src/src/transport/websocket/mod.ts

@@ -1,12 +1,33 @@
-import { TransportError } from "../../_errors.js";
+/**
+ * WebSocket transport for {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions | subscriptions} and {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests | POST requests}.
+ *
+ * Use {@link WebSocketTransport} for real-time subscriptions and for lower-latency API requests.
+ *
+ * @example Subscriptions
+ * ```ts
+ * import { SubscriptionClient, WebSocketTransport } from "@nktkas/hyperliquid";
+ *
+ * const transport = new WebSocketTransport();
+ * const client = new SubscriptionClient({ transport });
+ *
+ * const subscription = await client.allMids((data) => {
+ *   console.log(data.mids);
+ * });
+ *
+ * await subscription.unsubscribe();
+ * ```
+ *
+ * @module
+ */
+
+import type { IRequestTransport, ISubscription, ISubscriptionTransport } from "../_base.js";
 import { AbortSignal_ } from "../_polyfills.js";
 import { ReconnectingWebSocket, type ReconnectingWebSocketOptions } from "@nktkas/rews";
 import { HyperliquidEventTarget } from "./_hyperliquidEventTarget.js";
-import { WebSocketAsyncRequest, WebSocketRequestError } from "./_postRequest.js";
-import { type WebSocketSubscription, WebSocketSubscriptionManager } from "./_subscriptionManager.js";
+import { WebSocketPostRequest, WebSocketRequestError } from "./_postRequest.js";
+import { WebSocketSubscriptionManager } from "./_subscriptionManager.js";
 
 export { WebSocketRequestError };
-export type { WebSocketSubscription };
 
 /** Configuration options for the WebSocket transport layer. */
 export interface WebSocketTransportOptions {
@@ -15,7 +36,6 @@ export interface WebSocketTransportOptions {
    * @default false
    */
   isTestnet?: boolean;
-
   /**
    * Custom WebSocket endpoint for API and Subscription requests.
    * - Mainnet:
@@ -27,17 +47,13 @@ export interface WebSocketTransportOptions {
    * @default `wss://api.hyperliquid.xyz/ws` for mainnet, `wss://api.hyperliquid-testnet.xyz/ws` for testnet
    */
   url?: string | URL;
-
   /**
-   * Timeout for requests in ms.
-   * Set to `null` to disable.
+   * Timeout for requests in ms. Set to `null` to disable.
    * @default 10_000
    */
   timeout?: number | null;
-
   /** Reconnection policy configuration for closed connections. */
   reconnect?: ReconnectingWebSocketOptions;
-
   /**
    * Enable automatic re-subscription to Hyperliquid subscription after reconnection.
    * @default true
@@ -61,20 +77,27 @@ export const TESTNET_RPC_WS_URL = "wss://rpc.hyperliquid-testnet.xyz/ws";
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests
  */
-export class WebSocketTransport implements WebSocketTransportOptions {
+export class WebSocketTransport implements IRequestTransport, ISubscriptionTransport {
+  /** Indicates this transport uses testnet endpoint. */
   readonly isTestnet: boolean;
-  timeout: number | null;
   /** The WebSocket that is used for communication. */
   readonly socket: ReconnectingWebSocket;
-
+  /** Enable automatic re-subscription to Hyperliquid subscription after reconnection. */
   get resubscribe(): boolean {
     return this._subscriptionManager.resubscribe;
   }
   set resubscribe(value: boolean) {
     this._subscriptionManager.resubscribe = value;
   }
+  /** Timeout for requests in ms. Set to `null` to disable. */
+  get timeout(): number | null {
+    return this._postRequest.timeout;
+  }
+  set timeout(value: number | null) {
+    this._postRequest.timeout = value;
+  }
 
-  protected _wsRequester: WebSocketAsyncRequest;
+  protected _postRequest: WebSocketPostRequest;
   protected _hlEvents: HyperliquidEventTarget;
   protected _subscriptionManager: WebSocketSubscriptionManager;
   protected _keepAliveInterval: ReturnType<typeof setInterval> | undefined;
@@ -86,7 +109,6 @@ export class WebSocketTransport implements WebSocketTransportOptions {
    */
   constructor(options?: WebSocketTransportOptions) {
     this.isTestnet = options?.isTestnet ?? false;
-    this.timeout = options?.timeout === undefined ? 10_000 : options.timeout;
 
     this.socket = new ReconnectingWebSocket(
       options?.url ?? (this.isTestnet ? TESTNET_API_WS_URL : MAINNET_API_WS_URL),
@@ -94,10 +116,14 @@ export class WebSocketTransport implements WebSocketTransportOptions {
     );
 
     this._hlEvents = new HyperliquidEventTarget(this.socket);
-    this._wsRequester = new WebSocketAsyncRequest(this.socket, this._hlEvents);
+    this._postRequest = new WebSocketPostRequest(
+      this.socket,
+      this._hlEvents,
+      options?.timeout === undefined ? 10_000 : options.timeout,
+    );
     this._subscriptionManager = new WebSocketSubscriptionManager(
       this.socket,
-      this._wsRequester,
+      this._postRequest,
       this._hlEvents,
       options?.resubscribe ?? true,
     );
@@ -105,50 +131,24 @@ export class WebSocketTransport implements WebSocketTransportOptions {
     this._initKeepAlive();
   }
 
-  protected _initKeepAlive(): void {
-    const start = () => {
-      if (this._keepAliveInterval) return;
-      this._keepAliveInterval = setInterval(() => {
-        this.socket.send('{"method":"ping"}');
-      }, 30_000);
-    };
-    const stop = () => {
-      clearInterval(this._keepAliveInterval);
-      this._keepAliveInterval = undefined;
-    };
-
-    this.socket.addEventListener("open", start);
-    this.socket.addEventListener("close", stop);
-    this.socket.addEventListener("error", stop);
-  }
+  // ============================================================
+  // Public methods
+  // ============================================================
 
   /**
    * Sends a request to the Hyperliquid API via WebSocket.
    *
    * @param endpoint - The API endpoint to send the request to.
    * @param payload - The payload to send with the request.
-   * @param signal - [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to cancel the request.
+   * @param signal - {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
    *
    * @returns A promise that resolves with parsed JSON response body.
    *
    * @throws {WebSocketRequestError} - An error that occurs when a WebSocket request fails.
    */
   async request<T>(endpoint: "info" | "exchange", payload: unknown, signal?: AbortSignal): Promise<T> {
-    const timeoutSignal = this.timeout ? AbortSignal_.timeout(this.timeout) : undefined;
-    const combinedSignal = signal && timeoutSignal
-      ? AbortSignal_.any([signal, timeoutSignal])
-      : signal ?? timeoutSignal;
-
     const payload_ = { type: endpoint === "exchange" ? "action" : endpoint, payload };
-
-    return await this._wsRequester.request<T>("post", payload_, combinedSignal)
-      .catch((error) => {
-        if (error instanceof TransportError) throw error; // Re-throw known errors
-        throw new WebSocketRequestError(
-          `Unknown error while making a WebSocket request: ${error}`,
-          { cause: error },
-        );
-      });
+    return await this._postRequest.request<T>("post", payload_, signal);
   }
 
   /**
@@ -159,7 +159,7 @@ export class WebSocketTransport implements WebSocketTransportOptions {
    * @param payload - A payload to send with the subscription request.
    * @param listener - A function to call when the event is dispatched.
    *
-   * @returns A promise that resolves with a {@link WebSocketSubscription} object to manage the subscription lifecycle.
+   * @returns A promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
    *
    * @throws {WebSocketRequestError} - An error that occurs when a WebSocket request fails.
    */
@@ -167,14 +167,14 @@ export class WebSocketTransport implements WebSocketTransportOptions {
     channel: string,
     payload: unknown,
     listener: (data: CustomEvent<T>) => void,
-  ): Promise<WebSocketSubscription> {
+  ): Promise<ISubscription> {
     return this._subscriptionManager.subscribe(channel, payload, listener);
   }
 
   /**
    * Waits until the WebSocket connection is ready.
    *
-   * @param signal - [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to cancel the promise.
+   * @param signal - {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the promise.
    *
    * @returns A promise that resolves when the connection is ready.
    *
@@ -182,18 +182,22 @@ export class WebSocketTransport implements WebSocketTransportOptions {
    */
   ready(signal?: AbortSignal): Promise<void> {
     return new Promise((resolve, reject) => {
+      // Combine the provided signal with the socket's termination signal
       const combinedSignal = signal
         ? AbortSignal_.any([this.socket.terminationSignal, signal])
         : this.socket.terminationSignal;
 
+      // Check if already aborted
       if (combinedSignal.aborted) {
         return reject(
           new WebSocketRequestError("Failed to establish WebSocket connection", { cause: combinedSignal.reason }),
         );
       }
 
+      // Check if already open
       if (this.socket.readyState === ReconnectingWebSocket.OPEN) return resolve();
 
+      // Set up event listeners
       const handleOpen = () => {
         combinedSignal.removeEventListener("abort", handleAbort);
         resolve();
@@ -213,7 +217,7 @@ export class WebSocketTransport implements WebSocketTransportOptions {
   /**
    * Closes the WebSocket connection and waits until it is fully closed.
    *
-   * @param signal - [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to cancel the promise.
+   * @param signal - {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the promise.
    *
    * @returns A promise that resolves when the connection is fully closed.
    *
@@ -221,14 +225,17 @@ export class WebSocketTransport implements WebSocketTransportOptions {
    */
   close(signal?: AbortSignal): Promise<void> {
     return new Promise((resolve, reject) => {
+      // Check if already aborted
       if (signal?.aborted) {
         return reject(
           new WebSocketRequestError("Failed to close WebSocket connection", { cause: signal.reason }),
         );
       }
 
+      // Check if already closed
       if (this.socket.readyState === ReconnectingWebSocket.CLOSED) return resolve();
 
+      // Set up event listeners
       const handleClose = () => {
         signal?.removeEventListener("abort", handleAbort);
         resolve();
@@ -243,7 +250,29 @@ export class WebSocketTransport implements WebSocketTransportOptions {
       this.socket.addEventListener("error", handleClose, { once: true, signal });
       signal?.addEventListener("abort", handleAbort, { once: true });
 
+      // Initiate close
       this.socket.close();
     });
   }
+
+  // ============================================================
+  // Keep-Alive Logic
+  // ============================================================
+
+  protected _initKeepAlive(): void {
+    const start = () => {
+      if (this._keepAliveInterval) return;
+      this._keepAliveInterval = setInterval(() => {
+        this.socket.send('{"method":"ping"}');
+      }, 30_000);
+    };
+    const stop = () => {
+      clearInterval(this._keepAliveInterval);
+      this._keepAliveInterval = undefined;
+    };
+
+    this.socket.addEventListener("open", start);
+    this.socket.addEventListener("close", stop);
+    this.socket.addEventListener("error", stop);
+  }
 }

package/src/src/utils/{format.ts → _format.ts}

@@ -1,5 +1,5 @@
 /**
- * Format price according to Hyperliquid [rules](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size):
+ * Format price according to Hyperliquid {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size | rules}:
  * - Maximum 5 significant figures
  * - Maximum 6 (for perp) or 8 (for spot) - `szDecimals` decimal places
  * - Integer prices are always allowed regardless of significant figures
@@ -38,7 +38,7 @@ export function formatPrice(price: string | number, szDecimals: number, type: "p
 }
 
 /**
- * Format size according to Hyperliquid [rules](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size):
+ * Format size according to Hyperliquid {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size | rules}:
  * - Truncate decimal places to `szDecimals`
  *
  * @param size - The size to format (as string or number).