/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

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

---

Example shortened response

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

Field	Type	Description
provider and name	string	The name of the provider specified in the query.
timestamp	string	The timestamp of when the response was generated.
count	number	The number of tokens included in the response.
tokens	array	An array of token objects, each representing a token available for the specified provider.

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:

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

---

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

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:

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

---

Query parameters

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

---

Example response

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

Field	Type	Description
tokens	array	Array of matching token objects, ranked most relevant first (see Ranking).
total	number	Total number of matches before pagination.
page	number	The 1-based page number returned.
limit	number	The page size used.
hasMore	boolean	Whether another page of results exists.

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

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

---

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

Status	When
400	Missing/empty query, limit outside 1–100, page < 1, or an invalid chain/provider value.
401	Missing or invalid API key.
429	Rate limit exceeded. The default limit is 60 requests per minute per API key (configurable per key); the response includes a retryAfter value in seconds.
500	Token lists temporarily unavailable (transient — safe to retry).

---

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().