feat(assets-controllers): add searchTokens function (#7004)

## Explanation

**What is the current state of things and why does it need to change?**

Currently, the assets-controllers package provides functionality to
fetch token lists and metadata for individual networks, but lacks the
ability to search for tokens across multiple blockchain networks
simultaneously. Users and applications need to search for tokens by
name, symbol, or address across different chains (Ethereum, Polygon,
Solana, etc.) in a unified way, which requires multiple separate API
calls with the existing implementation.

**What is the solution your changes offer and how does it work?**

This PR introduces a new `searchTokens` function that enables
cross-chain token search functionality using CAIP (Chain Agnostic
Improvement Proposal) format chain IDs. The solution includes:

1. **New `searchTokens` function**: Accepts an array of CAIP chain IDs
(e.g., `['eip155:1', 'eip155:137',
'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp']`) and a search query string
2. **URL construction helper**: `getTokenSearchURL` function that
properly encodes chain IDs and query parameters
3. **Structured response**: Returns `{ count: number, data: unknown[] }`
format for consistent API responses
4. **Error handling**: Gracefully handles API failures by returning
empty results instead of throwing errors
5. **Configurable limits**: Supports customizable result limits
(default: 10)

The function makes a single API call to the `/tokens/search` endpoint,
making it more efficient than multiple individual network searches.

**Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?**

- **CAIP format requirement**: The function specifically requires CAIP
format chain IDs rather than hex chain IDs to support multi-chain
protocols including non-EVM chains like Solana
- **Error handling strategy**: The function returns `{ count: 0, data:
[] }` on errors rather than throwing, which prevents search failures
from breaking the user experience
- **Response normalization**: The function handles both new API response
format (object with count/data) and legacy format (direct array) for
backwards compatibility

## References

* Implements search token service functionality for cross-chain token
discovery
* Related to MetaMask's multi-chain token support initiative

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs),
highlighting breaking changes as necessary
- [ ] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Introduces `searchTokens` to query tokens across multiple networks
using CAIP chain IDs, exports it, and adds comprehensive tests and
changelog entry.
> 
> - **Token service (`src/token-service.ts`)**:
> - Add `searchTokens(chainIds: CaipChainId[], query, { limit })` using
`/tokens/search` and `handleFetch`; returns `{ count, data }` with
graceful error handling.
> - Add helper `getTokenSearchURL` and CAIP chain ID support; import
`CaipChainId`.
> - **Exports**:
>   - Export `searchTokens` from `src/index.ts`.
> - **Tests (`src/token-service.test.ts`)**:
> - Add coverage for single/multi-chain searches, custom `limit`, query
encoding, empty/invalid responses, and network/HTTP errors.
> - **Changelog**:
> - Document addition of `searchTokens` for multi-network searches via
CAIP IDs.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
bf6224c. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: salimtb

packages/assets-controllers/CHANGELOG.md

@@ -25,6 +25,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `fetchExchangeRates` function to fetch exchange rates from price-api ([#6863](https://github.com/MetaMask/core/pull/6863))
 - Added `ignoreAssets` to allow ignoring assets for non-EVM chains ([#6981](https://github.com/MetaMask/core/pull/6981))
 
+- Added `searchTokens` function to search for tokens across multiple networks using CAIP format chain IDs ([#7004](https://github.com/MetaMask/core/pull/7004))
+
 ### Changed
 
 - Bump `@metamask/controller-utils` from `^11.14.1` to `^11.15.0` ([#7003](https://github.com/MetaMask/core/pull/7003))

packages/assets-controllers/src/index.ts

@@ -142,6 +142,7 @@ export {
   SUPPORTED_CHAIN_IDS,
   getNativeTokenAddress,
 } from './token-prices-service';
+export { searchTokens } from './token-service';
 export { RatesController, Cryptocurrency } from './RatesController';
 export type {
   RatesControllerState,

packages/assets-controllers/src/token-service.test.ts

@@ -1,9 +1,11 @@
 import { toHex } from '@metamask/controller-utils';
+import type { CaipChainId } from '@metamask/utils';
 import nock from 'nock';
 
 import {
   fetchTokenListByChainId,
   fetchTokenMetadata,
+  searchTokens,
   TOKEN_END_POINT_API,
   TOKEN_METADATA_NO_SUPPORT_ERROR,
 } from './token-service';
@@ -234,8 +236,54 @@ const sampleToken = {
   name: 'Chainlink',
 };
 
+const sampleSearchResults = [
+  {
+    address: '0xa0b86a33e6c166428cf041c73490a6b448b7f2c2',
+    symbol: 'USDC',
+    decimals: 6,
+    name: 'USD Coin',
+    occurrences: 12,
+    aggregators: [
+      'paraswap',
+      'pmm',
+      'airswapLight',
+      'zeroEx',
+      'bancor',
+      'coinGecko',
+      'zapper',
+      'kleros',
+      'zerion',
+      'cmc',
+      'oneInch',
+      'uniswap',
+    ],
+  },
+  {
+    address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
+    symbol: 'USDT',
+    decimals: 6,
+    name: 'Tether USD',
+    occurrences: 11,
+    aggregators: [
+      'paraswap',
+      'pmm',
+      'airswapLight',
+      'zeroEx',
+      'bancor',
+      'coinGecko',
+      'zapper',
+      'kleros',
+      'zerion',
+      'cmc',
+      'oneInch',
+    ],
+  },
+];
+
 const sampleDecimalChainId = 1;
 const sampleChainId = toHex(sampleDecimalChainId);
+const sampleCaipChainId: CaipChainId = 'eip155:1';
+const polygonCaipChainId: CaipChainId = 'eip155:137';
 
 describe('Token service', () => {
   describe('fetchTokenListByChainId', () => {
@@ -437,4 +485,228 @@ describe('Token service', () => {
       ).rejects.toThrow(TOKEN_METADATA_NO_SUPPORT_ERROR);
     });
   });
+
+  describe('searchTokens', () => {
+    it('should call the search api and return the list of matching tokens for single chain', async () => {
+      const searchQuery = 'USD';
+      const mockResponse = {
+        count: sampleSearchResults.length,
+        data: sampleSearchResults,
+        pageInfo: { hasNextPage: false, endCursor: null },
+      };
+
+      nock(TOKEN_END_POINT_API)
+        .get(
+          `/tokens/search?chainIds=${encodeURIComponent(sampleCaipChainId)}&query=${searchQuery}&limit=10`,
+        )
+        .reply(200, mockResponse)
+        .persist();
+
+      const results = await searchTokens([sampleCaipChainId], searchQuery);
+
+      expect(results).toStrictEqual({
+        count: sampleSearchResults.length,
+        data: sampleSearchResults,
+      });
+    });
+
+    it('should call the search api with custom limit parameter', async () => {
+      const searchQuery = 'USDC';
+      const customLimit = 5;
+      const mockResponse = {
+        count: 1,
+        data: [sampleSearchResults[0]],
+        pageInfo: { hasNextPage: false, endCursor: null },
+      };
+
+      nock(TOKEN_END_POINT_API)
+        .get(
+          `/tokens/search?chainIds=${encodeURIComponent(sampleCaipChainId)}&query=${searchQuery}&limit=${customLimit}`,
+        )
+        .reply(200, mockResponse)
+        .persist();
+
+      const results = await searchTokens([sampleCaipChainId], searchQuery, {
+        limit: customLimit,
+      });
+
+      expect(results).toStrictEqual({
+        count: 1,
+        data: [sampleSearchResults[0]],
+      });
+    });
+
+    it('should properly encode search queries with special characters', async () => {
+      const searchQuery = 'USD Coin & Token';
+      const encodedQuery = 'USD%20Coin%20%26%20Token';
+      const mockResponse = {
+        count: sampleSearchResults.length,
+        data: sampleSearchResults,
+        pageInfo: { hasNextPage: false, endCursor: null },
+      };
+
+      nock(TOKEN_END_POINT_API)
+        .get(
+          `/tokens/search?chainIds=${encodeURIComponent(sampleCaipChainId)}&query=${encodedQuery}&limit=10`,
+        )
+        .reply(200, mockResponse)
+        .persist();
+
+      const results = await searchTokens([sampleCaipChainId], searchQuery);
+
+      expect(results).toStrictEqual({
+        count: sampleSearchResults.length,
+        data: sampleSearchResults,
+      });
+    });
+
+    it('should search across multiple chains in a single request', async () => {
+      const searchQuery = 'USD';
+      const encodedChainIds = [sampleCaipChainId, polygonCaipChainId]
+        .map((id) => encodeURIComponent(id))
+        .join(',');
+      const mockResponse = {
+        count: sampleSearchResults.length,
+        data: sampleSearchResults,
+        pageInfo: { hasNextPage: false, endCursor: null },
+      };
+
+      nock(TOKEN_END_POINT_API)
+        .get(
+          `/tokens/search?chainIds=${encodedChainIds}&query=${searchQuery}&limit=10`,
+        )
+        .reply(200, mockResponse)
+        .persist();
+
+      const results = await searchTokens(
+        [sampleCaipChainId, polygonCaipChainId],
+        searchQuery,
+      );
+
+      expect(results).toStrictEqual({
+        count: sampleSearchResults.length,
+        data: sampleSearchResults,
+      });
+    });
+
+    it('should return empty array if the fetch fails with a network error', async () => {
+      const searchQuery = 'USD';
+      nock(TOKEN_END_POINT_API)
+        .get(
+          `/tokens/search?chainIds=${encodeURIComponent(sampleCaipChainId)}&query=${searchQuery}&limit=10`,
+        )
+        .replyWithError('Example network error')
+        .persist();
+
+      const result = await searchTokens([sampleCaipChainId], searchQuery);
+
+      expect(result).toStrictEqual({ count: 0, data: [] });
+    });
+
+    it('should return empty array if the fetch fails with 400 error', async () => {
+      const searchQuery = 'USD';
+      nock(TOKEN_END_POINT_API)
+        .get(
+          `/tokens/search?chainIds=${encodeURIComponent(sampleCaipChainId)}&query=${searchQuery}&limit=10`,
+        )
+        .reply(400, { error: 'Bad Request' })
+        .persist();
+
+      const result = await searchTokens([sampleCaipChainId], searchQuery);
+
+      expect(result).toStrictEqual({ count: 0, data: [] });
+    });
+
+    it('should return empty array if the fetch fails with 500 error', async () => {
+      const searchQuery = 'USD';
+      nock(TOKEN_END_POINT_API)
+        .get(
+          `/tokens/search?chainIds=${encodeURIComponent(sampleCaipChainId)}&query=${searchQuery}&limit=10`,
+        )
+        .reply(500)
+        .persist();
+
+      const result = await searchTokens([sampleCaipChainId], searchQuery);
+
+      expect(result).toStrictEqual({ count: 0, data: [] });
+    });
+
+    it('should handle empty search results', async () => {
+      const searchQuery = 'NONEXISTENT';
+      const mockResponse = {
+        count: 0,
+        data: [],
+        pageInfo: { hasNextPage: false, endCursor: null },
+      };
+
+      nock(TOKEN_END_POINT_API)
+        .get(
+          `/tokens/search?chainIds=${encodeURIComponent(sampleCaipChainId)}&query=${searchQuery}&limit=10`,
+        )
+        .reply(200, mockResponse)
+        .persist();
+
+      const results = await searchTokens([sampleCaipChainId], searchQuery);
+
+      expect(results).toStrictEqual({ count: 0, data: [] });
+    });
+
+    it('should return empty array when no chainIds are provided', async () => {
+      const searchQuery = 'USD';
+      const results = await searchTokens([], searchQuery);
+
+      expect(results).toStrictEqual({ count: 0, data: [] });
+    });
+
+    it('should handle API error responses in JSON format', async () => {
+      const searchQuery = 'USD';
+      const errorResponse = { error: 'Invalid search query' };
+      nock(TOKEN_END_POINT_API)
+        .get(
+          `/tokens/search?chainIds=${encodeURIComponent(sampleCaipChainId)}&query=${searchQuery}&limit=10`,
+        )
+        .reply(200, errorResponse)
+        .persist();
+
+      const result = await searchTokens([sampleCaipChainId], searchQuery);
+
+      // Non-array responses should be converted to empty object with count 0
+      expect(result).toStrictEqual({ count: 0, data: [] });
+    });
+
+    it('should handle supported CAIP format chain IDs', async () => {
+      const searchQuery = 'USD';
+      const solanaChainId: CaipChainId =
+        'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
+      const tronChainId: CaipChainId = 'tron:728126428';
+
+      const multiChainIds: CaipChainId[] = [
+        sampleCaipChainId,
+        solanaChainId,
+        tronChainId,
+      ];
+      const encodedChainIds = multiChainIds
+        .map((id) => encodeURIComponent(id))
+        .join(',');
+      const mockResponse = {
+        count: sampleSearchResults.length,
+        data: sampleSearchResults,
+        pageInfo: { hasNextPage: false, endCursor: null },
+      };
+
+      nock(TOKEN_END_POINT_API)
+        .get(
+          `/tokens/search?chainIds=${encodedChainIds}&query=${searchQuery}&limit=10`,
+        )
+        .reply(200, mockResponse)
+        .persist();
+
+      const result = await searchTokens(multiChainIds, searchQuery);
+
+      expect(result).toStrictEqual({
+        count: sampleSearchResults.length,
+        data: sampleSearchResults,
+      });
+    });
+  });
 });

packages/assets-controllers/src/token-service.ts

@@ -1,9 +1,10 @@
 import {
   ChainId,
   convertHexToDecimal,
+  handleFetch,
   timeoutFetch,
 } from '@metamask/controller-utils';
-import type { Hex } from '@metamask/utils';
+import type { CaipChainId, Hex } from '@metamask/utils';
 
 import { isTokenListSupportedForNetwork } from './assetsUtil';
 
@@ -41,6 +42,22 @@ function getTokenMetadataURL(chainId: Hex, tokenAddress: string) {
   )}?address=${tokenAddress}`;
 }
 
+/**
+ * Get the token search URL for the given networks and search query.
+ *
+ * @param chainIds - Array of CAIP format chain IDs (e.g., 'eip155:1', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp').
+ * @param query - The search query (token name, symbol, or address).
+ * @param limit - Optional limit for the number of results (defaults to 10).
+ * @returns The token search URL.
+ */
+function getTokenSearchURL(chainIds: CaipChainId[], query: string, limit = 10) {
+  const encodedQuery = encodeURIComponent(query);
+  const encodedChainIds = chainIds
+    .map((id) => encodeURIComponent(id))
+    .join(',');
+  return `${TOKEN_END_POINT_API}/tokens/search?chainIds=${encodedChainIds}&query=${encodedQuery}&limit=${limit}`;
+}
+
 const tenSecondsInMilliseconds = 10_000;
 
 // Token list averages 1.6 MB in size
@@ -77,6 +94,46 @@ export async function fetchTokenListByChainId(
   return undefined;
 }
 
+/**
+ * Search for tokens across one or more networks by query string using CAIP format chain IDs.
+ *
+ * @param chainIds - Array of CAIP format chain IDs (e.g., ['eip155:1', 'eip155:137', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp']).
+ * @param query - The search query (token name, symbol, or address).
+ * @param options - Additional fetch options.
+ * @param options.limit - The maximum number of results to return.
+ * @returns Object containing count and data array. Returns { count: 0, data: [] } if request fails.
+ */
+export async function searchTokens(
+  chainIds: CaipChainId[],
+  query: string,
+  { limit = 10 } = {},
+): Promise<{ count: number; data: unknown[] }> {
+  if (chainIds.length === 0) {
+    return { count: 0, data: [] };
+  }
+
+  const tokenSearchURL = getTokenSearchURL(chainIds, query, limit);
+
+  try {
+    const result = await handleFetch(tokenSearchURL);
+
+    // The API returns an object with structure: { count: number, data: array, pageInfo: object }
+    if (result && typeof result === 'object' && Array.isArray(result.data)) {
+      return {
+        count: result.count || result.data.length,
+        data: result.data,
+      };
+    }
+
+    // Handle non-expected responses
+    return { count: 0, data: [] };
+  } catch (error) {
+    // Handle 400 errors and other failures by returning count 0 and empty array
+    console.log('Search request failed:', error);
+    return { count: 0, data: [] };
+  }
+}
+
 /**
  * Fetch metadata for the token address provided for a given network. This request is cancellable
  * using the abort signal passed in.