swap.coffee constantly updates its list of supported tokens (or jettons on TON). This list determines which assets our swap algorithms can use. Token data and their specific properties (TVL, price, etc.) are aggregated from various sources and refreshed regularly. You can swap any token from the list for another or build your own logic on top of it. The OpenAPI Specification for the tokens API is available here. You can generate your own API wrapper with the OpenAPI code generator.

​
Token properties

Each token entry includes the following fields:
  • created_at: The date and time when the token was added to the list.
  • address: Raw blockchain address of the token contract.
  • total_supply: Total token supply in the base units.
  • decimals: Number of decimal places the token supports.
  • mintable: Indicates whether additional tokens can be minted (true | false).
  • verification: Verification status (e.g., WHITELISTED).
  • name: Token name.
  • symbol: Token symbol (e.g., TON).
  • image_url: URL of the token image.
  • market_stats: Market statistics (see below).
Market statistics properties:
  • holders_count: Number of unique token holders.
  • price_usd: Current price in USD.
  • price_change_5m: Price change over the last 5 minutes (percentage).
  • price_change_1h: Price change over the last hour (percentage).
  • price_change_6h: Price change over the last 6 hours (percentage).
  • price_change_24h: Price change over the last 24 hours (percentage).
  • volume_usd_24h: 24-hour trading volume in USD.
  • tvl_usd: Total value locked (TVL) in USD.
  • fdmc: Fully diluted market capitalization in USD.
  • trust_score: Reliability score from 0 to 100.
⚠️ Note: The address field is provided in raw format. Example: CES token 
{
  "created_at": "2025-04-14T16:06:08.765Z",
  "address": "0:a5d12e31be87867851a28d3ce271203c8fa1a28ae826256e73c506d94d49edad",
  "total_supply": "10000000000000000",
  "decimals": 9,
  "mintable": false,
  "verification": "WHITELISTED",
  "name": "swap.coffee",
  "symbol": "CES",
  "image_url": "https://swap.coffee/logo.webp",
  "market_stats": {
    "holders_count": 6133,
    "price_usd": 0.8406369824666934,
    "price_change_5m": 0,
    "price_change_1h": 0,
    "price_change_6h": 0,
    "price_change_24h": 0.37,
    "volume_usd_24h": 192.946,
    "tvl_usd": 72106.4,
    "fdmc": 8250090,
    "trust_score": 100
  },
  "labels": []
}

​
Verification Status

The verification field reflects a token’s verification status. Possible values are:
  • WHITELISTED: The token is verified and whitelisted by swap.coffee. These assets are considered safe and are used in routing. Such tokens are guaranteed to be fee-free.
  • COMMUNITY: The token’s contract hash is deemed safe, but the asset is not included in swap.coffee routing. Such tokens are guaranteed to be fee-free.
  • UNKNOWN: The token is unverified and may be unsafe.
  • BLACKLISTED: The token is blacklisted and considered dangerous.

​
Token Labels

The labels property is an array of strings that classify a token. Possible values include:
  • new: The token was recently listed; the label remains for seven days.
  • contest: The token participates in a contest or promotion on swap.coffee.
  • cashback: Swapping this token on swap.coffee qualifies for cashback rewards.
[
  {
    "created_at": "2025-04-14T16:06:08.765Z",
    "address": "0:a5d12e31be87867851a28d3ce271203c8fa1a28ae826256e73c506d94d49edad",
    "total_supply": "10000000000000000",
    "decimals": 9,
    "mintable": false,
    "verification": "WHITELISTED",
    "name": "swap.coffee",
    "symbol": "CES",
    "image_url": "https://swap.coffee/logo.webp",
    "labels": [
      {
        "label": "new",
        "label_id": 1,
        "created_at": "2025-07-15T10:52:55.611Z",
        "expires_at": "2025-07-22T10:52:55.585Z"
      }
    ]
  }
]
All datetime fields are in ISO 8601 format.

​
Listing Tokens

The dedicated endpoint retrieves jettons (up to 100 per request) and supports the following query parameters:
  • search: A string used to filter jettons by name or symbol.
  • verification: An array of verification statuses to filter the results. Accepted values: WHITELISTED, COMMUNITY, UNKNOWN, BLACKLISTED. If omitted, only WHITELISTED jettons are returned.
  • label_id: An integer that filters jettons by a specific label ID.
  • page: The page number for pagination (default: 1).
  • size: The number of jettons per page (default: 100).
⚠️ Note: To specify multiple verification statuses, repeat the parameter in the query string, e.g. verification=WHITELISTED&verification=COMMUNITY.

​
Community libraries

⚠️ Note: The libraries listed below are maintained by third parties rather than the swap.coffee team. Consequently, we cannot guarantee their stability or correctness.
LanguageLibraryDescription
Pythonpy-stollen/swapcoffee-tokensPython wrapper for the Tokens APIWrapper for legacy v2 API.