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

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

/**
 * HTTP transport for executing requests to the Hyperliquid API.
 *
 * Use {@link HttpTransport} for simple requests via HTTP POST.
 *
 * ---
 *
 * ```text
 * HttpTransport.request():
 *   controller ◄─ timeout / user signal / fetchOptions.signal
 *    └─► fetch ┬─► non-OK or non-JSON body ─► HttpRequestError(response, detail)
 *              └─► parse JSON ─► T
 *     catch: classify by reference ─► finally: cancel timer, detach
 * ```
 *
 * @example
 * ```ts
 * import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";
 *
 * const transport = new HttpTransport();
 * const client = new InfoClient({ transport });
 *
 * const mids = await client.allMids();
 * ```
 *
 * @module
 */
/// <amd-module name="file:///home/runner/work/hyperliquid/hyperliquid/src/transport/http/mod.ts" />
import { type IRequestTransport, TransportError } from "../_base.js";
/** Configuration options for the HTTP transport layer. */
export interface HttpTransportOptions {
    /**
     * Indicates this transport uses testnet endpoint.
     *
     * Default: `false`
     */
    isTestnet?: boolean;
    /**
     * Request timeout in ms. Set to `null` to disable.
     *
     * Default: `10_000`
     */
    timeout?: number | null;
    /**
     * Custom API URL for `info` and `exchange` requests.
     *
     * Default: `https://api.hyperliquid.xyz` for mainnet, `https://api.hyperliquid-testnet.xyz` for testnet.
     */
    apiUrl?: string | URL;
    /**
     * Custom RPC URL for `explorer` requests.
     *
     * Default: `https://rpc.hyperliquid.xyz` for mainnet, `https://rpc.hyperliquid-testnet.xyz` for testnet.
     */
    rpcUrl?: string | URL;
    /** A custom {@link https://developer.mozilla.org/en-US/docs/Web/API/RequestInit | RequestInit} that is merged with a fetch request. */
    fetchOptions?: Omit<RequestInit, "body" | "method">;
}
/** Mainnet API URL. */
export declare const MAINNET_API_URL = "https://api.hyperliquid.xyz";
/** Testnet API URL. */
export declare const TESTNET_API_URL = "https://api.hyperliquid-testnet.xyz";
/** Mainnet RPC URL. */
export declare const MAINNET_RPC_URL = "https://rpc.hyperliquid.xyz";
/** Testnet RPC URL. */
export declare const TESTNET_RPC_URL = "https://rpc.hyperliquid-testnet.xyz";
/**
 * Error thrown when an HTTP request fails.
 *
 * @example
 * ```ts
 * import { HttpRequestError, HttpTransport } from "@nktkas/hyperliquid";
 *
 * const transport = new HttpTransport();
 * try {
 *   // Throws on a non-OK response, a timeout, an abort, or a network failure.
 *   await transport.request("info", { type: "allMids" });
 * } catch (error) {
 *   if (error instanceof HttpRequestError) {
 *     console.error(error.message, error.response?.status);
 *   }
 * }
 * ```
 */
export declare class HttpRequestError extends TransportError {
    /** The HTTP response that caused the error. */
    response?: Response;
    /** The original request payload that triggered the error, if available. */
    request?: unknown;
    /**
     * Creates an HTTP request error.
     *
     * The message is the response status line, extended with `detail` when given;
     * without a response, `detail` alone or a description of `cause` is used.
     */
    constructor(options?: ErrorOptions & {
        detail?: string;
        response?: Response;
        request?: unknown;
    });
}
/**
 * HTTP transport for the Hyperliquid API.
 *
 * @example
 * ```ts
 * import { HttpTransport } from "@nktkas/hyperliquid";
 *
 * const transport = new HttpTransport();
 * const mids = await transport.request("info", { type: "allMids" });
 * ```
 *
 * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint
 * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint
 */
export declare class HttpTransport implements IRequestTransport<"info" | "exchange" | "explorer"> {
    /** Indicates this transport uses testnet endpoint. */
    readonly isTestnet: boolean;
    /** Request timeout in ms. Set to `null` to disable. */
    timeout: number | null;
    /** Custom API URL for requests. */
    apiUrl: string | URL;
    /** Custom RPC URL for explorer requests. */
    rpcUrl: string | URL;
    /** A custom {@link https://developer.mozilla.org/en-US/docs/Web/API/RequestInit | RequestInit} that is merged with a fetch request. */
    fetchOptions: Omit<RequestInit, "body" | "method">;
    constructor(options?: HttpTransportOptions);
    /**
     * Sends a request to the Hyperliquid API.
     *
     * Routes to {@linkcode apiUrl} for `info`/`exchange` and {@linkcode rpcUrl} for `explorer`.
     *
     * @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 JSON response body.
     *
     * @throws {HttpRequestError} When the HTTP request fails.
     *
     * @example
     * ```ts
     * import { HttpTransport } from "@nktkas/hyperliquid";
     *
     * const transport = new HttpTransport();
     * const mids = await transport.request("info", { type: "allMids" });
     * ```
     */
    request<T>(endpoint: "info" | "exchange" | "explorer", payload: unknown, signal?: AbortSignal): Promise<T>;
}