@hfunlabs/hyperliquid 0.27.1-hfunlabs.1

package/script/src/utils/_symbolConverter.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SymbolConverter = void 0;
+const meta_js_1 = require("../api/info/meta.js");
+const spotMeta_js_1 = require("../api/info/spotMeta.js");
+const perpDexs_js_1 = require("../api/info/perpDexs.js");
+/**
+ * Utility class for converting asset symbols to their corresponding IDs and size decimals.
+ * Supports perpetuals, spot markets, and optional builder dexs.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids
+ * @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"
+ * ```
+ */
+class SymbolConverter {
+    transport;
+    dexOption;
+    nameToAssetId = new Map();
+    nameToSzDecimals = new Map();
+    nameToSpotPairId = new Map();
+    constructor(options) {
+        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) {
+        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() {
+        const config = { transport: this.transport };
+        const [perpMetaData, spotMetaData, perpDexsData] = await Promise.all([
+            (0, meta_js_1.meta)(config),
+            (0, spotMeta_js_1.spotMeta)(config),
+            (0, perpDexs_js_1.perpDexs)(config),
+        ]);
+        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 (this.dexOption !== false) {
+            await this.processBuilderDexs(perpDexsData);
+        }
+    }
+    processDefaultPerps(perpMeta) {
+        perpMeta.universe.forEach((asset, index) => {
+            this.nameToAssetId.set(asset.name, index);
+            this.nameToSzDecimals.set(asset.name, asset.szDecimals);
+        });
+    }
+    async processBuilderDexs(perpDexs) {
+        if (!perpDexs || perpDexs.length <= 1)
+            return;
+        const builderDexs = perpDexs
+            .map((dex, index) => ({ dex, index }))
+            .filter((item) => {
+            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.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) => (0, meta_js_1.meta)(config, { dex: item.dex.name })));
+        results.forEach((result, idx) => {
+            if (result.status !== "fulfilled")
+                return;
+            this.processBuilderDexResult(result.value, dexsToProcess[idx].index);
+        });
+    }
+    processBuilderDexResult(meta, perpDexIndex) {
+        const offset = 100000 + perpDexIndex * 10000;
+        meta.universe.forEach((asset, index) => {
+            const assetId = offset + index;
+            this.nameToAssetId.set(asset.name, assetId);
+            this.nameToSzDecimals.set(asset.name, asset.szDecimals);
+        });
+    }
+    processSpotAssets(spotMeta) {
+        const tokenMap = new Map();
+        spotMeta.tokens.forEach((token) => {
+            tokenMap.set(token.index, { name: token.name, szDecimals: token.szDecimals });
+        });
+        spotMeta.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) {
+        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) {
+        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) {
+        return this.nameToSpotPairId.get(name);
+    }
+}
+exports.SymbolConverter = SymbolConverter;
+//# sourceMappingURL=_symbolConverter.js.map

package/script/src/utils/_symbolConverter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_symbolConverter.js","sourceRoot":"","sources":["../../../src/src/utils/_symbolConverter.ts"],"names":[],"mappings":"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"}

package/script/src/utils/mod.d.ts

@@ -0,0 +1,4 @@
+export * from "./_symbolConverter.js";
+export * from "./_format.js";
+export * from "./_recover.js";
+//# sourceMappingURL=mod.d.ts.map

package/script/src/utils/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/src/utils/mod.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC"}

package/script/src/utils/mod.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./_symbolConverter.js"), exports);
+__exportStar(require("./_format.js"), exports);
+__exportStar(require("./_recover.js"), exports);
+//# sourceMappingURL=mod.js.map

package/script/src/utils/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../../src/src/utils/mod.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wDAAsC;AACtC,+CAA6B;AAC7B,gDAA8B"}

package/src/bin/_utils.ts

@@ -0,0 +1,181 @@
+export type RawArgs = {
+  [key: string]: string | undefined;
+} & {
+  _: string[];
+};
+
+export type ParseOptions = {
+  /**
+   * Consider these keys as flags (no value expected).
+   * Value going after a flag will be treated as a positional argument.
+   */
+  flags?: string[];
+};
+
+/**
+ * Parse command-line arguments into a key-value object.
+ * Does not transform values.
+ */
+export function parseArgs(args: string[], options?: ParseOptions): RawArgs {
+  const result = { _: [] } as unknown as RawArgs;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const nextArg = args[i + 1] as string | undefined;
+
+    if (arg.startsWith("-")) {
+      if (arg === "-_" || arg === "--_") continue; // Skip reserved key "_"
+
+      const isLong = arg.startsWith("--");
+      let keyPart = arg.slice(isLong ? 2 : 1);
+      let value: string | undefined;
+      const eqIndex = keyPart.indexOf("=");
+
+      if (eqIndex !== -1) {
+        value = keyPart.substring(eqIndex + 1);
+        keyPart = keyPart.substring(0, eqIndex);
+      } else if (
+        !options?.flags?.includes(keyPart) && // Skip if key is defined as flag and don't expect value
+        typeof nextArg === "string" && (!nextArg.startsWith("-") || !isNaN(parseFloat(nextArg)))
+      ) {
+        value = nextArg;
+        i++; // Skip next arg as it's consumed as value for current key
+      }
+      result[keyPart] = value;
+    } else {
+      result._.push(arg);
+    }
+  }
+  return result;
+}
+
+export interface TransformOptions {
+  /**
+   * Transform rule for flags (keys without values).
+   * @value `undefined`
+   * @default "true"
+   */
+  flag?: "true" | "false" | ((key: string) => "true" | "false");
+  /**
+   * Transform rule for null values.
+   * @value `"null"` (case insensitive)
+   * @default "null"
+   */
+  null?: "null" | "string" | ((key: string, value: string) => "null" | "string");
+  /**
+   * Transform rule for boolean values.
+   * @value `"true"`, `"false"` (case insensitive)
+   * @default "bool"
+   */
+  bool?: "bool" | "string" | ((key: string, value: string) => "bool" | "string");
+  /**
+   * Transform rule for hexadecimal values.
+   * @value `"0xff"`, `"0X1A"` (case insensitive) (0x prefix required)
+   * @default "string"
+   */
+  hex?: "string" | "number" | ((key: string, value: string) => "string" | "number");
+  /**
+   * Transform rule for special numeric values.
+   * @value `"Infinity"`, `"-Infinity"`, `"NaN"`, `"-NaN"` (case insensitive)
+   * @default "string"
+   */
+  specialNumber?: "string" | "number" | ((key: string, value: string) => "string" | "number");
+  /**
+   * Transform rule for numeric values.
+   * @value `"123"`, `"12.3"`, `"1e+2"`, `"+123"`, `"-123"` (anything that can be parsed by `Number(value)`) (excludes hex values)
+   * @default "number"
+   */
+  number?: "number" | "string" | ((key: string, value: string) => "number" | "string");
+  /**
+   * Transform rule for JSON object/array values.
+   * @value `"{ \"a\": 1 }"`, `"[invalid array string]"` (anything that begins with `{` and ends with `}` or begins with `[` and ends with `]`)
+   * @default "object"
+   */
+  json?: "object" | "string" | ((key: string, value: string) => "object" | "string");
+}
+
+export interface Args {
+  [key: string]: string | number | boolean | null | Record<string, unknown> | unknown[];
+  _: string[];
+}
+
+/**
+ * Transform raw args (string values) into typed args based on rules.
+ *
+ * Order of transformation:
+ * 1. flag (`undefined`)
+ * 2. null (`"null"`)
+ * 3. boolean (`"true"`, `"false"`)
+ * 4. hex (`"0x..."`)
+ * 5. special number (`"Infinity"`, `"-Infinity"`, `"NaN", "-NaN"`)
+ * 6. number (numeric strings)
+ * 7. json (object/array strings)
+ * 8. string (default)
+ */
+export function transformArgs(args: RawArgs, options?: TransformOptions): Args {
+  const opts = {
+    flag: "true",
+    null: "null",
+    bool: "bool",
+    hex: "string",
+    specialNumber: "string",
+    number: "number",
+    json: "object",
+    ...options,
+  } as const;
+
+  const result: Args = { _: args._ };
+  for (const key in args) {
+    if (key === "_") continue; // Skip the positional args array
+
+    const value = args[key];
+
+    // Transformation logic
+    let transformedValue: Args[string];
+
+    // flag
+    if (value === undefined) {
+      const action = typeof opts.flag === "function" ? opts.flag(key) : opts.flag;
+      transformedValue = action === "true" ? true : false;
+    } // null
+    else if (value.toLowerCase() === "null") {
+      const action = typeof opts.null === "function" ? opts.null(key, value) : opts.null;
+      transformedValue = action === "null" ? null : value;
+    } // boolean
+    else if (value.toLowerCase() === "true" || value.toLowerCase() === "false") {
+      const action = typeof opts.bool === "function" ? opts.bool(key, value) : opts.bool;
+      transformedValue = action === "bool" ? value.toLowerCase() === "true" : value;
+    } // hex
+    else if ((value.startsWith("0x") || value.startsWith("0X")) && !isNaN(parseInt(value, 16))) {
+      const action = typeof opts.hex === "function" ? opts.hex(key, value) : opts.hex;
+      transformedValue = action === "string" ? value : parseInt(value, 16);
+    } // special number
+    else if (
+      value.toLowerCase() === "infinity" || value.toLowerCase() === "-infinity" ||
+      value.toLowerCase() === "nan" || value.toLowerCase() === "-nan"
+    ) {
+      const action = typeof opts.specialNumber === "function" ? opts.specialNumber(key, value) : opts.specialNumber;
+      transformedValue = action === "string" ? value : Number(value);
+    } // number
+    else if (!isNaN(Number(value))) {
+      const action = typeof opts.number === "function" ? opts.number(key, value) : opts.number;
+      transformedValue = action === "number" ? Number(value) : value;
+    } // json object/array
+    else if (
+      (value.startsWith("{") && value.endsWith("}")) ||
+      (value.startsWith("[") && value.endsWith("]"))
+    ) {
+      const action = typeof opts.json === "function" ? opts.json(key, value) : opts.json;
+      try {
+        transformedValue = action === "object" ? JSON.parse(value) as Record<string, unknown> | unknown[] : value;
+      } catch {
+        transformedValue = value;
+      }
+    } // string (default)
+    else {
+      transformedValue = value;
+    }
+
+    result[key] = transformedValue;
+  }
+  return result;
+}