Guides

TON Tokens (Jetton)

Overview

Coins are native to a blockchain, such as Bitcoin or Ether. Tokens represent an asset on someone else's blockchain. Jetton tokens are assets on The Open Network (TON) blockchain, following the Jetton Token Standard (similar to ERC-20 on Ethereum or BEP-20 on BSC).

What are Jettons?

Jettons are fungible tokens on the TON blockchain. Unlike native TON coins, Jettons implement the smart contract model to manage token balances and transfers across multiple wallet contracts.

Key Characteristics

  • Distributed Architecture: Each user has their own Jetton Wallet contract for each token type
  • Master Contract: A Jetton Master contract manages the overall token supply and creates individual Jetton Wallets
  • Gas Fees: All Jetton transactions require native TON for gas fees (~0.1 TON per transfer, with excess returned)
  • Smart Contract Based: Jetton transfers involve smart contract calls, not simple value transfers
  • Asynchronous Messaging: A single Jetton transfer involves 4 on-chain messages

How Jettons Differ from Native TON

Aspect Native TON Jetton Tokens
Balance Storage Stored in TON address Stored in separate Jetton Wallet contract
Deployment Address exists immediately Jetton Wallet deployed on first receive
Gas Model Simple fee calculation Multi-message flow with excess return
Per Token N/A - only one native coin Each token type needs separate Jetton Wallet
Transfer Direct address-to-address Message flow through Jetton Wallet contracts

Supported Jetton Tokens

BitGo supported Jetton tokens can be accessed on the Mainnet:

Mainnet Tokens

Token Name Token ID Precision Master Contract Address Token Details
USDT ton:usdt 6 EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs TON USDT

Jetton Architecture

Understanding the Two-Contract System

Unlike simple token systems, Jettons on TON use a distributed architecture with two types of contracts:

1. Jetton Master Contract

The Jetton Master contract is the central "source of truth" for a token that:

  • Manages Token Metadata: Stores the token name, symbol, decimals, and total supply
  • Mints New Tokens: Can create new tokens (if minting is enabled)
  • Deploys Jetton Wallets: When someone receives a token for the first time, it helps create their personal Jetton Wallet
  • Provides Information: Allows querying of total supply and individual wallet addresses

Important

The Jetton Master does NOT hold user balances. It only coordinates and provides information.

Master Contract Address: A unique TON address (for example, EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs for USDT)

How it works:

  • Each Jetton token has ONE Master contract
  • The Master contract address is the token identifier
  • All Jetton Wallets for that token connect to this Master

2. Jetton Wallet Contracts

For each user and each Jetton token, there exists a separate Jetton Wallet contract that:

  • Holds Token Balance: Your actual token balance lives in YOUR Jetton Wallet contract
  • Processes Transfers: Handles sending and receiving tokens
  • Communicates with Other Jetton Wallets: Sends internal transfer messages to other users' Jetton Wallets
  • Notifies Owner: Sends notifications to your TON address when your wallet receives tokens
  • Auto-Deployment: Automatically created when you receive tokens for the first time

Jetton Wallet Address: Deterministically calculated from:

Owner's TON Address + Jetton Master Contract Address → Unique Jetton Wallet Address

This means:

  • Alice's USDT Jetton Wallet address is different from Bob's USDT Jetton Wallet
  • Alice's USDT Jetton Wallet is different from Alice's OTHER_TOKEN Jetton Wallet

Key Point: You don't "transfer tokens" in the traditional sense. Instead:

  1. Your TON address sends a message to YOUR Jetton Wallet
  2. Your Jetton Wallet sends a message to RECIPIENT's Jetton Wallet
  3. Both Jetton Wallet contracts update their balances
  4. Recipient's Jetton Wallet notifies the recipient's TON address

Address Relationship Diagram

                    ╔═════════════════════════════════════╗
                    ║        Jetton Master Contract       ║
                    ║   (e.g., TON USDT Master Contract)  ║
                    ║                                     ║
                    ║  • Manages total supply             ║
                    ║  • Creates Jetton Wallets           ║
                    ║  • Stores token metadata            ║
                    ╚═══════════════════╦═════════════════╝
                                        ║
                                        ║ Creates/Manages
                                        ║
                 ┌──────────────────────┼──────────────────────┐
                 │                      │                      │
                 ▼                      ▼                      ▼
         ┌───────────────┐      ┌───────────────┐     ┌───────────────┐
         │ Jetton Wallet │      │ Jetton Wallet │     │ Jetton Wallet │
         │   (User A)    │      │   (User B)    │     │   (User C)    │
         ├───────────────┤      ├───────────────┤     ├───────────────┤
         │ Owner:        │      │ Owner:        │     │ Owner:        │
         │  TON Addr A   │      │  TON Addr B   │     │  TON Addr C   │
         │               │      │               │     │               │
         │ Balance:      │      │ Balance:      │     │ Balance:      │
         │  1000 USDT    │      │  500 USDT     │     │  2000 USDT    │
         └───────────────┘      └───────────────┘     └───────────────┘

Jetton Transaction Flow

Token Transfer Flow

A Jetton transfer involves 4 on-chain messages between contracts:

┌─────────────┐         ┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│      A      │  (1)    │      B      │  (2)    │      C      │  (4)    │      D      │
│   Sender    │────────>│   Sender    │────────>│  Recipient  │────────>│  Recipient  │
│     TON     │  0.1    │   Jetton    │ 0.092   │   Jetton    │ 0.00001 │     TON     │
│   Address   │  TON    │   Wallet    │  TON    │   Wallet    │  TON    │   Address   │
└─────────────┘         └─────────────┘         └─────────────┘         └─────────────┘
       ▲                                                │
       │                                                │
       │                  (3) Excess Return             │
       │                      0.079 TON                 │
       └────────────────────────────────────────────────┘

Flow Steps:
  (1) Sender initiates transfer → Sender's Jetton Wallet
      • 0.1 TON attached
      
  (2) Sender's Jetton Wallet → Recipient's Jetton Wallet
      • Jetton Internal Transfer where actual jetton transfer happens
      • 0.092 TON is also sent to cover fees
      
  (3) Recipient's Jetton Wallet → Sender
      • Excess refund: ~0.079 TON
      
  (4) Recipient's Jetton Wallet → Recipient's TON Address
      • Notify message: 0.00001 TON

Gas Fee Structure

Jetton transfers require native TON for gas fees. Here's how the fees break down:

Component Typical Amount Purpose
Actual Gas Consumed ~0.015 TON Used for computation and storage fees
Excess Returned ~0.079 TON Unused TON automatically returned to sender
Forward TON Amount ~0.0001 TON Forwarded to recipient for notification processing
Initial TON Attached ~0.1 TON Total TON sent with the transfer message
Notification Fee ~0.00001 TON Small amount sent with notification

Important Notes:

  • You need approximately 0.1 TON to initiate a Jetton transfer
  • The network automatically returns excess TON to the sender after the transaction completes
  • Transfers with insufficient TON fail on-chain
  • The exact amounts vary slightly based on network conditions and message complexity

Why so much TON?

  • TON transaction model requires upfront payment for worst-case gas usage
  • The system automatically calculates what wasn't used and returns it
  • This prevents transactions from running out of gas mid-execution

Important

  • Your Jetton Wallet deploys automatically on first receive
  • Each token type requires a separate Jetton Wallet

Jetton Addresses on BitGo

Understanding Jetton Addresses

When working with Jetton tokens on BitGo, it's important to understand how Jetton addresses function:

What are Jetton Addresses?

  • Jetton addresses are the smart contract addresses of individual Jetton Wallet contracts
  • Each user has a unique Jetton Wallet contract address for each token type they hold
  • These addresses are distinct from the user's main TON address

Creating Child Jetton Addresses

  • Users can create child Jetton addresses derived from their Jetton Wallet addresses
  • These child addresses follow the same hierarchical structure as TON addresses
  • Each child address represents a separate Jetton Wallet contract instance

Important Limitations

Withdrawal Restrictions

  • Withdrawals from Jetton addresses are NOT possible
  • Jetton Wallet contracts can only transfer tokens through the standard Jetton transfer flow
  • All withdrawals must be initiated from the main TON address, not from Jetton addresses

Why Jetton Addresses are Hidden on BitGo

For security and user experience reasons, BitGo keeps Jetton addresses hidden from the platform interface:

  1. Prevents User Confusion: Jetton addresses look similar to regular TON addresses but have different capabilities
  2. Avoids Failed Transactions: Users cannot accidentally attempt to withdraw from Jetton addresses
  3. Simplifies Workflow: Users interact only with TON addresses, which handle all token operations
  4. Reduces Errors: Prevents sending funds to the wrong address type

Best Practices

  • Always use your main TON address for deposits and withdrawals
  • Do not attempt to send funds directly to or from Jetton Wallet addresses
  • The platform manages Jetton addresses automatically

V1 TON Wallets for Jetton Tokens

Important

Use v1 TON Wallets for Jetton

When interacting with Jetton tokens, we recommend using v1 TON wallets whose addresses have the format:

UQ...........?memoId=0

Benefits of v1 TON Wallets:

  • No Bounce Transactions: Eliminates failed transactions that bounce back
  • No Consolidation Needed: Simplifies fund management by removing the need to consolidate balances to the root address
  • Cost Savings: Saves transaction fees since consolidation is not required
  • Enhanced Reliability: Provides a more stable experience for Jetton token operations

Using v1 TON wallets ensures optimal performance and compatibility when working with Jetton tokens on BitGo.

Additional Resources