@nktkas/hyperliquid 0.27.0 → 0.28.0

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

@@ -0,0 +1,249 @@
+import { TransportError } from "../../_errors.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";
+
+export { WebSocketRequestError };
+export type { WebSocketSubscription };
+
+/** 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;
+
+  /**
+   * Enable automatic re-subscription to Hyperliquid subscription after reconnection.
+   * @default true
+   */
+  resubscribe?: boolean;
+}
+
+/** Mainnet API WebSocket URL. */
+export const MAINNET_API_WS_URL = "wss://api.hyperliquid.xyz/ws";
+/** Testnet API WebSocket URL. */
+export const TESTNET_API_WS_URL = "wss://api.hyperliquid-testnet.xyz/ws";
+/** Mainnet RPC WebSocket URL. */
+export const MAINNET_RPC_WS_URL = "wss://rpc.hyperliquid.xyz/ws";
+/** Testnet RPC WebSocket URL. */
+export const TESTNET_RPC_WS_URL = "wss://rpc.hyperliquid-testnet.xyz/ws";
+
+/**
+ * WebSocket transport for Hyperliquid API.
+ *
+ * @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 class WebSocketTransport implements WebSocketTransportOptions {
+  readonly isTestnet: boolean;
+  timeout: number | null;
+  /** The WebSocket that is used for communication. */
+  readonly socket: ReconnectingWebSocket;
+
+  get resubscribe(): boolean {
+    return this._subscriptionManager.resubscribe;
+  }
+  set resubscribe(value: boolean) {
+    this._subscriptionManager.resubscribe = value;
+  }
+
+  protected _wsRequester: WebSocketAsyncRequest;
+  protected _hlEvents: HyperliquidEventTarget;
+  protected _subscriptionManager: WebSocketSubscriptionManager;
+  protected _keepAliveInterval: ReturnType<typeof setInterval> | undefined;
+
+  /**
+   * Creates a new WebSocket transport instance.
+   *
+   * @param options - Configuration options for the WebSocket transport layer.
+   */
+  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),
+      options?.reconnect,
+    );
+
+    this._hlEvents = new HyperliquidEventTarget(this.socket);
+    this._wsRequester = new WebSocketAsyncRequest(this.socket, this._hlEvents);
+    this._subscriptionManager = new WebSocketSubscriptionManager(
+      this.socket,
+      this._wsRequester,
+      this._hlEvents,
+      options?.resubscribe ?? true,
+    );
+
+    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);
+  }
+
+  /**
+   * 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.
+   *
+   * @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 },
+        );
+      });
+  }
+
+  /**
+   * Subscribes to a Hyperliquid event channel.
+   * Sends a subscription request to the server and listens for events.
+   *
+   * @param channel - The event channel to listen to.
+   * @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.
+   *
+   * @throws {WebSocketRequestError} - An error that occurs when a WebSocket request fails.
+   */
+  subscribe<T>(
+    channel: string,
+    payload: unknown,
+    listener: (data: CustomEvent<T>) => void,
+  ): Promise<WebSocketSubscription> {
+    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.
+   *
+   * @returns A promise that resolves when the connection is ready.
+   *
+   * @throws {WebSocketRequestError} When the connection cannot be established.
+   */
+  ready(signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const combinedSignal = signal
+        ? AbortSignal_.any([this.socket.terminationSignal, signal])
+        : this.socket.terminationSignal;
+
+      if (combinedSignal.aborted) {
+        return reject(
+          new WebSocketRequestError("Failed to establish WebSocket connection", { cause: combinedSignal.reason }),
+        );
+      }
+
+      if (this.socket.readyState === ReconnectingWebSocket.OPEN) return resolve();
+
+      const handleOpen = () => {
+        combinedSignal.removeEventListener("abort", handleAbort);
+        resolve();
+      };
+      const handleAbort = () => {
+        this.socket.removeEventListener("open", handleOpen);
+        return reject(
+          new WebSocketRequestError("Failed to establish WebSocket connection", { cause: combinedSignal.reason }),
+        );
+      };
+
+      this.socket.addEventListener("open", handleOpen, { once: true });
+      combinedSignal.addEventListener("abort", handleAbort, { once: true });
+    });
+  }
+
+  /**
+   * 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.
+   *
+   * @returns A promise that resolves when the connection is fully closed.
+   *
+   * @throws {WebSocketRequestError} When the connection cannot be closed.
+   */
+  close(signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        return reject(
+          new WebSocketRequestError("Failed to close WebSocket connection", { cause: signal.reason }),
+        );
+      }
+
+      if (this.socket.readyState === ReconnectingWebSocket.CLOSED) return resolve();
+
+      const handleClose = () => {
+        signal?.removeEventListener("abort", handleAbort);
+        resolve();
+      };
+      const handleAbort = () => {
+        return reject(
+          new WebSocketRequestError("Failed to close WebSocket connection", { cause: signal?.reason }),
+        );
+      };
+
+      this.socket.addEventListener("close", handleClose, { once: true, signal });
+      this.socket.addEventListener("error", handleClose, { once: true, signal });
+      signal?.addEventListener("abort", handleAbort, { once: true });
+
+      this.socket.close();
+    });
+  }
+}

package/src/src/utils/format.ts

@@ -0,0 +1,192 @@
+/**
+ * Format price according to Hyperliquid [rules](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size):
+ * - Maximum 5 significant figures
+ * - Maximum 6 (for perp) or 8 (for spot) - `szDecimals` decimal places
+ * - Integer prices are always allowed regardless of significant figures
+ *
+ * @param price - The price to format (as string or number).
+ * @param szDecimals - The size decimals of the asset.
+ * @param type - The market type: "perp" for perpetuals or "spot" for spot markets. Default is "perp".
+ *
+ * @throws {RangeError} If the formatted price is 0
+ *
+ * @example
+ * ```ts
+ * import { formatPrice } from "@nktkas/hyperliquid/utils";
+ * const price = formatPrice("0.0000123456789", 0, "spot"); // → "0.00001234"
+ * ```
+ */
+export function formatPrice(price: string | number, szDecimals: number, type: "perp" | "spot" = "perp"): string {
+  price = price.toString().trim();
+  assertNumberString(price);
+
+  // Integer prices are always allowed
+  if (/^-?\d+$/.test(price)) return formatDecimalString(price);
+
+  // Apply decimal limit: max 6 (perp) or 8 (spot) - szDecimals
+  const maxDecimals = Math.max((type === "perp" ? 6 : 8) - szDecimals, 0);
+  price = StringMath.toFixedTruncate(price, maxDecimals);
+
+  // Apply sig figs limit: max 5 significant figures
+  price = StringMath.toPrecisionTruncate(price, 5);
+
+  if (price === "0") {
+    throw new RangeError("Price is too small and was truncated to 0");
+  }
+
+  return price;
+}
+
+/**
+ * Format size according to Hyperliquid [rules](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size):
+ * - Truncate decimal places to `szDecimals`
+ *
+ * @param size - The size to format (as string or number).
+ * @param szDecimals - The size decimals of the asset.
+ *
+ * @throws {RangeError} If the formatted size is 0
+ *
+ * @example
+ * ```ts
+ * import { formatSize } from "@nktkas/hyperliquid/utils";
+ *
+ * const size = formatSize("1.23456789", 5); // → "1.23456"
+ * ```
+ */
+export function formatSize(size: string | number, szDecimals: number): string {
+  size = size.toString().trim();
+  assertNumberString(size);
+
+  // Apply decimal limit: szDecimals
+  size = StringMath.toFixedTruncate(size, szDecimals);
+
+  if (size === "0") {
+    throw new RangeError("Size is too small and was truncated to 0");
+  }
+
+  return size;
+}
+
+/** String-based Math operations for arbitrary precision */
+const StringMath = {
+  /** Floor log10 (magnitude): position of most significant digit */
+  log10Floor(value: string): number {
+    const abs = value[0] === "-" ? value.slice(1) : value;
+
+    // Check if zero or invalid
+    const num = Number(abs);
+    if (num === 0 || isNaN(num)) return -Infinity;
+
+    const [int, dec] = abs.split(".");
+
+    // Number >= 1: magnitude = length of integer part - 1
+    if (Number(int) !== 0) {
+      const trimmed = int.replace(/^0+/, "");
+      return trimmed.length - 1;
+    }
+
+    // Number < 1: count leading zeros in decimal part
+    const leadingZeros = dec.match(/^0*/)?.[0].length ?? 0;
+    return -(leadingZeros + 1);
+  },
+
+  /** Multiply by 10^exp: shift decimal point left (negative) or right (positive) */
+  multiplyByPow10(value: string, exp: number): string {
+    if (!Number.isInteger(exp)) throw new RangeError("Exponent must be an integer");
+    if (exp === 0) return formatDecimalString(value);
+
+    const neg = value[0] === "-";
+    const abs = neg ? value.slice(1) : value;
+    const [intRaw, dec = ""] = abs.split(".");
+    // Normalize empty integer part to "0" (handles ".5" → "0.5")
+    const int = intRaw || "0";
+
+    let result: string;
+
+    if (exp > 0) {
+      // Shift right: move digits from decimal to integer
+      if (exp >= dec.length) {
+        result = int + dec + "0".repeat(exp - dec.length);
+      } else {
+        result = int + dec.slice(0, exp) + "." + dec.slice(exp);
+      }
+    } else {
+      // Shift left: move digits from integer to decimal
+      const absExp = -exp;
+      if (absExp >= int.length) {
+        result = "0." + "0".repeat(absExp - int.length) + int + dec;
+      } else {
+        result = int.slice(0, -absExp) + "." + int.slice(-absExp) + dec;
+      }
+    }
+
+    return formatDecimalString((neg ? "-" : "") + result);
+  },
+
+  /** Returns the integer part of a number by removing any fractional digits */
+  trunc(value: string): string {
+    const dotIndex = value.indexOf(".");
+    return dotIndex === -1 ? value : value.slice(0, dotIndex) || "0";
+  },
+
+  /** Truncate to a certain number of significant figures */
+  toPrecisionTruncate(value: string, precision: number): string {
+    if (!Number.isInteger(precision)) throw new RangeError("Precision must be an integer");
+    if (precision < 1) throw new RangeError("Precision must be positive");
+    if (/^-?0+(\.0*)?$/.test(value)) return "0"; // zero is special case (don't work with log10)
+
+    const neg = value[0] === "-";
+    const abs = neg ? value.slice(1) : value;
+
+    // Calculate how much to shift: align most significant digit to ones place + (maxSigFigs-1)
+    const magnitude = StringMath.log10Floor(abs);
+    const shiftAmount = precision - magnitude - 1;
+
+    // Shift right, truncate integer part, shift back
+    const shifted = StringMath.multiplyByPow10(abs, shiftAmount);
+    const truncated = StringMath.trunc(shifted);
+    const result = StringMath.multiplyByPow10(truncated, -shiftAmount);
+
+    // build final result and trim zeros
+    return formatDecimalString(neg ? "-" + result : result);
+  },
+
+  /** Truncate to a certain number of decimal places */
+  toFixedTruncate(value: string, decimals: number): string {
+    if (!Number.isInteger(decimals)) throw new RangeError("Decimals must be an integer");
+    if (decimals < 0) throw new RangeError("Decimals must be non-negative");
+
+    // Match number with up to `decimals` decimal places
+    const regex = new RegExp(`^-?(?:\\d+)?(?:\\.\\d{0,${decimals}})?`);
+    const result = value.match(regex)?.[0];
+
+    if (!result) {
+      throw new TypeError("Invalid number format");
+    }
+
+    // Trim zeros after truncation
+    return formatDecimalString(result);
+  },
+};
+
+function formatDecimalString(value: string): string {
+  return value
+    // remove leading/trailing whitespace
+    .trim() // "  123.45  " → "123.45"
+    // remove leading zeros
+    .replace(/^(-?)0+(?=\d)/, "$1") // "00123" → "123", "-00.5" → "-0.5"
+    // remove trailing zeros
+    .replace(/\.0*$|(\.\d+?)0+$/, "$1") // "1.2000" → "1.2", "5.0" → "5"
+    // add leading zero if starts with decimal point
+    .replace(/^(-?)\./, "$10.") // ".5" → "0.5", "-.5" → "-0.5"
+    // add "0" if string is empty after trimming
+    .replace(/^-?$/, "0") // "" → "0", "-" → "0"
+    // normalize negative zero
+    .replace(/^-0$/, "0"); // "-0" → "0"
+}
+
+function assertNumberString(value: string): void {
+  if (!/^-?(\d+\.?\d*|\.\d*)$/.test(value)) {
+    throw new TypeError("Invalid number format");
+  }
+}

package/src/src/utils/mod.ts

@@ -0,0 +1,2 @@
+export * from "./symbolConverter.js";
+export * from "./format.js";

package/src/src/utils/symbolConverter.ts

@@ -0,0 +1,218 @@
+import type { HttpTransport } from "../transport/http/mod.js";
+import type { WebSocketTransport } from "../transport/websocket/mod.js";
+import {
+  meta,
+  type MetaResponse,
+  perpDexs,
+  type PerpDexsResponse,
+  spotMeta,
+  type SpotMetaResponse,
+} from "../api/info/mod.js";
+
+/** Options for creating a {@link SymbolConverter} instance. */
+export interface SymbolConverterOptions {
+  /** Transport instance to use for API requests. */
+  transport: HttpTransport | WebSocketTransport;
+
+  /** 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, spot markets, and optional builder dexs.
+ *
+ * @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 market → 10107
+ * const dexAbcId = converter.getAssetId("test:ABC"); // builder dex (if enabled) → 110000
+ *
+ * const btcSzDecimals = converter.getSzDecimals("BTC"); // perpetual → 5
+ * const hypeUsdcSzDecimals = converter.getSzDecimals("HYPE/USDC"); // spot market → 2
+ * const dexAbcSzDecimals = converter.getSzDecimals("test:ABC"); // builder dex (if enabled) → 0
+ *
+ * const spotPairId = converter.getSpotPairId("HFUN/USDC"); // → "@2"
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids
+ */
+export class SymbolConverter {
+  private readonly transport: HttpTransport | WebSocketTransport;
+  private readonly dexOption: string[] | boolean;
+  private readonly nameToAssetId = new Map<string, number>();
+  private readonly nameToSzDecimals = new Map<string, number>();
+  private readonly nameToSpotPairId = new Map<string, string>();
+
+  private constructor(options: SymbolConverterOptions) {
+    this.transport = options.transport;
+    this.dexOption = options.dexs ?? false;
+  }
+
+  /**
+   * Create and initialize a SymbolConverter instance.
+   *
+   * @param options - Configuration options including transport and optional dex support.
+   *
+   * @returns 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 async create(options: SymbolConverterOptions): Promise<SymbolConverter> {
+    const instance = new SymbolConverter(options);
+    await instance.reload();
+    return instance;
+  }
+
+  /**
+   * Reload asset mappings from the API.
+   * Useful for refreshing data when new assets are added.
+   */
+  async reload(): Promise<void> {
+    const config = { transport: this.transport };
+    const needDexs = this.dexOption === true || (Array.isArray(this.dexOption) && this.dexOption.length > 0);
+
+    const [perpMetaData, spotMetaData, perpDexsData] = await Promise.all([
+      meta(config),
+      spotMeta(config),
+      needDexs ? perpDexs(config) : undefined,
+    ]);
+
+    if (!perpMetaData?.universe?.length) {
+      throw new Error("Invalid perpetual metadata response");
+    }
+
+    if (!spotMetaData?.universe?.length || !spotMetaData?.tokens?.length) {
+      throw new Error("Invalid spot metadata response");
+    }
+
+    this.nameToAssetId.clear();
+    this.nameToSzDecimals.clear();
+    this.nameToSpotPairId.clear();
+
+    this.processDefaultPerps(perpMetaData);
+    this.processSpotAssets(spotMetaData);
+
+    // Only process builder dexs if dex support is enabled
+    if (perpDexsData) {
+      await this.processBuilderDexs(perpDexsData);
+    }
+  }
+
+  private processDefaultPerps(perpMetaData: MetaResponse): void {
+    perpMetaData.universe.forEach((asset, index) => {
+      this.nameToAssetId.set(asset.name, index);
+      this.nameToSzDecimals.set(asset.name, asset.szDecimals);
+    });
+  }
+
+  private async processBuilderDexs(perpDexsData: PerpDexsResponse): Promise<void> {
+    if (!perpDexsData || perpDexsData.length <= 1) return;
+
+    const builderDexs = perpDexsData
+      .map((dex, index) => ({ dex, index }))
+      .filter((item): item is { dex: NonNullable<PerpDexsResponse[number]>; index: number } => {
+        return item.index > 0 && item.dex !== null && item.dex.name.length > 0;
+      });
+
+    if (builderDexs.length === 0) return;
+
+    // Filter dexs based on the dexOption
+    const dexsToProcess = Array.isArray(this.dexOption)
+      ? builderDexs.filter((item) => (this.dexOption as string[]).includes(item.dex.name))
+      : builderDexs; // true means process all
+
+    if (dexsToProcess.length === 0) return;
+
+    const config = { transport: this.transport };
+    const results = await Promise.allSettled(
+      dexsToProcess.map((item) => meta(config, { dex: item.dex.name })),
+    );
+
+    results.forEach((result, idx) => {
+      if (result.status !== "fulfilled") return;
+      this.processBuilderDexResult(result.value, dexsToProcess[idx].index);
+    });
+  }
+
+  private processBuilderDexResult(dexMeta: MetaResponse, perpDexIndex: number): void {
+    const offset = 100000 + perpDexIndex * 10000;
+
+    dexMeta.universe.forEach((asset, index) => {
+      const assetId = offset + index;
+      this.nameToAssetId.set(asset.name, assetId);
+      this.nameToSzDecimals.set(asset.name, asset.szDecimals);
+    });
+  }
+
+  private processSpotAssets(spotMetaData: SpotMetaResponse): void {
+    const tokenMap = new Map<number, { name: string; szDecimals: number }>();
+    spotMetaData.tokens.forEach((token) => {
+      tokenMap.set(token.index, { name: token.name, szDecimals: token.szDecimals });
+    });
+
+    spotMetaData.universe.forEach((market) => {
+      if (market.tokens.length < 2) return;
+      const baseToken = tokenMap.get(market.tokens[0]);
+      const quoteToken = tokenMap.get(market.tokens[1]);
+      if (!baseToken || !quoteToken) return;
+
+      const assetId = 10000 + market.index;
+      const baseQuoteKey = `${baseToken.name}/${quoteToken.name}`;
+      this.nameToAssetId.set(baseQuoteKey, assetId);
+      this.nameToSzDecimals.set(baseQuoteKey, baseToken.szDecimals);
+      this.nameToSpotPairId.set(baseQuoteKey, market.name);
+    });
+  }
+
+  /**
+   * Get asset ID for a coin.
+   * - For Perpetuals, use the coin name (e.g., "BTC").
+   * - For Spot markets, use the "BASE/QUOTE" format (e.g., "HYPE/USDC").
+   * - For Builder Dex assets, use the "DEX_NAME:ASSET_NAME" format (e.g., "test:ABC").
+   *
+   * @example "BTC" → 0, "HYPE/USDC" → 10107, "test:ABC" → 110000
+   */
+  getAssetId(name: string): number | undefined {
+    return this.nameToAssetId.get(name);
+  }
+
+  /**
+   * Get size decimals for a coin.
+   * - For Perpetuals, use the coin name (e.g., "BTC").
+   * - For Spot markets, use the "BASE/QUOTE" format (e.g., "HYPE/USDC").
+   * - For Builder Dex assets, use the "DEX_NAME:ASSET_NAME" format (e.g., "test:ABC").
+   *
+   * @example "BTC" → 5, "HYPE/USDC" → 2, "test:ABC" → 0
+   */
+  getSzDecimals(name: string): number | undefined {
+    return this.nameToSzDecimals.get(name);
+  }
+
+  /**
+   * Get spot pair ID for info endpoints and subscriptions (e.g., l2book, trades).
+   *
+   * Accepts spot markets in the "BASE/QUOTE" format (e.g., "HFUN/USDC").
+   *
+   * @example "HFUN/USDC" → "@2", "PURR/USDC" → "PURR/USDC"
+   */
+  getSpotPairId(name: string): string | undefined {
+    return this.nameToSpotPairId.get(name);
+  }
+}