Jettons on TON: what they are and how to read a jetton master

On TON, fungible tokens are called jettons. USD₮, wrapped assets and thousands of community tokens all follow the same standard, TEP-74. Its design is different from the "one contract with a balance table" model you may know from other chains, and that difference explains most of what you see in a TON wallet or explorer.

Master and wallets

A jetton is made of two kinds of contracts:

• One jetton master. It holds the total supply, the admin address, the metadata and the code of the wallet contract. It does not store anybody's balance.
• One jetton wallet per holder. Every owner of a jetton gets a separate small contract that stores their balance. A transfer is a message from your jetton wallet to the recipient's jetton wallet, which is deployed automatically if it does not exist yet.

So "the address of my USD₮" is ambiguous: there is the master (the same for everybody), your regular wallet, and your jetton wallet for that token.

Reading the master

TEP-74 defines two get-methods on the master:

get_jetton_data() → (total_supply, mintable, admin_address, jetton_content, jetton_wallet_code)
get_wallet_address(owner_address) → jetton_wallet_address

• total_supply is an integer in the smallest units.
• mintable tells whether new tokens can still be minted.
• admin_address can mint and change metadata. An empty admin (addr_none) means nobody can: admin rights were renounced.
• jetton_content is the metadata cell.

get_wallet_address finds any holder's jetton wallet without scanning the chain. Contracts that cannot call get-methods can ask the master with a message instead — that is TEP-89, "discoverable" jetton wallets.

Metadata and decimals

The metadata follows the Token Data Standard, TEP-64. It is either on-chain (a dictionary stored in the contract) or off-chain (a URL to a JSON file), sometimes a mix. Typical keys: name, symbol, description, image, decimals.

decimals matters: balances on-chain are integers, and the number shown to people is balance / 10^decimals. If decimals is missing, the standard default is 9 (like TON itself); USD₮ on TON uses 6. Off-chain metadata can change if whoever controls the URL changes the file — check the master address, not the name or the logo, before trusting a token.

Reading a jetton wallet

A jetton wallet answers get_wallet_data() with (balance, owner, jetton_master, wallet_code). The jetton_master field is how you verify that a wallet really belongs to the token it claims: ask that master for get_wallet_address(owner) and compare.

Transfers are recognisable by op-codes in the message body: transfer (0x0f8a7ea5), internal_transfer (0x178d4519), transfer_notification (0x7362d09c), excesses (0xd53276db) and burn (0x595f07bc).

With the apiton API

You do not need to run get-methods by hand:

# everything about a contract: type detection plus decoded content
curl -X POST https://app.apiton.org/v2.Address/Details \
  -H 'Content-Type: application/json' \
  -d '{"address":"<jetton master address>"}'

# the jettons held by a wallet (also accepts name.ton)
curl -X POST https://app.apiton.org/v2.Address/Jettons \
  -H 'Content-Type: application/json' \
  -d '{"address":"foundation.ton","limit":20}'

Details reports the detected interfaces (jetton_master, jetton_wallet, …) and the decoded content. Jettons returns, per token, the holder's jetton wallet address, the symbol, the balance with decimals applied, the metadata and the master address. More recipes are in Using the apiton API.

In Telegram, paste any address into @apitonBot to see its balance, contract type and decoded transactions (jetton transfers included), and watch a wallet for new transfers.

Related reading

• Reading a TON address — why contract addresses are usually shown as EQ… and wallets as UQ….
• On apiton.org, the explorer pages list Telegram usernames, numbers and domains — for example usernames for sale.