Ctrlk
SwapKit's websiteRegister for an API Key
For the complete documentation index, see llms.txt. This page is also available as Markdown.

/tokens - List and search supported tokens

GET /tokens

The /tokens endpoint provides a list of tokens for a specified provider. This endpoint requires a provider query parameter to determine which provider's tokens you want to retrieve, and accepts an optional category — see Filtering by asset category.

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://tokens.swapkit.dev/images/btc.btc.png",
      "coingeckoId": "bitcoin"
    },
    {
      "chain": "ARB",
      "chainId": "42161",
      "ticker": "ETH",
      "identifier": "ARB.ETH",
      "symbol": "ETH",
      "name": "Arbitrum Ether",
      "decimals": 18,
      "logoURI": "https://tokens.swapkit.dev/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://tokens.swapkit.dev/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

Searching by contract address works too:

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.

category

string

No

all (default), crypto or rwa. See Filtering by asset category.

Example response

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.

Filtering by asset category

Both /tokens and /tokens/search accept category, which splits the corpus into ordinary crypto and real-world assets — tokenized equities, ETFs and commodities.

Value
Returns

all

Everything. The default, so omitting it changes nothing.

crypto

Everything except RWAs.

rwa

RWAs only — a few hundred contracts against tens of thousands, so a securities picker needn't pull the full list and filter it.

Category is not geoBlockRule. An asset is an RWA because of what it is; geoBlockRule names a jurisdiction policy that happens to apply to it. category=crypto doesn't exempt you from handling a 451 — see Tokenized equities & geo-restrictions.

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

Over your key's per-minute limit. See Rate limits and trade size.

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

Previous/providers - Providers, status, and identifiers mapping
Next/swapFrom - Request sell swap options

Last updated