---
title: "Token Symbol Resolution"
method: GET
path: "/gateway/v1/search/token"
tags: ["Search"]
---

# 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

- `q` string, required — Exact token ticker symbol to resolve (case-insensitive), like `USDC` or `PEPE`. NOT a contract address, trading pair, or fuzzy token name.
- `chain` 'ethereum' | 'base' | 'bsc' | 'arbitrum' | 'solana' | 'polygon' | 'optimism' | 'avalanche' | 'fantom' | 'tron' | 'linea' | 'mantle' | 'blast' | 'gnosis' | 'zksync' | 'scroll' — Restrict resolution to one supported chain. Omit to search all supported chains.
- `limit` integer — Results per page
- `offset` integer — Pagination offset

## Response `200`

OK

- DataResponseSearchTokenItem
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `data` SearchTokenItem[], nullable, required
    - `address` string, required — Token contract address. Use together with `chain` only on token endpoints that support the returned chain.
    - `chain` string, required — Chain the contract is deployed on
    - `decimals` integer, required — Token decimal places
    - `symbol` string, required — Token ticker symbol (canonical uppercase)
    - `volume_usd` number, double, required — Reserved compatibility field. Always returns 0; do not use this field for candidate ordering.
  - `meta` OffsetMeta, required
    - `cached` boolean, required — Whether this response was served from cache
    - `credits_used` integer, required — Credits deducted for this request
    - `empty_reason` string — Hint explaining why the data array is empty, when applicable
    - `has_more` boolean — Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required — Maximum number of items returned in this response
    - `offset` integer, required — Number of items skipped (pagination offset)
    - `total` integer — Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer — Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) · [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/asksurf/asksurf-public-rest-api/revisions/498f461e81c4/schema)