Jetton prices in USD: where apiton's numbers come from

apiton shows an approximate USD value next to jetton balances — on address pages on apiton.org and in the API field price_usd. This article explains exactly where that number comes from, how fresh it is, and why it is sometimes absent.

A jetton is a token on TON (the fungible-token standard is TEP-74). Each jetton is identified by its master contract address; the balances live in per-holder jetton wallets. Prices are always keyed by the master. For the basics see Jettons on TON.

The source: a DEX asset list

The blockchain itself has no notion of a USD price. apiton takes prices from the public asset list of the STON.fi decentralised exchange, which publishes a USD price (dex_usd_price) for each asset traded on it, derived from its pools.

How apiton uses that list:

• A background job downloads the whole list every 3 minutes (with a 60-second timeout) and keeps only two fields per asset: the master address and the USD price.
• Assets without a positive price, and entries whose address cannot be parsed, are dropped.
• The prices are replaced all at once: a reader never sees half an update, and a jetton removed from the list disappears from apiton on the next refresh.
• The stored prices expire after 30 minutes. If the feed stops updating, prices vanish instead of silently going stale.

So a price shown by apiton is at most a few minutes old in normal operation, and never more than 30 minutes old.

What the price means

price_usd is the price of one whole token, with the jetton's decimals already applied. A balance of 50 tokens at a price_usd of 2 is worth $100; no further scaling by decimals is needed.

It is a DEX price: what the exchange's pools imply at the moment of the snapshot. For thinly traded tokens that can differ a lot from what you could actually sell for — a price multiplied by a large balance of an illiquid token gives a large number that no one would pay. Treat the value column as an indication, not a quote.

Why a price can be missing

A jetton has no price in apiton when:

• it is not listed on that exchange, or has no positive price there;
• the feed has not refreshed for more than 30 minutes (then every price is missing).

apiton never substitutes 0 for an unknown price: in the API the field is absent, and on the site the value cell stays empty. Code that sums portfolio values should skip jettons without a price rather than count them as zero-valued.

Reading prices through the API

v2.Rate/JettonPrices takes up to 100 master addresses in any form (raw 0:…, EQ…, UQ…) and returns a map keyed by the address exactly as you sent it:

curl -X POST https://app.apiton.org/v2.Rate/JettonPrices \
  -H 'Content-Type: application/json' \
  -d '{"master":["EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs","EQAvlWFDxGF2lXm67y4yzC17wYKD9A0guwPkMs1gOsM__NOT"]}'

At the time of writing this returned about 0.9999 for USD₮ and 0.0005 for NOT. A master without a price is simply not in the map; an empty map is a valid answer.

Balances from v2.Address/Jettons carry the same price per row, so one call is enough for a portfolio view:

curl -X POST https://app.apiton.org/v2.Address/Jettons \
  -H 'Content-Type: application/json' \
  -d '{"address":"foundation.ton","limit":20}'

Each result has master_address, symbol, balance and, when known, price_usd. Value = balance × price_usd. This is also how the Jettons table on an address page such as UQCd…3AF4 computes its Value column.

Known jettons

Separately from prices, apiton keeps a short curated list of known jettons: established tokens from the same exchange list that are not flagged as fake, suspicious or blacklisted and have a verified symbol or at least medium liquidity. At the time of writing the list had 285 jettons.

v2.Address/Details marks such a master with "known": true and "known_source": "stonfi", and v2.Catalog/Sitemap with {"kind":"jetton"} lists them all. A jetton can have a price without being known — anyone can create a pool for any token — so "has a price" is not a sign of legitimacy; "known" is a stronger one.

Summary

• Prices come from one DEX asset list, refreshed every 3 minutes, expiring after 30.
• price_usd is per whole token, keyed by master; unknown means absent, never zero.
• DEX prices of illiquid tokens overstate what a balance is worth.
• Check the master address, not the name — see Using the apiton API with curl for keys and limits.

Want a live balance and alerts in Telegram? Send any address to @apitonBot.