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 are implemented as smart contracts that 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 (e.g., EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs for USDT)
How it works:
- Each Jetton token has ONE Master contract
- The Master contract address is the token's identifier
- All Jetton Wallets for that token are connected 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 tokens are received
- 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:
- Your TON address sends a message to YOUR Jetton Wallet
- Your Jetton Wallet sends a message to RECIPIENT's Jetton Wallet
- Balances are updated in both Jetton Wallet contracts
- 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 excess TON is automatically returned to the sender after the transaction completes
- Transfers with insufficient TON will fail on-chain
- The exact amounts vary slightly based on network conditions and message complexity
Why so much TON?
- TON's 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 Notes:
- 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:
- Prevents User Confusion: Jetton addresses look similar to regular TON addresses but have different capabilities
- Avoids Failed Transactions: Users cannot accidentally attempt to withdraw from Jetton addresses
- Simplifies Workflow: Users interact only with TON addresses, which handle all token operations
- 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
- Jetton addresses are managed automatically by the platform
V1 TON Wallets for Jetton Tokens
Important: Use v1 TON Wallets for Jetton
When interacting with Jetton tokens, using v1 TON wallets is recommended 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
- TON Documentation - Official TON blockchain documentation
- Jetton Standard (TEP-74) - Jetton token standard
- TON Viewer - Block explorer for TON