> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swap.coffee/llms.txt
> Use this file to discover all available pages before exploring further.

# Jettons

> Read jetton metadata, market statistics and per-account holdings.

This page describes the canonical **jetton object** returned by the Tokens API and the read-only endpoints that serve it.

## Jetton Object

Each jetton entry contains the following fields:

* **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](#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](#market-statistics).
* **labels** *(array)*: Labels attached to the jetton — see [Labels](/technical-guides/tokens-api/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

The `market_stats` object aggregates the most recent on-chain and market data:

* **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

The `verification` field reflects how swap.coffee classifies a jetton. Possible values:

* **`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

```json theme={null}
{
  "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

```http theme={null}
GET /api/v3/jettons
```

Returns up to 100 jettons per request. Supports filtering and pagination.

**Query parameters:**

* **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.

**Response:** `200 OK` — array of [jetton objects](#jetton-object), with a `Cache-Control` header for caching hints.

***

## Get a Single Jetton

```http theme={null}
GET /api/v3/jettons/{address}
```

Fetch a single jetton by its master address.

**Parameters:**

* **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.

**Responses:** `200 OK` — a [jetton object](#jetton-object) | `404 Not Found` — jetton is unknown.

***

## Bulk Fetch by Addresses

```http theme={null}
POST /api/v3/jettons/by-addresses
```

Fetch up to 100 jettons at once. The request body is a JSON array of raw jetton master addresses.

**Query parameter:** `refresh_price` *(boolean, default: true)*.

**Request body:**

```json theme={null}
[
  "0:a5d12e31be87867851a28d3ce271203c8fa1a28ae826256e73c506d94d49edad",
  "0:b113a994b5024a16719f69139328eb759596c38a25f59028b146fecdc3621dfe"
]
```

**Response:** `200 OK` — array of [jetton objects](#jetton-object).

***

## Top Holders

```http theme={null}
GET /api/v3/jettons/{address}/holders
```

Returns the **top 10 holders** of a jetton.

**Response:** `200 OK` — array of wallet entries, each with:

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

***

## Price Chart

```http theme={null}
GET /api/v3/jettons/{address}/price-chart
```

Historical price series for a jetton.

**Query parameters:**

* **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.

**Response:** `200 OK`

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

***

## Account Jettons

```http theme={null}
GET /api/v3/accounts/{address}/jettons
```

Returns all jettons owned by an account, with balances and the attached jetton metadata.

**Response shape:**

```json theme={null}
{
  "items": [
    {
      "balance": "1000000000",
      "jetton_address": "0:...",
      "jetton_wallet": "0:...",
      "jetton": { /* ApiJetton object */ }
    }
  ]
}
```