> ## Documentation Index > Fetch the complete documentation index at: https://docs.sim.dune.com/llms.txt > Use this file to discover all available pages before exploring further. # Search Tokens > Search ERC20 tokens across supported EVM chains by symbol or name, with optional chain filters. Results are enriched with logo and decimals. The Search Tokens API lets you find ERC20 tokens by name or symbol across one or more supported EVM chains. Results are ranked by an internal score (where available) and returned with their canonical chain, address, symbol, name, `logo`, and `decimals` so they can be rendered immediately. Use it to power token-pickers, autocomplete inputs, and any UI flow where the user knows part of a token's name or symbol but not its contract address. ## Example Request ```bash theme={null} curl -X GET "https://api.sim.dune.com/v1/evm/search/tokens?query=USDC&chain_ids=1,8453&limit=5" \ -H "X-Sim-Api-Key: YOUR_API_KEY" ``` ```json Response (JSON) [expandable] theme={null} [ { "chain_id": 1, "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "token_type": "ERC20", "symbol": "USDC", "name": "USD Coin", "logo": "https://api.sim.dune.com/beta/token/logo/1/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "decimals": 6 }, { "chain_id": 8453, "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "token_type": "ERC20", "symbol": "USDC", "name": "USD Coin", "logo": "https://api.sim.dune.com/beta/token/logo/8453/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "decimals": 6 } ] ``` ## Query Parameters | Parameter | Type | Required | Description | | ----------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | yes | Search term matched against the token's `symbol` and `name`. Case-insensitive. **Minimum 3 characters** after trimming whitespace; shorter queries return an empty result set. | | `chain_ids` | string | no | Comma-separated chain IDs (`1,8453`) or a tag (`mainnet`, `default`). When omitted, all supported chains are searched. See the [Supported Chains](/evm/supported-chains#tags) page. | | `limit` | integer | no | Maximum number of results to return. Default `10`, maximum `50` — values above the maximum are clamped silently. Values below `1` are clamped to `1`. | ## Response Fields The endpoint returns a JSON array of token objects. Each object has: | Field | Type | Description | | ------------ | --------------- | ----------------------------------------------------------------- | | `chain_id` | integer | EVM chain ID where the token is deployed | | `address` | string | The token's contract address (lowercase, `0x`-prefixed) | | `token_type` | string | `"ERC20"` | | `symbol` | string | Token symbol (e.g. `USDC`, `WETH`) | | `name` | string | Token name (e.g. `USD Coin`, `Wrapped Ether`) | | `logo` | string \| null | Logo URL when available; `null` for tokens without a known logo. | | `decimals` | integer \| null | Token decimals; `null` for tokens without a known decimals value. | ## How Search Works Search is powered by an in-memory **trigram index** built over each token's `symbol` and `name`. Properties: * **Case-insensitive.** `usdc` and `USDC` match the same set of tokens. * **Substring-friendly.** `Teth` matches `Tether`, `TetherUSD`, and similar. * **Three-character minimum.** Queries of fewer than 3 characters (after trimming) return an empty array — trigrams need at least 3 characters of input. * **Ranked.** Tokens with an internal ranking score (driven by activity / liquidity signals) appear first. Ties fall back to a deterministic `(chain_id ASC, address ASC)` ordering, so repeat queries return stable results. ## Filtering Examples **Restrict to a single chain** ```bash theme={null} curl "https://api.sim.dune.com/v1/evm/search/tokens?query=USDC&chain_ids=8453" \ -H "X-Sim-Api-Key: YOUR_API_KEY" ``` **Search across the default chain set** ```bash theme={null} curl "https://api.sim.dune.com/v1/evm/search/tokens?query=Tether&chain_ids=default" \ -H "X-Sim-Api-Key: YOUR_API_KEY" ``` ## Error Responses | Status | Cause | | ------------------ | ------------------------------------------------------------------------------------------- | | `400 Bad Request` | `query` parameter is missing or empty after trimming, or a query parameter cannot be parsed | | `401 Unauthorized` | Missing or invalid `X-Sim-Api-Key` header | ## Compute Unit Cost The Search Tokens endpoint has a fixed CU cost of **2** per request. The `chain_ids` query parameter does not change the CU cost. See the [Compute Units](/compute-units) page for detailed information. ## OpenAPI ````yaml /openapi.json GET /v1/evm/search/tokens openapi: 3.0.3 info: title: Sim API description: >- The Sim API by Dune provides real-time blockchain data across EVM and SVM chains. Access token balances, transaction history, on-chain activity, DeFi positions, NFT collectibles, token information, and webhook subscriptions through a unified REST API. version: 1.0.0 license: name: '' contact: name: Dune Support url: https://docs.sim.dune.com email: support@dune.com servers: - url: https://api.sim.dune.com security: - ApiKeyAuth: [] tags: - name: evm description: EVM-compatible blockchain endpoints. - name: svm description: Solana/SVM blockchain endpoints. - name: activity description: On-chain activity feed. - name: balances description: Token balances (EVM and SVM). - name: transactions description: Transaction history (EVM and SVM). - name: collectibles description: NFT and ERC721/ERC1155 holdings. - name: defi description: DeFi protocol positions. - name: supported-chains description: Supported blockchain networks. - name: token-info description: Token metadata and pricing. - name: token-holders description: Token holder distribution. - name: subscriptions description: >- Webhook subscription management for real-time on-chain event notifications. paths: /v1/evm/search/tokens: get: tags: - evm - search summary: Search Tokens description: >- Search ERC20 tokens across supported EVM chains by symbol or name. Results are ranked by an internal score (where available) with deterministic `(chain_id ASC, address ASC)` tiebreak, and are enriched with `logo` and `decimals`. Search is case-insensitive and uses a trigram index — queries shorter than 3 characters (after trimming) return an empty array. operationId: searchEvmTokens parameters: - name: query in: query required: true description: >- Search term matched against the token's `symbol` and `name`. Case-insensitive. Minimum 3 characters after trimming whitespace; shorter queries return an empty result set. schema: type: string minLength: 3 example: USDC - name: chain_ids in: query required: false description: >- Filter by chain(s). Accepts numeric chain IDs and/or tags. Provide a single value (e.g. `?chain_ids=1` or `?chain_ids=mainnet`) or a comma-separated list (e.g. `?chain_ids=1,8453,testnet`). When omitted, all supported chains are searched. See the [Supported Chains Tags](/evm/supported-chains#tags) section. schema: type: string example: 1,8453 - name: limit in: query required: false description: >- Maximum number of results to return. Default is 10 when not provided. Values above 50 are clamped to 50; values below 1 are clamped to 1. schema: type: integer format: int32 minimum: 1 maximum: 50 default: 10 responses: '200': description: An array of matching tokens, ranked by relevance. content: application/json: schema: $ref: '#/components/schemas/TokenSearchResponse' examples: success: value: - chain_id: 1 address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' token_type: ERC20 symbol: USDC name: USD Coin logo: >- https://api.sim.dune.com/beta/token/logo/1/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 decimals: 6 - chain_id: 8453 address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' token_type: ERC20 symbol: USDC name: USD Coin logo: >- https://api.sim.dune.com/beta/token/logo/8453/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 decimals: 6 empty: summary: No matches value: [] '400': description: >- Bad Request - Missing or empty `query` parameter, or unparseable query parameters. content: application/json: schema: $ref: '#/components/schemas/TokenHolders_ErrorResponse' examples: missingQuery: summary: Missing query parameter value: error: message: 'Missing required parameter: query' code: BAD_REQUEST '401': description: Unauthorized - Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/GatewayErrorResponse' examples: invalidApiKey: value: error: invalid API Key '429': description: Rate Limit Exceeded - Too many requests. content: application/json: schema: $ref: '#/components/schemas/GatewayErrorResponse' examples: rateLimitExceeded: value: error: >- Too many requests. Please contact sales@dune.com to increase your limit. '500': description: Internal Server Error - Server-side error. content: application/json: schema: $ref: '#/components/schemas/TokenHolders_ErrorResponse' examples: internalServerError: value: error: message: Server-side error code: INTERNAL_SERVER_ERROR components: schemas: TokenSearchResponse: type: array description: >- Search results, ranked by internal score then `(chain_id ASC, address ASC)` for stable ordering. May be empty. items: $ref: '#/components/schemas/TokenSearchResult' TokenHolders_ErrorResponse: type: object properties: error: $ref: '#/components/schemas/ErrorDetail' required: - error GatewayErrorResponse: type: object description: >- Error response from the API gateway. Returned for authentication, permissions, rate-limiting, and quota errors. properties: error: type: string description: Error message. required: - error TokenSearchResult: type: object description: A single ERC20 token matched by the search index. properties: chain_id: type: integer format: int64 description: EVM chain ID where the token is deployed. example: 1 address: type: string format: address pattern: ^0x[a-fA-F0-9]{40}$ description: The token's contract address (lowercase, 0x-prefixed). example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' token_type: type: string enum: - ERC20 description: The token standard. Always `ERC20`. symbol: type: string description: Token symbol (e.g. `USDC`, `WETH`). example: USDC name: type: string description: Token name (e.g. `USD Coin`, `Wrapped Ether`). example: USD Coin logo: type: string nullable: true description: Logo URL when available; `null` for tokens without a known logo. example: >- https://api.sim.dune.com/beta/token/logo/1/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 decimals: type: integer format: int32 nullable: true description: Token decimals; `null` for tokens without a known decimals value. example: 6 required: - chain_id - address - token_type - symbol - name ErrorDetail: type: object properties: message: type: string description: Description of what went wrong. example: Invalid or missing API key code: type: string description: Error code. example: UNAUTHORIZED required: - message - code securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Sim-Api-Key description: >- API key for authentication. Obtain your key from the Dune dashboard at sim.dune.com. ````