# How it works

Every token on tonton lives on a **constant-product bonding curve** with virtual reserves. The math is the same shape as Uniswap's `x * y = k`, but seeded with virtual TON and virtual jettons so the price starts non-zero from the very first buy.

## The numbers

| Constant             |          Value | Meaning                                           |
| -------------------- | -------------: | ------------------------------------------------- |
| `TOTAL_SUPPLY`       |  1,000,000,000 | Total jettons minted (with 9 decimals).           |
| `CURVE_ALLOC`        |    800,000,000 | Jettons sold via the curve before graduation.     |
| `GRAD_LP_JETTON`     |    200,000,000 | Jettons seeded into the STON.fi LP at graduation. |
| `VIRTUAL_TON`        |      1,024 TON | Virtual TON reserve anchoring the curve.          |
| `VIRTUAL_JETTON`     |  1,073,000,000 | Virtual jetton reserve.                           |
| `PROTOCOL_FEE_BPS`   |   100 (1.00 %) | Cut taken by the protocol on every trade.         |
| `CREATOR_FEE_BPS`    |    30 (0.30 %) | Cut paid to the token's creator on every trade.   |
| `GRADUATION_TON_CAP` | \~3,001.46 TON | Total buyer spend that fills the curve.           |
| `MIGRATION_FEE_TON`  |        220 TON | Paid to treasury at graduation.                   |
| `LP_TON_AT_GRAD`     |    \~2,781 TON | TON deposited into STON.fi LP at graduation.      |

## How a buy quote is calculated

Given the curve's current `tokensSold` and `tonCollected`:

```
x = VIRTUAL_TON + tonCollected
y = VIRTUAL_JETTON - tokensSold

protocolFee = tonGross * 100 / 10000   # 1.00 %
creatorFee  = tonGross *  30 / 10000   # 0.30 %
tonNet      = tonGross - protocolFee - creatorFee

jettonsOut  = floor(y * tonNet / (x + tonNet))
```

All math uses BigInt with floor division — exactly what the contract does, so the off-chain preview matches the on-chain settle to the last unit.

If a buy would push `tokensSold` past `CURVE_ALLOC`, the contract takes **exactly enough TON to fill to the cap** and refunds the rest in the same tx. You can't accidentally overpay.

## How a sell quote is calculated

```
x = VIRTUAL_TON + tonCollected
y = VIRTUAL_JETTON - tokensSold

tonOutGross = floor(x * jettonsIn / (y + jettonsIn))
protocolFee = tonOutGross * 100 / 10000
creatorFee  = tonOutGross *  30 / 10000
tonNetOut   = tonOutGross - protocolFee - creatorFee
```

## Graduation

When `tonCollected` reaches `GRADUATION_TON_CAP` (\~3,001 TON of real buyer spend), the curve "graduates":

1. The remaining 200M jettons + \~2,781 TON are deposited into a **STON.fi** pair as the initial liquidity.
2. The 220 TON migration fee goes to the protocol treasury.
3. The bonding curve closes permanently — no more curve trades.
4. From that point on, the token is a standard jetton trading on STON.fi against TON.

Graduation happens *automatically* on the buy that crosses the cap. The buyer who fills the curve doesn't pay any extra fee for triggering it.

In the rare case a buy fills the curve but the auto-graduation message bounces (network blip), anyone can call `GRADUATE` op on the curve as a permissionless idempotent trigger. The SDK ships `buildGraduate()` for this.

## Spot price

The spot price (TON per jetton) at any point on the curve is just `x / y` where `x` and `y` are the post-virtual reserves. The SDK exposes:

* `spotPriceNano(tokensSold, tonCollected)` — returns scaled BigInt for precise math
* `spotPriceTonPerToken(tokensSold, tonCollected)` — returns a JS `number`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tonton.fun/how-it-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.