@nktkas/hyperliquid/esm/utils/_symbolConverter.d.ts

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

/// <amd-module name="file:///home/runner/work/hyperliquid/hyperliquid/src/utils/_symbolConverter.ts" />
import type { IRequestTransport } from "../transport/mod.js";
/** Options for creating a {@link SymbolConverter} instance. */
export interface SymbolConverterOptions {
    /** Transport instance to use for API requests. */
    transport: IRequestTransport;
    /** Optional dex support: array of dex names, true for all dexs, or false/undefined to skip. */
    dexs?: string[] | boolean;
}
/**
 * Utility class for converting asset symbols to their corresponding IDs and size decimals.
 * Supports perpetuals, spots, optional builder dexs and outcome markets.
 *
 * @example
 * ```ts
 * import { HttpTransport } from "@nktkas/hyperliquid";
 * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
 *
 * const transport = new HttpTransport(); // or `WebSocketTransport`
 * const converter = await SymbolConverter.create({ transport });
 *
 * // By default, dexs are not loaded; specify them when creating an instance
 * // const converter = await SymbolConverter.create({ transport, dexs: ["test"] });
 *
 * const btcId = converter.getAssetId("BTC"); // perpetual → 0
 * const hypeUsdcId = converter.getAssetId("HYPE/USDC"); // spot → 10107
 * const dexAbcId = converter.getAssetId("test:ABC"); // builder dex (if enabled) → 110000
 * const outcomeId = converter.getAssetId("btc-above-61720-yes-jun-08-0600"); // outcome market → 100002200
 *
 * const btcSzDecimals = converter.getSzDecimals("BTC"); // perpetual → 5
 * const hypeUsdcSzDecimals = converter.getSzDecimals("HYPE/USDC"); // spot → 2
 * const dexAbcSzDecimals = converter.getSzDecimals("test:ABC"); // builder dex (if enabled) → 0
 *
 * const spotPairId = converter.getSpotPairId("HFUN/USDC"); // → "@2"
 *
 * const symbol = converter.getSymbolBySpotPairId("@107"); // → "HYPE/USDC"
 * ```
 *
 * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids
 */
export declare class SymbolConverter {
    private _transport;
    private _dexOption;
    private _nameToAssetId;
    private _nameToSzDecimals;
    private _nameToSpotPairId;
    private _spotPairIdToName;
    private _reloadPromise;
    /**
     * Creates a new SymbolConverter instance, but does not initialize it.
     * Run {@link reload} to load asset data or use {@link create} to create and initialize in one step.
     *
     * @param options Configuration options including transport and optional dex support.
     */
    constructor(options: SymbolConverterOptions);
    /**
     * Create and initialize a SymbolConverter instance.
     *
     * @param options Configuration options including transport and optional dex support.
     * @return Initialized SymbolConverter instance.
     *
     * @example
     * ```ts
     * import { HttpTransport } from "@nktkas/hyperliquid";
     * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
     *
     * const transport = new HttpTransport(); // or `WebSocketTransport`
     * const converter = await SymbolConverter.create({ transport });
     * ```
     */
    static create(options: SymbolConverterOptions): Promise<SymbolConverter>;
    /**
     * Reload asset mappings from the API.
     *
     * Useful for refreshing data when new assets are added.
     */
    reload(): Promise<void>;
    private _reload;
    private _processPerps;
    private _processSpot;
    private _processBuilderDexs;
    private _processOutcomeMarkets;
    /**
     * Builds the URL slug for an outcome side.
     *
     * Recurring price markets encode their slug in a `class:price*` description; every other market
     * derives it from the question, outcome, and side names (e.g. "nba-finals-game-3-san-antonio").
     */
    private _outcomeSlug;
    /**
     * Builds the slug for a recurring price market from its `class:price*` description.
     *
     * @param spec Pipe-delimited recurring market spec (e.g. "class:priceBinary|underlying:BTC|expiry:...").
     * @param side Side name (e.g. "Yes").
     * @param bucketIndex Price range position for `priceBucket` markets (0 = below, 1 = between, 2 = above).
     * @return The generated slug, or `null` if the spec is incomplete or of an unknown class.
     *
     * @see https://hyperliquid.gitbook.io/hyperliquid-docs/trading/contract-specifications
     */
    private _recurringPriceSlug;
    /** Converts a market or side name to a URL slug. */
    private _slugify;
    /**
     * Get asset ID for a coin.
     * - For Perpetuals, use the coin name (e.g., "BTC").
     * - For Spots, use the "BASE/QUOTE" format (e.g., "HYPE/USDC").
     * - For Builder Dexs, use the "DEX_NAME:ASSET_NAME" format (e.g., "test:ABC").
     * - For Outcome Markets, use the slug as in the URL (e.g., "btc-above-61720-yes-jun-08-0600").
     *
     * @example
     * ```ts
     * import { HttpTransport } from "@nktkas/hyperliquid";
     * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
     *
     * const transport = new HttpTransport(); // or `WebSocketTransport`
     * const converter = await SymbolConverter.create({ transport });
     *
     * converter.getAssetId("BTC"); // → 0
     * converter.getAssetId("HYPE/USDC"); // → 10107
     * converter.getAssetId("test:ABC"); // → 110000
     * converter.getAssetId("btc-above-61720-yes-jun-08-0600"); // → 100002200
     * ```
     */
    getAssetId(name: string): number | undefined;
    /**
     * Get size decimals for a coin.
     * - For Perpetuals, use the coin name (e.g., "BTC").
     * - For Spots, use the "BASE/QUOTE" format (e.g., "HYPE/USDC").
     * - For Builder Dexs, use the "DEX_NAME:ASSET_NAME" format (e.g., "test:ABC").
     * - For Outcome Markets, use the slug as in the URL (e.g., "btc-above-61720-yes-jun-08-0600").
     *
     * @example
     * ```ts
     * import { HttpTransport } from "@nktkas/hyperliquid";
     * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
     *
     * const transport = new HttpTransport(); // or `WebSocketTransport`
     * const converter = await SymbolConverter.create({ transport });
     *
     * converter.getSzDecimals("BTC"); // → 5
     * converter.getSzDecimals("HYPE/USDC"); // → 2
     * converter.getSzDecimals("test:ABC"); // → 0
     * converter.getSzDecimals("btc-above-61720-yes-jun-08-0600"); // → 5
     * ```
     */
    getSzDecimals(name: string): number | undefined;
    /**
     * Get spot pair ID (e.g., @2) for info endpoints and subscriptions (e.g., l2book, trades).
     *
     * @example
     * ```ts
     * import { HttpTransport } from "@nktkas/hyperliquid";
     * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
     *
     * const transport = new HttpTransport(); // or `WebSocketTransport`
     * const converter = await SymbolConverter.create({ transport });
     *
     * converter.getSpotPairId("HFUN/USDC"); // → "@2"
     * converter.getSpotPairId("PURR/USDC"); // → "PURR/USDC" (exceptions exist for some pairs)
     * ```
     */
    getSpotPairId(name: string): string | undefined;
    /**
     * Get the symbol ("BASE/QUOTE") from a spot pair ID (e.g., @107).
     *
     * @example
     * ```ts
     * import { HttpTransport } from "@nktkas/hyperliquid";
     * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
     *
     * const transport = new HttpTransport(); // or `WebSocketTransport`
     * const converter = await SymbolConverter.create({ transport });
     *
     * converter.getSymbolBySpotPairId("@107"); // → "HYPE/USDC"
     * converter.getSymbolBySpotPairId("PURR/USDC"); // → "PURR/USDC" (exceptions exist for some pairs)
     * ```
     */
    getSymbolBySpotPairId(pairId: string): string | undefined;
}