Jettons

​

Jetton Object

• address (string, required): Raw blockchain address of the jetton master contract. ⚠️ Always returned in raw hex form (workchain:hash).
• decimals (integer, required): Number of decimal places the jetton supports.
• created_at (ISO 8601 datetime): Date and time the jetton was added to the list.
• total_supply (string): Total supply in base units (no decimal point).
• name (string): Jetton name, e.g. Tether USD.
• symbol (string): Jetton ticker, e.g. USDT.
• mintable (boolean): Whether new tokens can be minted.
• buy_fee (integer): On-chain fee (bps) charged on buys, if any.
• sell_fee (integer): On-chain fee (bps) charged on sells, if any.
• verification (enum): Verification status — see Verification Status.
• contract_interface (string): Implementation identifier (e.g. jetton_wallet_tonfun). Used by the aggregator to route through specialized jetton implementations.
• image_url (string): URL of the jetton logo.
• market_stats (object): Aggregated market statistics — see Market Statistics.
• labels (array): Labels attached to the jetton — see Labels.
• scaled_ui_multiplier (object): Optional UI multiplier (numerator / denominator) applied on top of decimals when displaying balances to end users. Relevant for rebase / scaled-UI jettons.

​

Market Statistics

• holders_count (integer): Number of unique jetton holders.
• price_usd (number): Current price in USD.
• price_change_5m (number): Price change over the last 5 minutes (percentage).
• price_change_1h (number): Price change over the last hour (percentage).
• price_change_6h (number): Price change over the last 6 hours (percentage).
• price_change_24h (number): Price change over the last 24 hours (percentage).
• price_change_7d (number): Price change over the last 7 days (percentage).
• volume_usd_24h (number): 24-hour trading volume in USD.
• tvl_usd (number): Total value locked in USD across supported pools.
• fdmc (number): Fully diluted market capitalization in USD.
• mcap (number): Circulating market capitalization in USD.
• trust_score (integer, 0–100): Reliability score computed from multiple signals.

​

Verification Status

• WHITELISTED — the jetton is verified and whitelisted by swap.coffee. Safe and routable; guaranteed to be fee-free.
• COMMUNITY — the jetton’s contract hash is recognized as safe, but the jetton is not used in swap.coffee routing. Guaranteed to be fee-free.
• UNKNOWN — the jetton is not verified and may be unsafe.
• BLACKLISTED — the jetton is blacklisted and considered dangerous.

​

Example

{
  "address": "0:a5d12e31be87867851a28d3ce271203c8fa1a28ae826256e73c506d94d49edad",
  "decimals": 9,
  "created_at": "2025-04-14T16:06:08.765Z",
  "total_supply": "10000000000000000",
  "name": "swap.coffee",
  "symbol": "CES",
  "mintable": false,
  "buy_fee": 0,
  "sell_fee": 0,
  "verification": "WHITELISTED",
  "contract_interface": "jetton_wallet",
  "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,
    "price_change_7d": 1.12,
    "volume_usd_24h": 192.946,
    "tvl_usd": 72106.4,
    "fdmc": 8250090,
    "mcap": 8250090,
    "trust_score": 100
  },
  "labels": [
    {
      "label": "new",
      "label_id": 1,
      "created_at": "2025-07-15T10:52:55.611Z",
      "expires_at": "2025-07-22T10:52:55.585Z"
    }
  ]
}

​

List Jettons

GET /api/v3/jettons

• search (string) — free-text filter across jetton name and symbol.
• verification (array of verification statuses, default: [WHITELISTED]) — verification statuses to include. Accepted values: WHITELISTED, COMMUNITY, UNKNOWN, BLACKLISTED. ⚠️ To pass multiple values, repeat the parameter in the query string, e.g. verification=WHITELISTED&verification=COMMUNITY.
• label_id (integer) — return only jettons carrying a specific label.
• page (integer, min: 1, default: 1) — page number.
• size (integer, 1–100, default: 100) — number of jettons per page.

​

Get a Single Jetton

GET /api/v3/jettons/{address}

• address (path, required) — raw jetton master address.
• refresh_price (query, boolean, default: true) — whether to recompute the current price on the fly from the latest pools state. Set to false for a cheaper read that returns a slightly stale price.

​

Bulk Fetch by Addresses

POST /api/v3/jettons/by-addresses

[
  "0:a5d12e31be87867851a28d3ce271203c8fa1a28ae826256e73c506d94d49edad",
  "0:b113a994b5024a16719f69139328eb759596c38a25f59028b146fecdc3621dfe"
]

​

Top Holders

GET /api/v3/jettons/{address}/holders

• owner — wallet owner address.
• wallet — jetton wallet address.
• master — jetton master address.
• balance — balance in nano units (string).

​

Price Chart

GET /api/v3/jettons/{address}/price-chart

• from (datetime, required) — start of the window (inclusive).
• to (datetime, required) — end of the window (inclusive).
• currency (enum: usd | ton, default: usd) — denomination for returned values.

{
  "points": [
    { "time": "2025-04-14T16:06:08.765Z", "value": 0.8406 },
    { "time": "2025-04-14T17:06:08.765Z", "value": 0.8411 }
  ]
}

​

Account Jettons

GET /api/v3/accounts/{address}/jettons

{
  "items": [
    {
      "balance": "1000000000",
      "jetton_address": "0:...",
      "jetton_wallet": "0:...",
      "jetton": { /* ApiJetton object */ }
    }
  ]
}