school Beginner Basics

TON Wallet Integration: Non-Custodial Wallets, USDT & Jettons Architecture

verified_user TGWAY Editorial Staff • calendar_today Published Sep 11, 2026 • visibility 3,290 Views

Module 08: Bots, TMA Mini Apps & Web3 TON Ecosystem

Step 089: TON Wallet Integration: Non-Custodial Wallets, USDT & Jettons

← Prev: Step 088 Curriculum Index Next: Step 090 →

89% Complete (89/100)

The financial engine powering Telegram's Web3 economy is The Open Network (TON). Originally conceptualized by the Durov brothers and continued by an open-source developer collective, TON achieves unprecedented transaction throughput via asynchronous actor-model smart contracts and dynamic sharding. Rather than relying on clunky browser extensions or centralized custodial exchanges, Telegram users interact with non-custodial crypto wallets directly inside the app. Through the standardized TON Connect 2.0 protocol, Mini Apps and bots request cryptographic signatures, transfer native TON coins, settle payments in official Tether (USDT on TON) with near-zero gas fees, and mint or trade custom Jettons (TEP-74). In this masterclass guide, we dissect the complete architecture of TON wallet integration.

TON Wallet Integration Architecture Banner

Figure 89.1: Non-Custodial TON Wallet Architecture, Jetton Contracts & TON Connect 2.0. TELEGRAM 189 • TON CERTIFIED

1. Custodial (@wallet) vs. Non-Custodial (TON Space & Tonkeeper)

Telegram supports two distinct wallet paradigms that developers must understand before designing Web3 checkout flows:

Type A: Custodial Wallet (@wallet)

Managed Ledger & Fiat On-Ramps

Operated by third-party company TOP (The Open Platform). Users authenticate with Telegram phone credentials. Private keys are held centrally. Transfers between @wallet users occur off-chain with zero gas fees.

Best for: Novice crypto onboarding, credit card fiat purchases, peer-to-peer P2P fiat trades.
Limitation: Subject to centralized KYC restrictions and jurisdiction bans.

Type B: Non-Custodial (TON Space & Tonkeeper)

Self-Sovereign Cryptographic Seed

The user maintains absolute custody of their 24-word recovery mnemonic. Integrates directly with smart contracts, DEXs (DeDust, STON.fi), Jetton transfers, and TON Connect 2.0.

Best for: Web3 Mini Apps, DeFi staking, NFT trading, unfreezable asset ownership.
Zero Counterparty Risk: Funds can never be frozen by any corporate entity.

2. The Jetton Standard (TEP-74) & Official USDT on TON

Unlike Ethereum's ERC-20 standard where a single central contract maintains balances for all users in a monolithic table, TON's TEP-74 Jetton architecture is completely sharded:

Sharded Jetton Contract Architecture

Jetton Master Contract: Deployed once. Stores token metadata (name, ticker, decimals, logo URL, total supply) and the compiled code template for child wallets.
User Jetton Wallet Contracts: Every single token holder possesses their own independent smart contract on the blockchain. When Alice transfers USDT to Bob, Alice's Jetton Wallet contract dispatches an internal message across the network to Bob's Jetton Wallet contract.
Infinite Scalability: Because transfers do not touch a single global storage slot, millions of Jetton transactions execute concurrently across TON's sharded workchains without network congestion or fee spikes.
USDT on TON: Launched officially by Tether in April 2024. Operates natively on TON with 6 decimal places and transaction fees as low as $0.01 per transfer, completely eliminating Ethereum gas volatility.

3. Implementing TON Connect 2.0 in TypeScript

TON Connect 2.0 is the universal standard for connecting web applications to TON wallets. Below is a production React / TypeScript snippet initializing the connector and requesting a signed transaction:

        ton_connect_transaction.ts
        TypeScript / @tonconnect/ui
      

import { TonConnectUI } from '@tonconnect/ui';
import { beginCell, toNano } from '@ton/ton';

// 1. Initialize TON Connect UI with your manifest URI
const tonConnectUI = new TonConnectUI({
    manifestUrl: 'https://tgway.com/tonconnect-manifest.json'
});

// 2. Dispatch Payment Request to User's Wallet
export async function executeVipPayment(orderId: string, recipientAddress: string) {
    // Serialize message memo / comment into Bag of Cells (BoC)
    const bodyCell = beginCell()
        .storeUint(0, 32)                // 0x00000000 = Plain text comment opcode
        .storeStringTail(`ORDER-#${orderId}`)
        .endCell();

    const transaction = {
        validUntil: Math.floor(Date.now() / 1000) + 600, // 10 minutes expiry
        messages: [
            {
                address: recipientAddress,       // Destination TON wallet address
                amount: toNano('2.5').toString(), // 2.5 TON in nanotons (10^9)
                payload: bodyCell.toBoc().toString('base64')
            }
        ]
    };

    try {
        const result = await tonConnectUI.sendTransaction(transaction);
        console.log('Transaction signed! BOC Hash:', result.boc);
        return result.boc;
    } catch (error) {
        console.error('User rejected wallet signature:', error);
        throw error;
    }
}

Interactive Lab Simulator

TON Connect 2.0 Wallet & Jetton Transfer Simulator

ENGINE: TON_CONNECT_V2_EMU

Transaction Parameters

Select Connected Wallet:

Transfer Asset:

Transfer Amount:

Memo / Comment (BoC Payload):

TON Connect 2.0 Sign Request AWAITING SIGNATURE

Amount: 5.0 TON

Est. Network Gas: 0.005 TON (~$0.03)

BoC Cell: te6ccgEBAQE...

            TON BLOCKCHAIN STREAM
            SYNCED
          
            [TON-NET] Connected to TON Mainnet lite-server. Height: #39,418,204

5. Complete System Architecture Blueprint: TON Web3 Infrastructure

Inspect the comprehensive architectural infographic detailing TON Connect 2.0 communication bridges, TEP-74 Jetton contract hierarchies, Bag of Cells serialization, and non-custodial key custody:

TON Blockchain & Wallet Integration Architecture Blueprint

Click to Enlarge High-Res Blueprint

Figure 89.2: Full 2:3 Masterclass Infographic Summary. Click to inspect high-resolution vector details.

6. Asset Comparison: Native TON vs. USDT-TON vs. Custom Jetton vs. Telegram Stars

Asset	Protocol Standard	Decimals	Average Gas Fee	Settlement Finality	Custody Type
Native TON	L1 Native Coin	9 (nanoTON)	~0.005 TON ($0.03)	~5 seconds	Non-Custodial
USDT on TON	TEP-74 Jetton	6 (Units)	~0.01 TON ($0.06)	~5 seconds	Non-Custodial
Custom Jetton (TEP-74)	TEP-74 Jetton	Custom (Typically 9)	~0.05 TON ($0.30)	~5 seconds	Non-Custodial
Telegram Stars	Internal Virtual Unit	0 (Integer)	Zero Gas (In-App)	Instant (<100ms)	Custodial (Telegram)

7. Frequently Asked Questions (FAQ)

Q1: What is the difference between bounceable (EQ...) and non-bounceable (UQ...) addresses?

In TON, every address has both formats. A bounceable address (prefixed with EQ) instructs the network that if the destination contract does not exist or fails to process the message, the funds must automatically bounce back to the sender. A non-bounceable address (prefixed with UQ) allows newly created wallets that have not yet sent an outbound transaction (uninitialized state) to receive funds safely without triggering a premature bounce.

Q2: How do I verify on my backend that a user actually completed a TON transaction?

When tonConnectUI.sendTransaction succeeds, it returns a base64 encoded external message BoC. To verify settlement, query the TON Center API or a local Lite Client using getTransactions for your receiving wallet address. Inspect the incoming transactions for the unique order ID stored inside the comment memo cell, confirm the transferred amount matches the invoice, and verify that the transaction is finalized in a masterchain block.

Q3: Can a user pay with USDT on TON if they have zero TON for gas?

Yes, under modern TON wallet features (such as Tonkeeper Battery and Telegram Wallet gasless USDT), wallets support sponsored gas. The wallet automatically deducts a tiny fraction of USDT to cover network fees or sponsors the fee on behalf of the user, enabling complete gas-free onboarding for non-crypto natives.

Q4: Where should I host my tonconnect-manifest.json?

Your manifest must be hosted over public HTTPS with CORS headers enabled (Access-Control-Allow-Origin: *). It defines your application's url, name, iconUrl (180x180 PNG), and privacy policy URL. Wallets fetch this manifest during handshake to display your brand icon and verified domain to the user.

Q5: What happens if a user closes the wallet app before signing?

The TON Connect bridge maintains an active SSE session. If the user dismisses the sign request or if the validUntil timestamp expires, the promise returned by sendTransaction rejects with a UserRejectsError. Your frontend code should catch this rejection, release any inventory holds, and prompt the user with a retry button.

MODULE 08 • WEB3 MASTERY EXPANDING Next Architecture Milestone: Step 090

Ready for Step 090: Fragment Marketplace: Anonymous Virtual Numbers (+888) & Usernames

With non-custodial wallets and TON blockchain transactions mastered, explore Telegram's premier decentralized asset exchange: Fragment (fragment.com). Learn how high-value usernames, rare channel handles, and +888 Anonymous Virtual Numbers are minted as TON NFTs and traded with 100% cryptographic sovereignty.

Continue to Step 090 (Fragment Marketplace Architecture) →

← Prev: [Telegram 188] Telegram Mini Apps (TMA) Architecture: WebApp SDK & Viewports Next: [Telegram 190] Fragment Marketplace: Anonymous Virtual Numbers & Usernames →