feat(assets-controllers): add searchTokens function

[salimtb]

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

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed, highlighting breaking changes as necessary
• I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes

---

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.

^{Written by Cursor Bugbot for commit bf6224c. This will update automatically on new commits. Configure here.}

[juanmigdr]

Do we need to send this over? Could we minimize the data we return to the UI?

[juanmigdr]

I meant aggregators

[salimtb]

This is required since it’s also part of the tokenList state. However, it’s not actually used in the UI , I just wanted to keep it consistent with the existing tokenList state structure.