Token Symbol Resolution

GET/gateway/v1/search/token

Resolves an exact token ticker symbol to likely contract address candidates on supported chains.

Use this before calling token endpoints that require a contract address. Pass a returned `chain` + `address` only to endpoints that support that chain.

Results are ranked by Surf registry, listing, and market signals. `volume_usd` is kept for response compatibility, always returns `0`, and must not be used as a candidate ordering signal.

Included fields: symbol, chain, address, decimals, volume_usd.

Chains: Ethereum, Base, BSC, Arbitrum, Solana, Polygon, Optimism, Avalanche, Fantom, Tron, Linea, Mantle, Blast, Gnosis, zkSync, Scroll.

Query Parameters

qstringrequired

Exact token ticker symbol to resolve (case-insensitive), like `USDC` or `PEPE`. NOT a contract address, trading pair, or fuzzy token name.

Example: USDC

chainenum<string>

Restrict resolution to one supported chain. Omit to search all supported chains.

Available options:ethereumbasebscarbitrumsolanapolygonoptimismavalanchefantomtronlineamantleblastgnosiszksyncscroll

Example: solana

limitinteger

Results per page

Example: 20

offsetinteger

Pagination offset

Example: 0

Token Symbol Resolution

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/search/token?q=USDC&chain=solana&limit=20&offset=0', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/DataResponseSearchTokenItem.json",
  "data": [
    {
      "address": "<string>",
      "chain": "<string>",
      "decimals": 123,
      "symbol": "<string>",
      "volume_usd": 123
    }
  ],
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>",
    "has_more": true,
    "limit": 123,
    "offset": 123,
    "total": 123,
    "watermark": 123
  }
}