feat(perps-controller): integrate Terminal API for market metadata with HyperLiquid fallback

packages/perps-controller/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add Terminal API integration for market data, controlled via `useTerminalApi` parameter on `GetMarketsParams` / `GetMarketDataWithPricesParams` ([#9137](https://github.com/MetaMask/core/pull/9137))
+  - `TerminalMarketService` fetches structured market metadata from the injected `terminalApiUrl` with a 5-minute cache TTL.
+  - When enabled, `getMarkets()` attempts the Terminal API first; on failure or empty response, falls back silently to HyperLiquid. Terminal results respect the same allowlist/blocklist filtering as the provider path.
+  - `getMarketDataWithPrices()` enriches provider data with Terminal API metadata (name, keywords, tags, categories).
+  - `PerpsPlatformDependencies` gains an optional `terminalApiUrl?: string` field and an optional `terminalMarketService?: PerpsTerminalMarketService` field; clients can inject a pre-built service instance or let the controller create one from the URL.
+  - `PerpsMarketData` gains optional `keywords`, `tags`, and `categories` fields.
+  - Market search (`getMarketMatchRank`, `rankMarketsByQuery`) now indexes the `keywords` field for richer search results.
+  - `HYPERLIQUID_ASSET_NAMES` and `HIP3_ASSET_MARKET_TYPES` remain intact as fallback for assets absent from the Terminal API.
+
+### Changed
+
+- Replace unsafe `as` type cast with runtime schema validation (`@metamask/superstruct`) in `TerminalMarketService` ([#9137](https://github.com/MetaMask/core/pull/9137))
+  - Each item in the Terminal API response is now individually validated; items that fail validation are filtered out and logged instead of silently accepted.
+
 ## [8.2.0]
 
 ### Added

packages/perps-controller/package.json

@@ -100,6 +100,7 @@
     "@metamask/base-controller": "^9.1.0",
     "@metamask/controller-utils": "^12.2.0",
     "@metamask/messenger": "^1.2.0",
+    "@metamask/superstruct": "^3.1.0",
     "@metamask/utils": "^11.11.0",
     "@nktkas/hyperliquid": "^0.32.2",
     "bignumber.js": "^9.1.2",

packages/perps-controller/src/PerpsController.ts

@@ -38,6 +38,7 @@ import { FeatureFlagConfigurationService } from './services/FeatureFlagConfigura
 import { MarketDataService } from './services/MarketDataService';
 import { RewardsIntegrationService } from './services/RewardsIntegrationService';
 import type { ServiceContext } from './services/ServiceContext';
+import { TerminalMarketService } from './services/TerminalMarketService';
 import { TradingService } from './services/TradingService';
 // PerpsStreamChannelKey removed: using string for channel keys (PerpsStreamManager.pauseChannel takes string)
 import {
@@ -126,6 +127,9 @@ import {
 } from './types/transactionTypes';
 import { getSelectedEvmAccountFromMessenger } from './utils/accountUtils';
 import { ensureError } from './utils/errorUtils';
+import { parseAssetName } from './utils/hyperLiquidAdapter';
+import { compileMarketPattern, shouldIncludeMarket } from './utils/marketUtils';
+import type { CompiledMarketPattern } from './utils/marketUtils';
 import {
   hydrateFromDiskSync,
   persistMarketEntriesToDisk,
@@ -950,7 +954,14 @@ export class PerpsController extends BaseController<
     // Instantiate services with platform dependencies
     // Services that need cross-controller access receive the messenger
     this.#tradingService = new TradingService(infrastructure);
-    this.#marketDataService = new MarketDataService(infrastructure);
+    this.#marketDataService = new MarketDataService({
+      ...infrastructure,
+      terminalMarketService:
+        infrastructure.terminalMarketService ??
+        (infrastructure.terminalApiUrl
+          ? new TerminalMarketService(infrastructure)
+          : undefined),
+    });
     this.#accountService = new AccountService(infrastructure, messenger);
     this.#eligibilityService = new EligibilityService(infrastructure);
     this.#dataLakeService = new DataLakeService(infrastructure, messenger);
@@ -1905,6 +1916,50 @@ export class PerpsController extends BaseController<
     return this.state as unknown as PerpsControllerState;
   }
 
+  /**
+   * Build a filter function that mirrors the provider's allowlist/blocklist
+   * logic so that Terminal API results are filtered identically.
+   *
+   * @returns Filter predicate accepting a market symbol.
+   */
+  #buildMarketAllowedFilter(): (symbol: string) => boolean {
+    const hip3Enabled = this.#hip3Enabled;
+    const compiledAllowlist = this.#compilePatternsSafely(
+      this.#hip3AllowlistMarkets,
+    );
+    const compiledBlocklist = this.#compilePatternsSafely(
+      this.#hip3BlocklistMarkets,
+    );
+    return (symbol: string) => {
+      const { dex } = parseAssetName(symbol);
+      return shouldIncludeMarket(
+        symbol,
+        dex,
+        hip3Enabled,
+        compiledAllowlist,
+        compiledBlocklist,
+      );
+    };
+  }
+
+  /**
+   * Compile market patterns safely, skipping any that fail validation.
+   *
+   * @param patterns - Raw pattern strings from config.
+   * @returns Compiled patterns (invalid entries silently skipped).
+   */
+  #compilePatternsSafely(patterns: string[]): CompiledMarketPattern[] {
+    const compiled: CompiledMarketPattern[] = [];
+    for (const pattern of patterns) {
+      try {
+        compiled.push({ pattern, matcher: compileMarketPattern(pattern) });
+      } catch {
+        // Invalid patterns silently skipped — logged at provider level.
+      }
+    }
+    return compiled;
+  }
+
   /**
    * Create a ServiceContext for dependency injection into services
    * Provides all orchestration dependencies (tracing, analytics, state management)
@@ -2917,21 +2972,24 @@ export class PerpsController extends BaseController<
    * @returns Array of available markets matching the filter criteria.
    */
   async getMarkets(params?: GetMarketsParams): Promise<MarketInfo[]> {
-    // For standalone mode, access provider directly without initialization check
-    // This allows discovery use cases (checking if market exists) without full perps setup
+    const isMarketAllowed = this.#buildMarketAllowedFilter();
     if (params?.standalone) {
-      // Use activeProviderInstance if available (respects provider abstraction)
-      // Fallback to cached standalone provider for pre-initialization discovery
       const provider =
         this.activeProviderInstance ?? this.#getOrCreateStandaloneProvider();
-      return provider.getMarkets(params);
+      return this.#marketDataService.getMarkets({
+        provider,
+        params,
+        context: this.#createServiceContext('getMarkets'),
+        isMarketAllowed,
+      });
     }
 
     const provider = this.getActiveProvider();
     return this.#marketDataService.getMarkets({
       provider,
       params,
       context: this.#createServiceContext('getMarkets'),
+      isMarketAllowed,
     });
   }
 
@@ -2954,8 +3012,6 @@ export class PerpsController extends BaseController<
     params?: GetMarketDataWithPricesParams,
   ): Promise<PerpsMarketData[]> {
     if (params?.standalone) {
-      // Use activeProviderInstance if available (respects provider abstraction)
-      // Fallback to cached standalone provider for pre-initialization discovery
       const provider =
         this.activeProviderInstance ?? this.#getOrCreateStandaloneProvider();
       return this.#marketDataService.getMarketDataWithPrices({

packages/perps-controller/src/constants/perpsConfig.ts

@@ -328,6 +328,16 @@ export const DATA_LAKE_API_CONFIG = {
   OrdersEndpoint: 'https://perps.api.cx.metamask.io/api/v1/orders',
 } as const;
 
+/**
+ * Terminal API configuration.
+ * The full endpoint URL is injected at runtime via
+ * `PerpsPlatformDependencies.terminalApiUrl` from each client build
+ * (dev/uat/prd); only cache settings live here.
+ */
+export const TERMINAL_API_CONFIG = {
+  CacheTtlMs: 5 * 60 * 1000, // 5 minutes
+} as const;
+
 /**
  * Decimal precision configuration
  * Controls maximum decimal places for price and input validation

packages/perps-controller/src/index.ts

@@ -244,6 +244,8 @@ export type {
   PerpsInternalAccount,
   PerpsRemoteFeatureFlagState,
   PerpsPlatformDependencies,
+  PerpsTerminalMarketService,
+  TerminalAssetMetadata,
   PerpsCacheType,
   InvalidateCacheParams,
   PerpsCacheInvalidator,

packages/perps-controller/src/services/MarketDataService.ts

@@ -32,6 +32,7 @@ import type {
   AssetRoute,
   PerpsPlatformDependencies,
   PerpsMarketData,
+  TerminalAssetMetadata,
 } from '../types';
 import type { CandleData } from '../types/perps-types';
 import { coalescePerpsRestRequest } from '../utils/coalescePerpsRestRequest';
@@ -711,20 +712,28 @@ export class MarketDataService {
 
   /**
    * Get available markets
-   * Handles full orchestration: tracing, error logging, state management, and provider delegation
+   * Handles full orchestration: tracing, error logging, state management, and provider delegation.
+   * When `useTerminalApi` is true, attempts the Terminal API first; on failure or empty
+   * response, falls back silently to the HyperLiquid provider path.
    *
    * @param options - The configuration options.
    * @param options.provider - The perps provider instance.
    * @param options.params - The operation parameters.
    * @param options.context - The service context for dependencies.
+   * @param options.isMarketAllowed - Optional filter callback applied to
+   * Terminal API results so that allowlist/blocklist rules from the provider
+   * layer are enforced even when the provider is bypassed. Skipped when
+   * `params.skipFilters` is true.
    * @returns The result of the operation.
    */
   async getMarkets(options: {
     provider: PerpsProvider;
     params?: GetMarketsParams;
     context: ServiceContext;
+    isMarketAllowed?: (symbol: string) => boolean;
   }): Promise<MarketInfo[]> {
-    const { provider, params, context } = options;
+    const { provider, params, context, isMarketAllowed } = options;
+    const useTerminalApi = params?.useTerminalApi;
     const traceId = uuidv4();
     let traceData: { success: boolean; error?: string } | undefined;
 
@@ -740,12 +749,65 @@ export class MarketDataService {
             symbolCount: String(params.symbols.length),
           }),
           ...(params?.dex !== undefined && { dex: params.dex }),
+          ...(useTerminalApi !== undefined && {
+            useTerminalApi: String(useTerminalApi),
+          }),
         },
       });
 
+      // Terminal API path: attempt first when flag is enabled
+      if (useTerminalApi && this.#deps.terminalMarketService) {
+        try {
+          const { markets: terminalMarkets } =
+            await this.#deps.terminalMarketService.fetchMarkets();
+          if (terminalMarkets.length > 0) {
+            let filtered = terminalMarkets;
+
+            // Apply allowlist/blocklist filtering (same as provider path)
+            if (!params?.skipFilters && isMarketAllowed) {
+              filtered = filtered.filter((market) =>
+                isMarketAllowed(market.name),
+              );
+            }
+
+            // Filter by specific DEX when requested
+            if (params?.dex !== undefined) {
+              const dexPrefix = params.dex ? `${params.dex}:` : '';
+              filtered = filtered.filter((market) =>
+                dexPrefix
+                  ? market.name.startsWith(dexPrefix)
+                  : !market.name.includes(':'),
+              );
+            }
+
+            // Filter by symbols when requested
+            if (params?.symbols?.length) {
+              filtered = filtered.filter((market) =>
+                (params.symbols as string[]).some(
+                  (sym) => market.name.toLowerCase() === sym.toLowerCase(),
+                ),
+              );
+            }
+
+            if (context.stateManager) {
+              context.stateManager.update((state) => {
+                state.lastError = null;
+                state.lastUpdateTimestamp = Date.now();
+              });
+            }
+            traceData = { success: true };
+            return filtered;
+          }
+        } catch (terminalError) {
+          this.#deps.terminalMarketService.logError(
+            terminalError,
+            'getMarkets',
+          );
+        }
+      }
+
       const markets = await provider.getMarkets(params);
 
-      // Clear any previous errors on successful call (if stateManager is provided)
       if (context.stateManager) {
         context.stateManager.update((state) => {
           state.lastError = null;
@@ -779,7 +841,6 @@ export class MarketDataService {
         },
       );
 
-      // Update error state (if stateManager is provided)
       if (context.stateManager) {
         context.stateManager.update((state) => {
           state.lastError = errorMessage;
@@ -805,6 +866,8 @@ export class MarketDataService {
   /**
    * Get market data with prices (includes price, volume, 24h change).
    * Applies optional category filtering, sorting, and limit after fetching.
+   * When `useTerminalApi` is true, enriches provider data with Terminal API metadata
+   * (name, keywords, tags, categories). On Terminal API failure, falls back silently.
    *
    * @param options - The configuration options.
    * @param options.provider - The perps provider instance.
@@ -818,6 +881,7 @@ export class MarketDataService {
     context: ServiceContext;
   }): Promise<PerpsMarketData[]> {
     const { provider, params, context } = options;
+    const useTerminalApi = params?.useTerminalApi;
     const traceId = uuidv4();
     let traceData: { success: boolean; error?: string } | undefined;
 
@@ -832,11 +896,38 @@ export class MarketDataService {
           ...(params?.categories && {
             categoryCount: String(params.categories.length),
           }),
+          ...(useTerminalApi !== undefined && {
+            useTerminalApi: String(useTerminalApi),
+          }),
         },
       });
 
+      // Fetch Terminal API metadata before provider data when enabled.
+      // Terminal metadata enriches the provider result (name, keywords, tags,
+      // categories) but never replaces live pricing / funding data.
+      let terminalMetadata: Map<string, TerminalAssetMetadata> | undefined;
+      if (useTerminalApi && this.#deps.terminalMarketService) {
+        try {
+          const result = await this.#deps.terminalMarketService.fetchMarkets();
+          if (result.metadata.size > 0) {
+            terminalMetadata = result.metadata;
+          }
+        } catch (terminalError) {
+          this.#deps.terminalMarketService.logError(
+            terminalError,
+            'getMarketDataWithPrices',
+          );
+        }
+      }
+
       const markets = await provider.getMarketDataWithPrices();
-      const filtered = applyMarketFilters(markets, params);
+
+      // Enrich with terminal metadata when available
+      const enriched = terminalMetadata
+        ? this.#enrichWithTerminalMetadata(markets, terminalMetadata)
+        : markets;
+
+      const filtered = applyMarketFilters(enriched, params);
 
       traceData = { success: true };
       return filtered;
@@ -1252,4 +1343,35 @@ export class MarketDataService {
     const { provider, address } = options;
     return provider.getBlockExplorerUrl(address);
   }
+
+  /**
+   * Merge Terminal API metadata into provider-sourced PerpsMarketData.
+   * For each market, if the terminal metadata map contains an entry for its
+   * symbol, override name/marketType and attach keywords/tags/categories.
+   * Unmatched markets keep their provider-sourced values.
+   *
+   * @param markets - Markets from the provider.
+   * @param metadata - Per-symbol metadata from the Terminal API.
+   * @returns Enriched market data array.
+   */
+  #enrichWithTerminalMetadata(
+    markets: PerpsMarketData[],
+    metadata: Map<string, TerminalAssetMetadata>,
+  ): PerpsMarketData[] {
+    return markets.map((market) => {
+      const meta = metadata.get(market.symbol);
+      if (!meta) {
+        return market;
+      }
+
+      return {
+        ...market,
+        name: meta.name,
+        ...(meta.marketType !== undefined && { marketType: meta.marketType }),
+        ...(meta.keywords !== undefined && { keywords: meta.keywords }),
+        ...(meta.tags !== undefined && { tags: meta.tags }),
+        ...(meta.categories !== undefined && { categories: meta.categories }),
+      };
+    });
+  }
 }