Developing Telegram Mini App for DEX
The TON ecosystem grew unusually fast in 2024: Telegram opened Mini Apps to 900M+ users, TON became top-5 by DAU in DeFi. A typical DEX on TON (StonFi, DeDust) is not a Uniswap clone, it's a different architecture: asynchronous messages instead of synchronous calls, account-based model instead of contract-centric. Telegram Mini App on top — a separate complexity layer with its own constraints.
DEX on TON Specifics: Why It's Not Like Ethereum
Asynchronous Transactions
On Ethereum, swap() is atomic: either everything executed or reversal. On TON each contract is a separate actor, messages between them are async. Swap on StonFi looks like:
- User sends jetton transfer with op-code
0xf8a7ea5to LP Pool - LP Pool processes message, sends output jetton back
- If something went wrong — bounced message returns original tokens
This flow takes 3-5 seconds and several blocks. UI should reflect this: not a 5-second spinner, but explicit state "transaction sent, awaiting confirmation". Poll transaction status via TON API (/v2/transactions/{hash}) every 1-2 seconds.
TON Connect vs Classic Wallets
TON Connect is wallet connection protocol, WalletConnect analog for TON. In Telegram Mini App context there's a nuance: Tonkeeper, MyTonWallet, and built-in Telegram Wallet all implement TON Connect but with different capabilities.
Built-in Telegram Wallet (via window.Telegram.WebApp.openInvoice) only works for TON transfers, not jetton operations. For DEX swaps need external wallet via @tonconnect/ui-react. This means deep link to mobile wallet app — additional UX step you need to explain.
Jetton Addresses and Friendly Address Format
In TON there's no global token address — each user has their own jetton wallet address (derived from master jetton contract + owner address). Before displaying balance or swapping, get user's jetton wallet address:
const jettonMaster = Address.parse(USDT_MASTER_ADDRESS);
const jettonWalletAddress = await tonClient.runMethod(
jettonMaster,
'get_wallet_address',
[{ type: 'slice', cell: beginCell().storeAddress(userAddress).endCell() }]
);
This is async call per token, needs caching. Without cache — UI lags on balance loading.
Mini App Architecture
Technical Stack
Frontend: React 18 + TypeScript + Tailwind CSS. @tonconnect/ui-react for wallet connection. @ton/ton for blockchain interaction. @ston-fi/sdk for StonFi router or direct DeDust contract calls via custom message builders.
TON API: TonCenter API v2 (free, rate-limited) or TON API from ton.access.tech (better for production). The Open Network has official @ton-api/client.
Telegram WebApp SDK: window.Telegram.WebApp for theme, haptic feedback, BackButton, MainButton.
Telegram-Specific UX
Telegram Mini App runs in webview with limited space. Key patterns:
MainButton — native Telegram button at bottom. Use for main action (Swap, Confirm), don't render custom button on top.
WebApp.MainButton.setText('Confirm Swap');
WebApp.MainButton.onClick(() => executeSwap());
WebApp.MainButton.show();
HapticFeedback — on successful transaction: WebApp.HapticFeedback.notificationOccurred('success'). On error: 'error'. Small thing, but noticeably improves app feel.
Theme: WebApp.themeParams returns Telegram theme colors. App should adapt to user's dark/light theme, not fix its own.
BackButton: on navigation deeper (transaction details, token selection) — show WebApp.BackButton, on return — hide.
Price Charts
To display price chart inside Mini App — TradingView Lightweight Charts (minimal bundle ~50KB). Data: OHLCV from StonFi subgraph or TON API historical prices. Update via WebSocket if real-time needed, polling every 30 seconds if near-real-time enough.
Important: charts shouldn't be interactive in mobile webview — pinch-to-zoom conflicts with native Telegram scroll. Only static chart with tap to view specific candle.
Liquidity Management
If Mini App includes LP functionality (add/remove liquidity), display current pool share and impermanent loss. IL calculated off-chain:
IL% = 2 * sqrt(price_ratio) / (1 + price_ratio) - 1
Where price_ratio = current_price / entry_price. When IL > 5% — alert user.
Work Process
Design and Flow (3-5 days). Figma prototype, define supported operations (swap / LP / history).
Frontend development (1.5-2 weeks). Wallet connection, token list, swap interface, transaction history.
Blockchain integration (1 week). StonFi/DeDust message building, transaction submission, status polling.
Testing (3-5 days). Test in Telegram on real devices (iOS + Android — webview behavior differs). Test on TON testnet.
Deployment. Mini App is static site on HTTPS. Vercel/Netlify + domain. Register via BotFather (/newapp).
Timeline Guidelines
MVP with basic swap and balances: 2-3 weeks. Full DEX Mini App with LP, history and charts: 4-6 weeks.