@basedone/core 0.0.6 → 0.0.7

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { SpotToken, PerpsMeta, PerpsAssetCtx, SpotMeta, PerpDex } from '@nktkas/hyperliquid';
+import { SpotToken, PerpsMeta, PerpsAssetCtx, SpotMeta } from '@nktkas/hyperliquid';
+import { Hex } from '@nktkas/hyperliquid/script/src/types/mod';
 
 declare function encodeSlug(slug: string): bigint;
 declare function decodeSlug(value: bigint): string;
@@ -233,6 +234,18 @@ declare function getNextTierInfo(pupTokenAmount: number, normalizedAirDropAmount
 declare const USDC_SPOT_TOKEN: SpotToken;
 declare const TESTNET_USDC_SPOT_TOKEN: SpotToken;
 
+interface PerpDex {
+    /** Short name of the perpetual dex. */
+    name: string;
+    /** Complete name of the perpetual dex. */
+    fullName: string;
+    /** Hex address of the dex deployer. */
+    deployer: Hex;
+    /** Hex address of the oracle updater, or null if not available. */
+    oracleUpdater: Hex | null;
+    feeRecipient: Hex | null;
+    assetToStreamingOiCap: [string, string][];
+}
 /**
  * Market information for trading operations
  */
@@ -242,11 +255,15 @@ interface MarketInfo {
     szDecimals: number;
     type: "perps" | "spot" | "hip3";
     coin: string;
+    displayName?: string;
+    imageUrl?: string;
     maxLeverage?: number;
     baseToken?: SpotToken;
     quoteToken?: SpotToken;
     dexName?: string;
     dexIndex?: number;
+    dexDisplayName?: string;
+    dexImageUrl?: string;
 }
 interface DexInfo {
     meta: PerpsMeta;
@@ -255,6 +272,8 @@ interface DexInfo {
     dexName: string;
     dexIndex: number;
     collateralTokenSymbol: string;
+    displayName?: string;
+    imageUrl?: string;
 }
 type ExtendedPerpsMeta = PerpsMeta & {
     collateralToken?: number;
@@ -298,6 +317,7 @@ interface MetadataClientConfig {
  * - Spot: 10000 + index
  * - HIP-3: 100000 + perp_dex_index * 10000 + index_in_meta
  */
+declare const ROOT_DEX = "hyperliquid";
 declare class MetadataClient {
     private infoClient;
     private config;
@@ -305,6 +325,7 @@ declare class MetadataClient {
     private spotMeta;
     private perpsMeta;
     private perpDexs;
+    private staticMeta;
     private hip3DexsMeta;
     private perpsSymbolToIndex;
     private spotTokenNameToIndex;
@@ -320,6 +341,11 @@ declare class MetadataClient {
      * Initialize metadata by fetching from Hyperliquid
      */
     initialize(): Promise<void>;
+    /**
+     * Load staticMeta.json for display overrides
+     * This is always loaded regardless of config.useStaticFallback
+     */
+    private loadStaticMetaOverrides;
     /**
      * Load static metadata from bundled JSON files
      */
@@ -459,4 +485,4 @@ declare const formatSizeForOrder: ({ sz, szDecimals, }: {
  */
 declare function getPriceDecimals(price: number, szDecimals: number, isSpot: boolean): number;
 
-export { type AirdropAllocationData, CloidClientCode, type CloidClientCodeId, CloidClientCodeNameById, type CloidData, type DexInfo, type ExtendedPerpsMeta, type MarketInfo, MetadataClient, PUP_TOKEN_ADDRESS, PUP_TOKEN_THRESHOLDS, type PupEligibilityResult, TARGET_APPROVED_MAX_BUILDER_FEE, TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT, TESTNET_USDC_SPOT_TOKEN, type TokenInfo, USDC_SPOT_TOKEN, type UpheavalApiResponse, type UpheavalPosition, type UpheavalSnapshot, type V3LPTokenInfo, WidgetType, WidgetTypeById, type WidgetTypeId, XP_BOOST_PERCENTAGES, buildCloid, calculateBoostPercentage, calculateTotalPupAmount, decodeSlug, encodeSlug, formatPriceAndSize, formatPriceForOrder, formatSizeForOrder, getApprovalAmount, getClientCodeNameById, getCloid, getNextTierInfo, getPriceDecimals, getWidgetTypeById, isBasedCloid, isClientCode, isMiniAppCloid, isMiniAppTriggeredCloid, isTenantCloid, isTrackingIdCloid, isWidgetType, normaliseSlug, normaliseTrackingId, normalizeAirdropAmount, parseCloid };
+export { type AirdropAllocationData, CloidClientCode, type CloidClientCodeId, CloidClientCodeNameById, type CloidData, type DexInfo, type ExtendedPerpsMeta, type MarketInfo, MetadataClient, PUP_TOKEN_ADDRESS, PUP_TOKEN_THRESHOLDS, type PerpDex, type PupEligibilityResult, ROOT_DEX, TARGET_APPROVED_MAX_BUILDER_FEE, TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT, TESTNET_USDC_SPOT_TOKEN, type TokenInfo, USDC_SPOT_TOKEN, type UpheavalApiResponse, type UpheavalPosition, type UpheavalSnapshot, type V3LPTokenInfo, WidgetType, WidgetTypeById, type WidgetTypeId, XP_BOOST_PERCENTAGES, buildCloid, calculateBoostPercentage, calculateTotalPupAmount, decodeSlug, encodeSlug, formatPriceAndSize, formatPriceForOrder, formatSizeForOrder, getApprovalAmount, getClientCodeNameById, getCloid, getNextTierInfo, getPriceDecimals, getWidgetTypeById, isBasedCloid, isClientCode, isMiniAppCloid, isMiniAppTriggeredCloid, isTenantCloid, isTrackingIdCloid, isWidgetType, normaliseSlug, normaliseTrackingId, normalizeAirdropAmount, parseCloid };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { SpotToken, PerpsMeta, PerpsAssetCtx, SpotMeta, PerpDex } from '@nktkas/hyperliquid';
+import { SpotToken, PerpsMeta, PerpsAssetCtx, SpotMeta } from '@nktkas/hyperliquid';
+import { Hex } from '@nktkas/hyperliquid/script/src/types/mod';
 
 declare function encodeSlug(slug: string): bigint;
 declare function decodeSlug(value: bigint): string;
@@ -233,6 +234,18 @@ declare function getNextTierInfo(pupTokenAmount: number, normalizedAirDropAmount
 declare const USDC_SPOT_TOKEN: SpotToken;
 declare const TESTNET_USDC_SPOT_TOKEN: SpotToken;
 
+interface PerpDex {
+    /** Short name of the perpetual dex. */
+    name: string;
+    /** Complete name of the perpetual dex. */
+    fullName: string;
+    /** Hex address of the dex deployer. */
+    deployer: Hex;
+    /** Hex address of the oracle updater, or null if not available. */
+    oracleUpdater: Hex | null;
+    feeRecipient: Hex | null;
+    assetToStreamingOiCap: [string, string][];
+}
 /**
  * Market information for trading operations
  */
@@ -242,11 +255,15 @@ interface MarketInfo {
     szDecimals: number;
     type: "perps" | "spot" | "hip3";
     coin: string;
+    displayName?: string;
+    imageUrl?: string;
     maxLeverage?: number;
     baseToken?: SpotToken;
     quoteToken?: SpotToken;
     dexName?: string;
     dexIndex?: number;
+    dexDisplayName?: string;
+    dexImageUrl?: string;
 }
 interface DexInfo {
     meta: PerpsMeta;
@@ -255,6 +272,8 @@ interface DexInfo {
     dexName: string;
     dexIndex: number;
     collateralTokenSymbol: string;
+    displayName?: string;
+    imageUrl?: string;
 }
 type ExtendedPerpsMeta = PerpsMeta & {
     collateralToken?: number;
@@ -298,6 +317,7 @@ interface MetadataClientConfig {
  * - Spot: 10000 + index
  * - HIP-3: 100000 + perp_dex_index * 10000 + index_in_meta
  */
+declare const ROOT_DEX = "hyperliquid";
 declare class MetadataClient {
     private infoClient;
     private config;
@@ -305,6 +325,7 @@ declare class MetadataClient {
     private spotMeta;
     private perpsMeta;
     private perpDexs;
+    private staticMeta;
     private hip3DexsMeta;
     private perpsSymbolToIndex;
     private spotTokenNameToIndex;
@@ -320,6 +341,11 @@ declare class MetadataClient {
      * Initialize metadata by fetching from Hyperliquid
      */
     initialize(): Promise<void>;
+    /**
+     * Load staticMeta.json for display overrides
+     * This is always loaded regardless of config.useStaticFallback
+     */
+    private loadStaticMetaOverrides;
     /**
      * Load static metadata from bundled JSON files
      */
@@ -459,4 +485,4 @@ declare const formatSizeForOrder: ({ sz, szDecimals, }: {
  */
 declare function getPriceDecimals(price: number, szDecimals: number, isSpot: boolean): number;
 
-export { type AirdropAllocationData, CloidClientCode, type CloidClientCodeId, CloidClientCodeNameById, type CloidData, type DexInfo, type ExtendedPerpsMeta, type MarketInfo, MetadataClient, PUP_TOKEN_ADDRESS, PUP_TOKEN_THRESHOLDS, type PupEligibilityResult, TARGET_APPROVED_MAX_BUILDER_FEE, TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT, TESTNET_USDC_SPOT_TOKEN, type TokenInfo, USDC_SPOT_TOKEN, type UpheavalApiResponse, type UpheavalPosition, type UpheavalSnapshot, type V3LPTokenInfo, WidgetType, WidgetTypeById, type WidgetTypeId, XP_BOOST_PERCENTAGES, buildCloid, calculateBoostPercentage, calculateTotalPupAmount, decodeSlug, encodeSlug, formatPriceAndSize, formatPriceForOrder, formatSizeForOrder, getApprovalAmount, getClientCodeNameById, getCloid, getNextTierInfo, getPriceDecimals, getWidgetTypeById, isBasedCloid, isClientCode, isMiniAppCloid, isMiniAppTriggeredCloid, isTenantCloid, isTrackingIdCloid, isWidgetType, normaliseSlug, normaliseTrackingId, normalizeAirdropAmount, parseCloid };
+export { type AirdropAllocationData, CloidClientCode, type CloidClientCodeId, CloidClientCodeNameById, type CloidData, type DexInfo, type ExtendedPerpsMeta, type MarketInfo, MetadataClient, PUP_TOKEN_ADDRESS, PUP_TOKEN_THRESHOLDS, type PerpDex, type PupEligibilityResult, ROOT_DEX, TARGET_APPROVED_MAX_BUILDER_FEE, TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT, TESTNET_USDC_SPOT_TOKEN, type TokenInfo, USDC_SPOT_TOKEN, type UpheavalApiResponse, type UpheavalPosition, type UpheavalSnapshot, type V3LPTokenInfo, WidgetType, WidgetTypeById, type WidgetTypeId, XP_BOOST_PERCENTAGES, buildCloid, calculateBoostPercentage, calculateTotalPupAmount, decodeSlug, encodeSlug, formatPriceAndSize, formatPriceForOrder, formatSizeForOrder, getApprovalAmount, getClientCodeNameById, getCloid, getNextTierInfo, getPriceDecimals, getWidgetTypeById, isBasedCloid, isClientCode, isMiniAppCloid, isMiniAppTriggeredCloid, isTenantCloid, isTrackingIdCloid, isWidgetType, normaliseSlug, normaliseTrackingId, normalizeAirdropAmount, parseCloid };

package/dist/index.js

@@ -35,6 +35,44 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// lib/meta/data/mainnet/staticMeta.json
+var require_staticMeta = __commonJS({
+  "lib/meta/data/mainnet/staticMeta.json"(exports2, module2) {
+    module2.exports = {
+      coins: {
+        "xyz:XYZ100": {
+          imageUrl: "https://app.based.one/hip3/xyz/xyz100.webp",
+          displayName: "Nasdaq-100"
+        }
+      },
+      dexs: {
+        xyz: {
+          imageUrl: "",
+          displayName: "Stocks"
+        }
+      }
+    };
+  }
+});
+
+// lib/meta/data/testnet/staticMeta.json
+var require_staticMeta2 = __commonJS({
+  "lib/meta/data/testnet/staticMeta.json"(exports2, module2) {
+    module2.exports = {
+      coins: {
+        "rrrrr:BTC": {
+          displayName: "BTCe"
+        }
+      },
+      dexs: {
+        rrrrr: {
+          displayName: "Hyena"
+        }
+      }
+    };
+  }
+});
+
 // lib/meta/data/mainnet/spotMeta.json
 var require_spotMeta = __commonJS({
   "lib/meta/data/mainnet/spotMeta.json"(exports2, module2) {
@@ -36407,6 +36445,7 @@ __export(index_exports, {
   MetadataClient: () => MetadataClient,
   PUP_TOKEN_ADDRESS: () => PUP_TOKEN_ADDRESS,
   PUP_TOKEN_THRESHOLDS: () => PUP_TOKEN_THRESHOLDS,
+  ROOT_DEX: () => ROOT_DEX,
   TARGET_APPROVED_MAX_BUILDER_FEE: () => TARGET_APPROVED_MAX_BUILDER_FEE,
   TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT: () => TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT,
   TESTNET_USDC_SPOT_TOKEN: () => TESTNET_USDC_SPOT_TOKEN,
@@ -36979,6 +37018,12 @@ function isHip3Symbol(symbol) {
   return symbol.includes(":");
 }
 
+// import("./data/**/*/staticMeta.json") in lib/meta/metadata.ts
+var globImport_data_staticMeta_json = __glob({
+  "./data/mainnet/staticMeta.json": () => Promise.resolve().then(() => __toESM(require_staticMeta())),
+  "./data/testnet/staticMeta.json": () => Promise.resolve().then(() => __toESM(require_staticMeta2()))
+});
+
 // import("./data/**/*/spotMeta.json") in lib/meta/metadata.ts
 var globImport_data_spotMeta_json = __glob({
   "./data/mainnet/spotMeta.json": () => Promise.resolve().then(() => __toESM(require_spotMeta())),
@@ -36998,12 +37043,14 @@ var globImport_data_perpDexs_json = __glob({
 });
 
 // lib/meta/metadata.ts
+var ROOT_DEX = "hyperliquid";
 var MetadataClient = class {
   constructor(config = {}) {
     // Core metadata
     this.spotMeta = null;
     this.perpsMeta = null;
     this.perpDexs = [];
+    this.staticMeta = null;
     // HIP-3 metadata cache
     this.hip3DexsMeta = /* @__PURE__ */ new Map();
     // Pre-computed lookup maps (populated on initialize)
@@ -37028,6 +37075,7 @@ var MetadataClient = class {
     this.infoClient = new import_hyperliquid.InfoClient({ transport });
     this.config = {
       ...config,
+      hip3Dexs: config.hip3Dexs?.filter((dex) => dex !== ROOT_DEX),
       useStaticFallback: config.useStaticFallback ?? true
     };
     this.isTestnet = config.isTestnet ?? false;
@@ -37038,6 +37086,7 @@ var MetadataClient = class {
    */
   async initialize() {
     if (this.initialized) return;
+    await this.loadStaticMetaOverrides();
     if (this.config.onlyUseStaticFallback) {
       await this.loadStaticMetadata();
       this.buildLookupMaps();
@@ -37076,20 +37125,41 @@ var MetadataClient = class {
       }
     }
   }
+  /**
+   * Load staticMeta.json for display overrides
+   * This is always loaded regardless of config.useStaticFallback
+   */
+  async loadStaticMetaOverrides() {
+    const network = this.isTestnet ? "testnet" : "mainnet";
+    try {
+      const staticMetaModule = await globImport_data_staticMeta_json(`./data/${network}/staticMeta.json`);
+      this.staticMeta = staticMetaModule.default;
+    } catch (error) {
+      console.warn(`Failed to load staticMeta.json for ${network}:`, error);
+      this.staticMeta = null;
+    }
+  }
   /**
    * Load static metadata from bundled JSON files
    */
   async loadStaticMetadata() {
     const network = this.isTestnet ? "testnet" : "mainnet";
     try {
-      const [spotMetaModule, perpsMetaModule, perpDexsModule] = await Promise.all([
+      const [
+        spotMetaModule,
+        perpsMetaModule,
+        perpDexsModule,
+        staticMetaModule
+      ] = await Promise.all([
         globImport_data_spotMeta_json(`./data/${network}/spotMeta.json`),
         globImport_data_meta_json(`./data/${network}/meta.json`),
-        globImport_data_perpDexs_json(`./data/${network}/perpDexs.json`)
+        globImport_data_perpDexs_json(`./data/${network}/perpDexs.json`),
+        globImport_data_staticMeta_json(`./data/${network}/staticMeta.json`)
       ]);
       this.spotMeta = spotMetaModule.default;
       this.perpsMeta = perpsMetaModule.default;
       this.perpDexs = perpDexsModule.default;
+      this.staticMeta = staticMetaModule.default;
       console.warn(`Using static ${network} metadata`);
     } catch (error) {
       console.error(`Failed to load static ${network} metadata:`, error);
@@ -37126,6 +37196,15 @@ var MetadataClient = class {
           type: "perps",
           maxLeverage: market.maxLeverage
         };
+        const staticOverrides = this.staticMeta?.coins?.[market.name];
+        if (staticOverrides) {
+          if (staticOverrides.displayName) {
+            marketInfo.displayName = staticOverrides.displayName;
+          }
+          if (staticOverrides.imageUrl) {
+            marketInfo.imageUrl = staticOverrides.imageUrl;
+          }
+        }
         this.perpsSymbolToIndex.set(market.name.toUpperCase(), index);
         this.coinToMarket.set(market.name, marketInfo);
       });
@@ -37150,6 +37229,15 @@ var MetadataClient = class {
           baseToken,
           quoteToken
         };
+        const staticOverrides = this.staticMeta?.coins?.[coin];
+        if (staticOverrides) {
+          if (staticOverrides.displayName) {
+            marketInfo.displayName = staticOverrides.displayName;
+          }
+          if (staticOverrides.imageUrl) {
+            marketInfo.imageUrl = staticOverrides.imageUrl;
+          }
+        }
         const pairKey = `${baseToken.name}/${quoteToken.name}`.toUpperCase();
         this.spotPairToMarket.set(pairKey, marketInfo);
         this.coinToMarket.set(pairKey, marketInfo);
@@ -37189,10 +37277,19 @@ var MetadataClient = class {
         meta,
         assetContext: contexts,
         collateralTokenSymbol,
-        dexFullName: dex?.full_name ?? dexName,
+        dexFullName: dex?.fullName ?? dexName,
         dexName: dex?.name ?? dexName,
         dexIndex
       };
+      const staticDexOverrides = this.staticMeta?.dexs?.[dexName];
+      if (staticDexOverrides) {
+        if (staticDexOverrides.displayName) {
+          dexInfo.displayName = staticDexOverrides.displayName;
+        }
+        if (staticDexOverrides.imageUrl) {
+          dexInfo.imageUrl = staticDexOverrides.imageUrl;
+        }
+      }
       this.hip3DexsMeta.set(dexName, dexInfo);
       this.buildHip3MarketsForDex(dexName, dexInfo);
       return dexInfo;
@@ -37215,8 +37312,19 @@ var MetadataClient = class {
         type: "hip3",
         maxLeverage: market.maxLeverage,
         dexName,
-        dexIndex: dexInfo.dexIndex
+        dexIndex: dexInfo.dexIndex,
+        dexDisplayName: dexInfo.displayName,
+        dexImageUrl: dexInfo.imageUrl
       };
+      const staticOverrides = this.staticMeta?.coins?.[symbol];
+      if (staticOverrides) {
+        if (staticOverrides.displayName) {
+          marketInfo.displayName = staticOverrides.displayName;
+        }
+        if (staticOverrides.imageUrl) {
+          marketInfo.imageUrl = staticOverrides.imageUrl;
+        }
+      }
       this.coinToMarket.set(symbol, marketInfo);
       this.hip3SymbolToMarket.set(symbol, marketInfo);
     });
@@ -37245,7 +37353,7 @@ var MetadataClient = class {
     }
     let lookupKey = symbol.toUpperCase();
     if (!symbol.includes("/") && !symbol.includes("@")) {
-      const perpsMarket = this.coinToMarket.get(lookupKey);
+      const perpsMarket = this.coinToMarket.get(symbol);
       if (perpsMarket?.type === "perps") {
         return perpsMarket;
       }
@@ -37430,6 +37538,7 @@ function getPriceDecimals(price, szDecimals, isSpot) {
   MetadataClient,
   PUP_TOKEN_ADDRESS,
   PUP_TOKEN_THRESHOLDS,
+  ROOT_DEX,
   TARGET_APPROVED_MAX_BUILDER_FEE,
   TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT,
   TESTNET_USDC_SPOT_TOKEN,

package/dist/index.mjs

@@ -542,6 +542,12 @@ function isHip3Symbol(symbol) {
   return symbol.includes(":");
 }
 
+// import("./data/**/*/staticMeta.json") in lib/meta/metadata.ts
+var globImport_data_staticMeta_json = __glob({
+  "./data/mainnet/staticMeta.json": () => import("./staticMeta-HRXST42O.mjs"),
+  "./data/testnet/staticMeta.json": () => import("./staticMeta-QWPQK3MD.mjs")
+});
+
 // import("./data/**/*/spotMeta.json") in lib/meta/metadata.ts
 var globImport_data_spotMeta_json = __glob({
   "./data/mainnet/spotMeta.json": () => import("./spotMeta-7IJT3W6H.mjs"),
@@ -561,12 +567,14 @@ var globImport_data_perpDexs_json = __glob({
 });
 
 // lib/meta/metadata.ts
+var ROOT_DEX = "hyperliquid";
 var MetadataClient = class {
   constructor(config = {}) {
     // Core metadata
     this.spotMeta = null;
     this.perpsMeta = null;
     this.perpDexs = [];
+    this.staticMeta = null;
     // HIP-3 metadata cache
     this.hip3DexsMeta = /* @__PURE__ */ new Map();
     // Pre-computed lookup maps (populated on initialize)
@@ -591,6 +599,7 @@ var MetadataClient = class {
     this.infoClient = new InfoClient({ transport });
     this.config = {
       ...config,
+      hip3Dexs: config.hip3Dexs?.filter((dex) => dex !== ROOT_DEX),
       useStaticFallback: config.useStaticFallback ?? true
     };
     this.isTestnet = config.isTestnet ?? false;
@@ -601,6 +610,7 @@ var MetadataClient = class {
    */
   async initialize() {
     if (this.initialized) return;
+    await this.loadStaticMetaOverrides();
     if (this.config.onlyUseStaticFallback) {
       await this.loadStaticMetadata();
       this.buildLookupMaps();
@@ -639,20 +649,41 @@ var MetadataClient = class {
       }
     }
   }
+  /**
+   * Load staticMeta.json for display overrides
+   * This is always loaded regardless of config.useStaticFallback
+   */
+  async loadStaticMetaOverrides() {
+    const network = this.isTestnet ? "testnet" : "mainnet";
+    try {
+      const staticMetaModule = await globImport_data_staticMeta_json(`./data/${network}/staticMeta.json`);
+      this.staticMeta = staticMetaModule.default;
+    } catch (error) {
+      console.warn(`Failed to load staticMeta.json for ${network}:`, error);
+      this.staticMeta = null;
+    }
+  }
   /**
    * Load static metadata from bundled JSON files
    */
   async loadStaticMetadata() {
     const network = this.isTestnet ? "testnet" : "mainnet";
     try {
-      const [spotMetaModule, perpsMetaModule, perpDexsModule] = await Promise.all([
+      const [
+        spotMetaModule,
+        perpsMetaModule,
+        perpDexsModule,
+        staticMetaModule
+      ] = await Promise.all([
         globImport_data_spotMeta_json(`./data/${network}/spotMeta.json`),
         globImport_data_meta_json(`./data/${network}/meta.json`),
-        globImport_data_perpDexs_json(`./data/${network}/perpDexs.json`)
+        globImport_data_perpDexs_json(`./data/${network}/perpDexs.json`),
+        globImport_data_staticMeta_json(`./data/${network}/staticMeta.json`)
       ]);
       this.spotMeta = spotMetaModule.default;
       this.perpsMeta = perpsMetaModule.default;
       this.perpDexs = perpDexsModule.default;
+      this.staticMeta = staticMetaModule.default;
       console.warn(`Using static ${network} metadata`);
     } catch (error) {
       console.error(`Failed to load static ${network} metadata:`, error);
@@ -689,6 +720,15 @@ var MetadataClient = class {
           type: "perps",
           maxLeverage: market.maxLeverage
         };
+        const staticOverrides = this.staticMeta?.coins?.[market.name];
+        if (staticOverrides) {
+          if (staticOverrides.displayName) {
+            marketInfo.displayName = staticOverrides.displayName;
+          }
+          if (staticOverrides.imageUrl) {
+            marketInfo.imageUrl = staticOverrides.imageUrl;
+          }
+        }
         this.perpsSymbolToIndex.set(market.name.toUpperCase(), index);
         this.coinToMarket.set(market.name, marketInfo);
       });
@@ -713,6 +753,15 @@ var MetadataClient = class {
           baseToken,
           quoteToken
         };
+        const staticOverrides = this.staticMeta?.coins?.[coin];
+        if (staticOverrides) {
+          if (staticOverrides.displayName) {
+            marketInfo.displayName = staticOverrides.displayName;
+          }
+          if (staticOverrides.imageUrl) {
+            marketInfo.imageUrl = staticOverrides.imageUrl;
+          }
+        }
         const pairKey = `${baseToken.name}/${quoteToken.name}`.toUpperCase();
         this.spotPairToMarket.set(pairKey, marketInfo);
         this.coinToMarket.set(pairKey, marketInfo);
@@ -752,10 +801,19 @@ var MetadataClient = class {
         meta,
         assetContext: contexts,
         collateralTokenSymbol,
-        dexFullName: dex?.full_name ?? dexName,
+        dexFullName: dex?.fullName ?? dexName,
         dexName: dex?.name ?? dexName,
         dexIndex
       };
+      const staticDexOverrides = this.staticMeta?.dexs?.[dexName];
+      if (staticDexOverrides) {
+        if (staticDexOverrides.displayName) {
+          dexInfo.displayName = staticDexOverrides.displayName;
+        }
+        if (staticDexOverrides.imageUrl) {
+          dexInfo.imageUrl = staticDexOverrides.imageUrl;
+        }
+      }
       this.hip3DexsMeta.set(dexName, dexInfo);
       this.buildHip3MarketsForDex(dexName, dexInfo);
       return dexInfo;
@@ -778,8 +836,19 @@ var MetadataClient = class {
         type: "hip3",
         maxLeverage: market.maxLeverage,
         dexName,
-        dexIndex: dexInfo.dexIndex
+        dexIndex: dexInfo.dexIndex,
+        dexDisplayName: dexInfo.displayName,
+        dexImageUrl: dexInfo.imageUrl
       };
+      const staticOverrides = this.staticMeta?.coins?.[symbol];
+      if (staticOverrides) {
+        if (staticOverrides.displayName) {
+          marketInfo.displayName = staticOverrides.displayName;
+        }
+        if (staticOverrides.imageUrl) {
+          marketInfo.imageUrl = staticOverrides.imageUrl;
+        }
+      }
       this.coinToMarket.set(symbol, marketInfo);
       this.hip3SymbolToMarket.set(symbol, marketInfo);
     });
@@ -808,7 +877,7 @@ var MetadataClient = class {
     }
     let lookupKey = symbol.toUpperCase();
     if (!symbol.includes("/") && !symbol.includes("@")) {
-      const perpsMarket = this.coinToMarket.get(lookupKey);
+      const perpsMarket = this.coinToMarket.get(symbol);
       if (perpsMarket?.type === "perps") {
         return perpsMarket;
       }
@@ -992,6 +1061,7 @@ export {
   MetadataClient,
   PUP_TOKEN_ADDRESS,
   PUP_TOKEN_THRESHOLDS,
+  ROOT_DEX,
   TARGET_APPROVED_MAX_BUILDER_FEE,
   TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT,
   TESTNET_USDC_SPOT_TOKEN,

package/dist/staticMeta-HRXST42O.mjs

@@ -0,0 +1,24 @@
+import "./chunk-4UEJOM6W.mjs";
+
+// lib/meta/data/mainnet/staticMeta.json
+var coins = {
+  "xyz:XYZ100": {
+    imageUrl: "https://app.based.one/hip3/xyz/xyz100.webp",
+    displayName: "Nasdaq-100"
+  }
+};
+var dexs = {
+  xyz: {
+    imageUrl: "",
+    displayName: "Stocks"
+  }
+};
+var staticMeta_default = {
+  coins,
+  dexs
+};
+export {
+  coins,
+  staticMeta_default as default,
+  dexs
+};

package/dist/staticMeta-QWPQK3MD.mjs

@@ -0,0 +1,22 @@
+import "./chunk-4UEJOM6W.mjs";
+
+// lib/meta/data/testnet/staticMeta.json
+var coins = {
+  "rrrrr:BTC": {
+    displayName: "BTCe"
+  }
+};
+var dexs = {
+  rrrrr: {
+    displayName: "Hyena"
+  }
+};
+var staticMeta_default = {
+  coins,
+  dexs
+};
+export {
+  coins,
+  staticMeta_default as default,
+  dexs
+};

package/lib/meta/data/mainnet/dexs/xyz.json

@@ -0,0 +1,26 @@
+{
+    "universe": [
+        {
+            "szDecimals": 4,
+            "name": "xyz:XYZ100",
+            "maxLeverage": 20,
+            "marginTableId": 20,
+            "onlyIsolated": true
+        }
+    ],
+    "marginTables": [
+        [
+            50,
+            {
+                "description": "",
+                "marginTiers": [
+                    {
+                        "lowerBound": "0.0",
+                        "maxLeverage": 50
+                    }
+                ]
+            }
+        ]
+    ],
+    "collateralToken": 0
+}

package/lib/meta/data/mainnet/staticMeta.json

@@ -0,0 +1,14 @@
+{
+    "coins": {
+        "xyz:XYZ100": {
+            "imageUrl": "https://app.based.one/hip3/xyz/xyz100.webp",
+            "displayName": "Nasdaq-100"
+        }
+    },
+    "dexs": {
+        "xyz": {
+            "imageUrl": "",
+            "displayName": "Stocks"
+        }
+    }
+}

package/lib/meta/data/testnet/staticMeta.json

@@ -0,0 +1,12 @@
+{
+    "coins": {
+        "rrrrr:BTC": {
+            "displayName": "BTCe"
+        }
+    },
+    "dexs": {
+        "rrrrr": {
+            "displayName": "Hyena"
+        }
+    }
+}

package/lib/meta/metadata.ts

@@ -1,13 +1,27 @@
 import {
   HttpTransport,
   InfoClient,
-  PerpDex,
   PerpsAssetCtx,
   PerpsMeta,
   SpotMeta,
   SpotToken,
 } from "@nktkas/hyperliquid";
 import { isHip3Symbol } from "../hip3/utils";
+import { Hex } from "@nktkas/hyperliquid/script/src/types/mod";
+
+export interface PerpDex {
+  /** Short name of the perpetual dex. */
+  name: string;
+  /** Complete name of the perpetual dex. */
+  fullName: string;
+  /** Hex address of the dex deployer. */
+  deployer: Hex;
+  /** Hex address of the oracle updater, or null if not available. */
+  oracleUpdater: Hex | null;
+
+  feeRecipient: Hex | null;
+  assetToStreamingOiCap: [string, string][];
+}
 
 /**
  * Market information for trading operations
@@ -19,6 +33,9 @@ export interface MarketInfo {
   type: "perps" | "spot" | "hip3";
   coin: string; // Format used in info endpoint (e.g., "@107") for spot hype, "HYPE" for perps, "dex:coin" for hip3
 
+  displayName?: string; // Display name for the market
+  imageUrl?: string; // Image URL for the market
+
   maxLeverage?: number; // For perps only
 
   // Spot-specific fields
@@ -28,6 +45,8 @@ export interface MarketInfo {
   // HIP-3 specific fields
   dexName?: string; // DEX name for HIP-3 markets
   dexIndex?: number; // DEX index for asset ID calculation
+  dexDisplayName?: string; // Display name override for the DEX
+  dexImageUrl?: string; // Image URL override for the DEX
 }
 
 export interface DexInfo {
@@ -37,6 +56,8 @@ export interface DexInfo {
   dexName: string; // DEX name for HIP-3 markets
   dexIndex: number; // DEX index for asset ID calculation
   collateralTokenSymbol: string;
+  displayName?: string; // Display name override for the DEX
+  imageUrl?: string; // Image URL override for the DEX
 }
 
 export type ExtendedPerpsMeta = PerpsMeta & {
@@ -54,6 +75,24 @@ export interface TokenInfo {
   tokenId: string;
 }
 
+/**
+ * Static metadata structure for display overrides
+ */
+interface StaticMetadata {
+  coins?: {
+    [symbol: string]: {
+      displayName?: string;
+      imageUrl?: string;
+    };
+  };
+  dexs?: {
+    [dexName: string]: {
+      displayName?: string;
+      imageUrl?: string;
+    };
+  };
+}
+
 /**
  * Configuration for MetadataClient
  */
@@ -84,6 +123,8 @@ interface MetadataClientConfig {
  * - Spot: 10000 + index
  * - HIP-3: 100000 + perp_dex_index * 10000 + index_in_meta
  */
+export const ROOT_DEX = "hyperliquid";
+
 export class MetadataClient {
   private infoClient: InfoClient;
   private config: MetadataClientConfig;
@@ -93,6 +134,7 @@ export class MetadataClient {
   private spotMeta: SpotMeta | null = null;
   private perpsMeta: PerpsMeta | null = null;
   private perpDexs: (PerpDex | null)[] = [];
+  private staticMeta: StaticMetadata | null = null;
 
   // HIP-3 metadata cache
   private hip3DexsMeta: Map<string, DexInfo> = new Map();
@@ -124,6 +166,7 @@ export class MetadataClient {
     this.infoClient = new InfoClient({ transport });
     this.config = {
       ...config,
+      hip3Dexs: config.hip3Dexs?.filter((dex) => dex !== ROOT_DEX),
       useStaticFallback: config.useStaticFallback ?? true,
     };
     this.isTestnet = config.isTestnet ?? false;
@@ -136,6 +179,9 @@ export class MetadataClient {
   async initialize(): Promise<void> {
     if (this.initialized) return;
 
+    // Always load staticMeta.json regardless of config.useStaticFallback
+    await this.loadStaticMetaOverrides();
+
     if (this.config.onlyUseStaticFallback) {
       await this.loadStaticMetadata();
       this.buildLookupMaps();
@@ -156,7 +202,7 @@ export class MetadataClient {
       [this.spotMeta, this.perpsMeta, this.perpDexs] = await Promise.all([
         this.infoClient.spotMeta(),
         this.infoClient.meta(),
-        this.infoClient.perpDexs(),
+        this.infoClient.perpDexs() as Promise<PerpDex[] | null[]>,
       ]);
 
       // Build optimized lookup maps
@@ -186,6 +232,24 @@ export class MetadataClient {
     }
   }
 
+  /**
+   * Load staticMeta.json for display overrides
+   * This is always loaded regardless of config.useStaticFallback
+   */
+  private async loadStaticMetaOverrides(): Promise<void> {
+    const network = this.isTestnet ? "testnet" : "mainnet";
+
+    try {
+      const staticMetaModule = await import(
+        `./data/${network}/staticMeta.json`
+      );
+      this.staticMeta = staticMetaModule.default as StaticMetadata;
+    } catch (error) {
+      console.warn(`Failed to load staticMeta.json for ${network}:`, error);
+      this.staticMeta = null;
+    }
+  }
+
   /**
    * Load static metadata from bundled JSON files
    */
@@ -194,16 +258,22 @@ export class MetadataClient {
 
     try {
       // Dynamic imports for static data
-      const [spotMetaModule, perpsMetaModule, perpDexsModule] =
-        await Promise.all([
-          import(`./data/${network}/spotMeta.json`),
-          import(`./data/${network}/meta.json`),
-          import(`./data/${network}/perpDexs.json`),
-        ]);
+      const [
+        spotMetaModule,
+        perpsMetaModule,
+        perpDexsModule,
+        staticMetaModule,
+      ] = await Promise.all([
+        import(`./data/${network}/spotMeta.json`),
+        import(`./data/${network}/meta.json`),
+        import(`./data/${network}/perpDexs.json`),
+        import(`./data/${network}/staticMeta.json`),
+      ]);
 
       this.spotMeta = spotMetaModule.default as SpotMeta;
       this.perpsMeta = perpsMetaModule.default as PerpsMeta;
       this.perpDexs = perpDexsModule.default as (PerpDex | null)[];
+      this.staticMeta = staticMetaModule.default as StaticMetadata;
 
       console.warn(`Using static ${network} metadata`);
     } catch (error) {
@@ -248,6 +318,17 @@ export class MetadataClient {
           maxLeverage: market.maxLeverage,
         };
 
+        // Apply static metadata overrides for perps
+        const staticOverrides = this.staticMeta?.coins?.[market.name];
+        if (staticOverrides) {
+          if (staticOverrides.displayName) {
+            marketInfo.displayName = staticOverrides.displayName;
+          }
+          if (staticOverrides.imageUrl) {
+            marketInfo.imageUrl = staticOverrides.imageUrl;
+          }
+        }
+
         // Case-insensitive lookup
         this.perpsSymbolToIndex.set(market.name.toUpperCase(), index);
 
@@ -288,6 +369,17 @@ export class MetadataClient {
           quoteToken: quoteToken,
         };
 
+        // Apply static metadata overrides for spot
+        const staticOverrides = this.staticMeta?.coins?.[coin];
+        if (staticOverrides) {
+          if (staticOverrides.displayName) {
+            marketInfo.displayName = staticOverrides.displayName;
+          }
+          if (staticOverrides.imageUrl) {
+            marketInfo.imageUrl = staticOverrides.imageUrl;
+          }
+        }
+
         // Store by full pair (case-insensitive)
         const pairKey = `${baseToken.name}/${quoteToken.name}`.toUpperCase();
         this.spotPairToMarket.set(pairKey, marketInfo);
@@ -347,15 +439,26 @@ export class MetadataClient {
       const collateralTokenSymbol =
         spotMetaTokens?.[collateralTokenIndex]?.name ?? "USDC";
 
-      const dexInfo = {
+      const dexInfo: DexInfo = {
         meta,
         assetContext: contexts,
         collateralTokenSymbol,
-        dexFullName: dex?.full_name ?? dexName,
+        dexFullName: dex?.fullName ?? dexName,
         dexName: dex?.name ?? dexName,
         dexIndex: dexIndex,
       };
 
+      // Apply static metadata overrides for DEX
+      const staticDexOverrides = this.staticMeta?.dexs?.[dexName];
+      if (staticDexOverrides) {
+        if (staticDexOverrides.displayName) {
+          dexInfo.displayName = staticDexOverrides.displayName;
+        }
+        if (staticDexOverrides.imageUrl) {
+          dexInfo.imageUrl = staticDexOverrides.imageUrl;
+        }
+      }
+
       this.hip3DexsMeta.set(dexName, dexInfo);
 
       // Build HIP-3 market lookups for this DEX
@@ -374,6 +477,7 @@ export class MetadataClient {
   private buildHip3MarketsForDex(dexName: string, dexInfo: DexInfo): void {
     dexInfo.meta.universe.forEach((market, index) => {
       const symbol = market.name;
+
       const marketInfo: MarketInfo = {
         coin: symbol,
         symbol,
@@ -383,8 +487,21 @@ export class MetadataClient {
         maxLeverage: market.maxLeverage,
         dexName,
         dexIndex: dexInfo.dexIndex,
+        dexDisplayName: dexInfo.displayName,
+        dexImageUrl: dexInfo.imageUrl,
       };
 
+      // Apply static metadata overrides for HIP-3
+      const staticOverrides = this.staticMeta?.coins?.[symbol];
+      if (staticOverrides) {
+        if (staticOverrides.displayName) {
+          marketInfo.displayName = staticOverrides.displayName;
+        }
+        if (staticOverrides.imageUrl) {
+          marketInfo.imageUrl = staticOverrides.imageUrl;
+        }
+      }
+
       this.coinToMarket.set(symbol, marketInfo);
       this.hip3SymbolToMarket.set(symbol, marketInfo);
     });
@@ -425,7 +542,7 @@ export class MetadataClient {
     // If no "/" in symbol, it could be perps or need quote asset
     if (!symbol.includes("/") && !symbol.includes("@")) {
       // Try perps lookup first (O(1))
-      const perpsMarket = this.coinToMarket.get(lookupKey);
+      const perpsMarket = this.coinToMarket.get(symbol);
       if (perpsMarket?.type === "perps") {
         return perpsMarket;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basedone/core",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Core utilities for Based One",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",