@nktkas/hyperliquid/esm/transport/websocket/mod.d.ts

Hyperliquid API SDK for all major JS runtimes, written in TypeScript.

/**
 * 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
 * ```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
 */
/// <amd-module name="file:///home/runner/work/hyperliquid/hyperliquid/src/transport/websocket/mod.ts" />
import { ReconnectingWebSocket, type ReconnectingWebSocketOptions } from "@nktkas/rews";
import type { IRequestTransport, ISubscription, ISubscriptionTransport } from "../_base.js";
import { WebSocketRequestError } from "./_dispatcher.js";
import { type WebSocketKeepAliveOptions } from "./_keepAlive.js";
export { WebSocketRequestError };
/** Configuration options for the WebSocket transport layer. */
export interface WebSocketTransportOptions {
    /**
     * Indicates this transport uses testnet endpoint.
     *
     * Default: `false`
     */
    isTestnet?: boolean;
    /**
     * Custom WebSocket endpoint for API and Subscription requests.
     * - Mainnet:
     *   - API: `wss://api.hyperliquid.xyz/ws`
     *   - Explorer: `wss://rpc.hyperliquid.xyz/ws`
     * - Testnet:
     *   - API: `wss://api.hyperliquid-testnet.xyz/ws`
     *   - Explorer: `wss://rpc.hyperliquid-testnet.xyz/ws`
     *
     * 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.
     *
     * Default: `10_000`
     */
    timeout?: number | null;
    /** Reconnection policy configuration for closed connections. */
    reconnect?: ReconnectingWebSocketOptions;
    /** Keep-alive ping/pong watchdog configuration. */
    keepAlive?: WebSocketKeepAliveOptions;
    /**
     * Enable automatic re-subscription to Hyperliquid subscription after reconnection.
     *
     * Default: `true`
     */
    resubscribe?: boolean;
}
/** Mainnet API WebSocket URL. */
export declare const MAINNET_API_WS_URL = "wss://api.hyperliquid.xyz/ws";
/** Testnet API WebSocket URL. */
export declare const TESTNET_API_WS_URL = "wss://api.hyperliquid-testnet.xyz/ws";
/** Mainnet RPC WebSocket URL. */
export declare const MAINNET_RPC_WS_URL = "wss://rpc.hyperliquid.xyz/ws";
/** Testnet RPC WebSocket URL. */
export declare const TESTNET_RPC_WS_URL = "wss://rpc.hyperliquid-testnet.xyz/ws";
/**
 * WebSocket transport for the Hyperliquid API.
 *
 * @example
 * ```ts
 * import { WebSocketTransport } from "@nktkas/hyperliquid";
 *
 * const transport = new WebSocketTransport();
 * const mids = await transport.request("info", { type: "allMids" });
 * transport.close();
 * ```
 *
 * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint
 * @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 declare class WebSocketTransport implements IRequestTransport<"info" | "exchange">, ISubscriptionTransport {
    /** Indicates this transport uses testnet endpoint. */
    readonly isTestnet: boolean;
    /** The WebSocket that is used for communication. */
    readonly socket: ReconnectingWebSocket;
    /** Enable automatic re-subscription to Hyperliquid subscription after reconnection. */
    get resubscribe(): boolean;
    set resubscribe(value: boolean);
    /** Timeout for requests in ms. Set to `null` to disable. */
    get timeout(): number | null;
    set timeout(value: number | null);
    private readonly _hlEvents;
    private readonly _dispatcher;
    private readonly _keepAlive;
    private readonly _subscriptionManager;
    /** Creates the transport and immediately starts connecting. */
    constructor(options?: WebSocketTransportOptions);
    /**
     * Sends a request to the Hyperliquid API via WebSocket.
     *
     * The `explorer` endpoint is HTTP-only and not supported by this transport.
     *
     * @param endpoint The API endpoint to send the request to.
     * @param payload The payload to send with the request.
     * @param signal {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
     * @return A promise that resolves with the parsed response payload.
     *
     * @throws {WebSocketRequestError} An error that occurs when a WebSocket request fails.
     *
     * @example
     * ```ts
     * import { WebSocketTransport } from "@nktkas/hyperliquid";
     *
     * const transport = new WebSocketTransport();
     * const mids = await transport.request("info", { type: "allMids" });
     * ```
     */
    request<T>(endpoint: "info" | "exchange", payload: unknown, signal?: AbortSignal): Promise<T>;
    /**
     * Subscribes to a Hyperliquid event channel.
     *
     * @param channel The event channel to listen to.
     * @param payload The payload to send with the subscription request.
     * @param listener The function to call when the event is dispatched.
     * @param options Subscription options; see {@linkcode WebSocketSubscriptionManager.subscribe}.
     * @return A promise that resolves with a subscription handle once the server confirms the subscription.
     *
     * @throws {WebSocketRequestError} An error that occurs when the subscription request fails.
     *
     * @example
     * ```ts
     * import { WebSocketTransport } from "@nktkas/hyperliquid";
     *
     * const transport = new WebSocketTransport();
     * const subscription = await transport.subscribe("allMids", { type: "allMids" }, (event) => {
     *   console.log(event.detail);
     * });
     *
     * await subscription.unsubscribe();
     * ```
     */
    subscribe<T>(channel: string, payload: unknown, listener: (data: CustomEvent<T>) => void, options?: {
        /** Stops waiting for the confirmation and detaches the listener. */
        signal?: AbortSignal;
        /**
         * Callback invoked at most once, when an already confirmed subscription fails:
         * - the server rejects a re-subscription after a reconnect;
         * - the connection is permanently terminated;
         * - the connection goes down while re-subscription is disabled.
         *
         * Failures before the confirmation reject the `subscribe()` promise instead.
         * After the callback fires, the subscription is removed and no further events or errors follow.
         */
        onError?: (error: WebSocketRequestError) => void;
    }): Promise<ISubscription>;
    /**
     * Waits until the WebSocket connection is ready.
     *
     * @param signal Stops waiting for the connection; the connection itself keeps establishing.
     * @return A promise that resolves once the connection is open.
     *
     * @throws {WebSocketRequestError} When the connection is permanently terminated, or when `signal` aborts the waiting.
     *
     * @example
     * ```ts
     * import { WebSocketTransport } from "@nktkas/hyperliquid";
     *
     * const transport = new WebSocketTransport();
     * await transport.ready(AbortSignal.timeout(5_000));
     * ```
     */
    ready(signal?: AbortSignal): Promise<void>;
    /**
     * Permanently closes the WebSocket connection.
     *
     * @example
     * ```ts
     * import { WebSocketTransport } from "@nktkas/hyperliquid";
     *
     * const transport = new WebSocketTransport();
     * transport.close();
     * ```
     */
    close(): void;
}