> For the complete documentation index, see [llms.txt](https://docs.swapkit.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapkit.dev/swapkit-api/tokens-list-and-search-supported-tokens.md).

# /tokens - List and search supported tokens

## `GET /tokens`

The `/tokens` endpoint provides a list of tokens for a specified provider. This endpoint requires a query parameter to determine which provider's tokens you want to retrieve.

**Method:** `GET`\
**URL:** `https://api.swapkit.dev/tokens`

#### Example Request

```bash
curl -X 'GET' \
  'https://api.swapkit.dev/tokens?provider=CHAINFLIP' \
  -H 'accept: application/json' \
  -H "x-api-key: YOUR_VARIABLE_HERE"
```

***

### Example shortened response

```json
{
  "provider": "CHAINFLIP",
  "name": "CHAINFLIP",
  "timestamp": "2025-01-11T16:31:04.355Z",
  "version": {
    "major": 1,
    "minor": 0,
    "patch": 0
  },
  "keywords": [],
  "count": 10,
  "tokens": [
    {
      "chain": "BTC",
      "chainId": "bitcoin",
      "ticker": "BTC",
      "identifier": "BTC.BTC",
      "symbol": "BTC",
      "name": "Bitcoin",
      "decimals": 8,
      "logoURI": "https://storage.googleapis.com/token-list-swapkit/images/btc.btc.png",
      "coingeckoId": "bitcoin"
    },
    {
      "chain": "ARB",
      "chainId": "42161",
      "ticker": "ETH",
      "identifier": "ARB.ETH",
      "symbol": "ETH",
      "name": "Arbitrum Ether",
      "decimals": 18,
      "logoURI": "https://storage.googleapis.com/token-list-swapkit/images/arb.eth.png",
      "coingeckoId": "ethereum"
    },
    {
      "chain": "SOL",
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "chainId": "solana",
      "ticker": "USDC",
      "identifier": "SOL.USDC-EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC-EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "name": "Solana USDC",
      "decimals": 6,
      "logoURI": "https://storage.googleapis.com/token-list-swapkit/images/sol.usdc-epjfwdd5aufqssqem2qn1xzybapc8g4weggkzwytdt1v.png"
    },
    ...
  ]
}
```

***

### Response fields

The relevant response fields are:

<table><thead><tr><th width="257">Field</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>provider</code> and <code>name</code></td><td><code>string</code></td><td>The name of the provider specified in the query.</td></tr><tr><td><code>timestamp</code></td><td><code>string</code></td><td>The timestamp of when the response was generated.</td></tr><tr><td><code>count</code></td><td><code>number</code></td><td>The number of tokens included in the response.</td></tr><tr><td><code>tokens</code></td><td><code>array</code></td><td>An array of token objects, each representing a token available for the specified provider.</td></tr></tbody></table>

#### Each token includes information to properly distinguish it from others. Note the `identifier` in particular, as it's what identifies a token within the SwapKit API:

<table><thead><tr><th width="257">Field</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>chain</code></td><td><code>string</code></td><td>The blockchain the token is associated with (e.g., <code>ETH</code>, <code>BTC</code>, <code>SOL</code>).</td></tr><tr><td><code>address</code></td><td><code>string</code></td><td>The contract address of the token (only provided if it is not the gas token of the network).</td></tr><tr><td><code>chainId</code></td><td><code>string</code></td><td>The ID of the chain. It could be a numeric ID (e.g., <code>42161</code> for Arbitrum) or a name like <code>solana</code>.</td></tr><tr><td><code>ticker</code></td><td><code>string</code></td><td>The ticker symbol of the token (e.g., <code>ETH</code>, <code>BTC</code>).</td></tr><tr><td><code>identifier</code></td><td><code>string</code></td><td>An identifier for the token that combines chain and token address, used to identify the token in SwapKit API.</td></tr><tr><td><code>symbol</code></td><td><code>string</code></td><td>The token symbol, which includes address information.</td></tr><tr><td><code>name</code></td><td><code>string</code></td><td>The full name of the token.</td></tr><tr><td><code>decimals</code></td><td><code>number</code></td><td>The number of decimal places the token supports.</td></tr><tr><td><code>logoURI</code></td><td><code>string</code></td><td>A URL pointing to the token's logo image.</td></tr><tr><td><code>coingeckoId</code></td><td><code>string</code></td><td>The identifier of the token on CoinGecko (if available).</td></tr></tbody></table>

***

### Notes

* The `identifier` is what SwapKit uses to uniquely identify a token in all its requests and responses. It includes the chain, the name and the token address. It is how the token should be named when using the `/quote` endpoint.
  * The identifier is built by putting together Chain.Ticker-ContractAddress (e.g., `"ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"`).
  * Gas assets like BTC, ETH or SOL don't require a contract address, so their identifier is just `BTC.BTC` for example.
* Tokens with an `address` field are specific instances of a token on a given chain (e.g., `USDC` on Ethereum or Solana). While the `coingeckoId` could be shared, we provide the relevant contract address for the token in the specific chain.

***

## `GET /tokens/search` - Search tokens

The `/tokens/search` endpoint runs a free-text search across SwapKit's combined provider token lists. Built for search-box UX, it accepts a ticker (`usdc`), name (`usd coin`), contract address, or full SwapKit identifier (`ETH.USDC-0x…`), and returns deduplicated results ranked by relevance.

Like all `/tokens/*` endpoints, it is protected by the `x-api-key` header and rate-limited.

**Method:** `GET`\
**URL:** `https://api.swapkit.dev/tokens/search`

#### Example Request

```bash
curl -X 'GET' \
  'https://api.swapkit.dev/tokens/search?query=usdc&chain=ETH&limit=20' \
  -H 'accept: application/json' \
  -H "x-api-key: YOUR_VARIABLE_HERE"
```

Searching by contract address works too:

```bash
curl -X 'GET' \
  'https://api.swapkit.dev/tokens/search?query=0xdAC17F958D2ee523a2206206994597C13D831ec7' \
  -H 'accept: application/json' \
  -H "x-api-key: YOUR_VARIABLE_HERE"
```

***

### Query parameters

<table><thead><tr><th width="140">Parameter</th><th width="110">Type</th><th width="109.9296875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>query</code></td><td><code>string</code></td><td>Yes</td><td>Free text, 3–256 characters. Matched case-insensitively against <code>identifier</code>, <code>ticker</code>, <code>symbol</code>, <code>name</code>, and contract <code>address</code>.</td></tr><tr><td><code>chain</code></td><td><code>string</code></td><td>No</td><td>Only return assets on this chain (e.g. <code>ETH</code>, <code>BTC</code>, <code>SOL</code>).</td></tr><tr><td><code>provider</code></td><td><code>string</code></td><td>No</td><td>Only match assets present in this provider's token list (e.g. <code>ONEINCH</code>). Restricts what can match, not what is reported in <code>providers</code>.</td></tr><tr><td><code>limit</code></td><td><code>number</code></td><td>No</td><td>Page size, 1–100. Defaults to <code>100</code>.</td></tr><tr><td><code>page</code></td><td><code>number</code></td><td>No</td><td>1-based page number (≥ 1). Defaults to <code>1</code>.</td></tr></tbody></table>

***

### Example response

```json
{
  "tokens": [
    {
      "identifier": "ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48",
      "chain": "ETH",
      "chainId": "1",
      "ticker": "USDC",
      "symbol": "USDC-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "name": "USD Coin",
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "decimals": 6,
      "logoURI": "https://…",
      "coingeckoId": "usd-coin",
      "providers": ["ONEINCH", "UNISWAP_V3"],
      "marketCapUsd": 30000000000
    },
    ...
  ],
  "total": 42,
  "page": 1,
  "limit": 100,
  "hasMore": false
}
```

***

### Response fields

<table><thead><tr><th width="140">Field</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>tokens</code></td><td><code>array</code></td><td>Array of matching token objects, ranked most relevant first (see <a href="#ranking">Ranking</a>).</td></tr><tr><td><code>total</code></td><td><code>number</code></td><td>Total number of matches before pagination.</td></tr><tr><td><code>page</code></td><td><code>number</code></td><td>The 1-based page number returned.</td></tr><tr><td><code>limit</code></td><td><code>number</code></td><td>The page size used.</td></tr><tr><td><code>hasMore</code></td><td><code>boolean</code></td><td>Whether another page of results exists.</td></tr></tbody></table>

Each object in `tokens` uses the same shape as a token from the `/tokens` endpoint, plus `providers` and `marketCapUsd` :

<table><thead><tr><th width="170">Field</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>identifier</code></td><td><code>string</code></td><td>The SwapKit identifier (<code>Chain.Ticker-ContractAddress</code>).</td></tr><tr><td><code>chain</code></td><td><code>string</code></td><td>The blockchain the token is on (e.g., <code>ETH</code>, <code>BTC</code>, <code>SOL</code>).</td></tr><tr><td><code>chainId</code></td><td><code>string</code></td><td>The ID of the chain. Either a numeric ID (e.g., <code>1</code> for Ethereum, <code>42161</code> for Arbitrum) or a name like <code>solana</code>.</td></tr><tr><td><code>ticker</code></td><td><code>string</code></td><td>The ticker symbol of the token (e.g., <code>USDC</code>).</td></tr><tr><td><code>symbol</code></td><td><code>string</code></td><td>The token symbol, which includes address information. <em>Optional — omitted when unknown.</em></td></tr><tr><td><code>name</code></td><td><code>string</code></td><td>The full name of the token. <em>Optional — omitted when unknown.</em></td></tr><tr><td><code>address</code></td><td><code>string</code></td><td>The contract address of the token. <em>Only provided if it is not the gas token of the network.</em></td></tr><tr><td><code>decimals</code></td><td><code>number</code></td><td>The number of decimal places the token supports.</td></tr><tr><td><code>logoURI</code></td><td><code>string</code></td><td>URL pointing to the token's logo image. <em>Optional — omitted when unknown.</em></td></tr><tr><td><code>coingeckoId</code></td><td><code>string</code></td><td>The token's CoinGecko ID. <em>Optional — omitted when unknown.</em></td></tr><tr><td><code>providers</code></td><td><code>array</code></td><td>Every provider listing this asset. Reported in full even when the <code>provider</code> filter is used — the filter restricts what can match, not what is reported.</td></tr><tr><td><code>marketCapUsd</code></td><td><code>number</code></td><td>Market cap in USD, from SwapKit's CoinGecko-backed price feed. <em>Optional</em> — only tokens with market-cap data in the feed include it; long-tail tokens won't have it, which is expected.</td></tr></tbody></table>

***

### Ranking

Results are sorted primarily by **match quality**, in tiers:

1. Exact identifier match
2. Exact contract-address match
3. Exact ticker / symbol match
4. Exact name match
5. Ticker / symbol / identifier prefix
6. Name prefix
7. Substring anywhere in the above fields

Within a tier, ties break by **market cap** (descending; assets without market-cap data sort after those with it), then by the **number of providers** listing the asset, then by **identifier** alphabetically, so ordering is fully deterministic.

***

### Errors

<table><thead><tr><th width="110">Status</th><th>When</th></tr></thead><tbody><tr><td><code>400</code></td><td>Missing/empty <code>query</code>, <code>limit</code> outside 1–100, <code>page</code> &#x3C; 1, or an invalid <code>chain</code>/<code>provider</code> value.</td></tr><tr><td><code>401</code></td><td>Missing or invalid API key.</td></tr><tr><td><code>429</code></td><td>Rate limit exceeded. The default limit is 60 requests per minute per API key (configurable per key); the response includes a <code>retryAfter</code> value in seconds.</td></tr><tr><td><code>500</code></td><td>Token lists temporarily unavailable (transient — safe to retry).</td></tr></tbody></table>

***

### Notes

* **Case-insensitive everywhere**, including contract addresses. Identifiers are returned normalized (uppercased) except on case-sensitive chains (Solana, NEAR, Sui, Tron, TON, Ripple), where original casing is preserved. Note that the address inside an EVM `identifier` is uppercased, while the standalone `address` field keeps its checksummed casing — use `address` when you need the checksummed form.
* **Multi-word queries** match tokens that contain every term — e.g. `usd coin` matches "USD Coin". When matching names, prefixes, or substrings, spaces and the separators `. _ : / -` all count as the same thing. Exact matches on an identifier, address, or ticker use the value exactly as written.
* **Deduplicated by normalized identifier** — a token listed by 5 providers appears once, with all 5 in `providers`.
* **Same data source as `/tokens`.** Results come from the same cached token lists behind `GET /tokens` — no live provider calls. The lists refresh roughly every 30 minutes, and search responses are additionally cached per query for about 5 minutes (region-local).
* **Pagination is deterministic and stable within a cache window.** Deterministic ordering means paging is stable across calls within the same \~5-minute response cache window. After the token lists refresh (\~30 min), ranking can shift, so a client paging slowly across a refresh boundary may see a token skipped or repeated.
* **Empty results.** A query with no matches (or a `page` beyond the last page) returns `"tokens": []`, `"total": 0`, `"hasMore": false`.
* **SDK.** Will be available shortly in the TypeScript SDK as `SwapKitService.searchTokens()`.