Search Tokens

Search ERC20 tokens across supported EVM chains by symbol or name, with optional chain filters. Results are enriched with logo and decimals.

GET /v1/evm/search/tokens

Search Tokens

cURL

curl --request GET \
  --url https://api.sim.dune.com/v1/evm/search/tokens \
  --header 'X-Sim-Api-Key: <api-key>'

200

success

[
  {
    "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
  }
]

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

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"

Response (JSON)

[
  {
    "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 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

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

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 page for detailed information.

Authorizations

X-Sim-Api-Key · string · header · required

API key for authentication. Obtain your key from the Dune dashboard at sim.dune.com.

Query Parameters

query · string · required

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.

Minimum string length: 3

chain_ids · string

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 section.

limit · integer<int32> · default: 10

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.

Required range: 1 <= x <= 50

Response

200

application/json

An array of matching tokens, ranked by relevance.

chain_id · integer<int64> · required

EVM chain ID where the token is deployed.

Example:

1

address · string<address> · required

The token's contract address (lowercase, 0x-prefixed).

Pattern: ^0x[a-fA-F0-9]{40}$

Example:

"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

token_type · enum<string> · required

The token standard. Always ERC20.

Available options: ERC20

symbol · string · required

Token symbol (e.g. USDC, WETH).

Example:

"USDC"

name · string · required

Token name (e.g. USD Coin, Wrapped Ether).

Example:

"USD Coin"

logo · string | null

Logo URL when available; null for tokens without a known logo.

Example:

"https://api.sim.dune.com/beta/token/logo/1/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

decimals · integer<int32> | null

Token decimals; null for tokens without a known decimals value.

Example:

6