What is a Telegram Mini App and what APIs does it use?

A Telegram Mini App (TWA) is a web app that runs inside Telegram's 800M+ user base. It uses the Telegram Web App API with functions like `tg.ready()`, `tg.expand()`, `MainButton`, `BackButton`, `themeParams`, and `HapticFeedback` to integrate with Telegram's native interface.

How do I add TON blockchain wallet support to a Telegram Mini App?

Use TON Connect via the `@tonconnect/ui-react` library to enable wallet connection and TON transactions. You'll need to include a required `tonconnect-manifest.json` file and test on real devices with wallets like Tonkeeper or OpenMask, as TON Connect can fail on mobile due to manifest, HTTPS, or deep-linking issues.

Why is server-side initData validation critical, and how do I do it?

Trusting `initDataUnsafe` directly on the backend is a HIGH-severity security vulnerability that allows user spoofing and data tampering. Validate it server-side using HMAC-SHA256 hash verification against your bot token.

What are common performance issues in Telegram Mini Apps?

Slow or janky apps typically result from large bundle sizes, missing code splitting, or lack of lazy loading. Use native Telegram UI components like `MainButton` instead of custom buttons to maintain expected UX conventions and avoid performance degradation.

Skill

Build Telegram Mini Apps with TON Integration

Name: Telegram Mini App
Availability: OnlineOnly
Author: Antigravity

Builds Telegram Mini Apps (TWA): Web App API, TON Connect payments, viral mechanics, and initData security validation.

Get skill

Works with telegramton

Antigravity

Own this? Claim it

Spark score

out of 100

Updated last month

Version 13.1.0

Add to Favorites

Why it matters

Develop engaging Telegram Mini Apps that leverage the TON ecosystem for payments, authentication, and viral growth, reaching over 800 million users.

Outcomes

What it gets done

Integrate Telegram Web App API for native-like experiences.

Implement TON Connect for seamless crypto wallet integration.

Design and build viral mechanics for user acquisition and retention.

Develop secure payment flows using TON blockchain and Telegram Stars.

Install

Add it to your toolbox

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/ag-telegram-mini-app | bash

Overview

Telegram Mini App

Covers building Telegram Mini Apps (TWA): the Telegram Web App API, TON Connect wallet payments, monetization via Telegram Stars/TON, viral mechanics, and a security checklist centered on server-side initData validation. Use when building a new Mini App, integrating TON Connect, planning monetization, or auditing an existing Mini App for the HIGH-severity missing initData validation vulnerability.

What it does

This skill covers building Telegram Mini Apps (TWA) - web apps running inside Telegram's 800M+ user base - spanning the Telegram Web App API (tg.ready(), tg.expand(), initDataUnsafe.user, MainButton, BackButton, themeParams, HapticFeedback), TON blockchain integration via TON Connect (wallet connection, sending TON transactions, the required tonconnect-manifest.json), monetization (TON payments, in-app purchases, Telegram Ads, referral programs, NFT sales, and the newer Telegram Stars currency XTR for invoices), and viral/retention mechanics (referral share links via tg.openTelegramLink, daily rewards, streak bonuses, leaderboards).

It documents a set of "sharp edges" with severity ratings and fixes: not validating initData server-side (HIGH - initData can be spoofed, enabling user impersonation and data tampering; fix is HMAC-SHA256 hash verification against the bot token), TON Connect failing on mobile (HIGH - usually a manifest/HTTPS/deep-linking issue, test on real devices with Tonkeeper/OpenMask), a slow/janky app (MEDIUM - bundle size, code splitting, lazy loading), and using custom buttons instead of the native MainButton (MEDIUM - breaks the expected Telegram UX convention).

When to use - and when NOT to

Use this skill when starting a new Mini App, integrating TON Connect for a Web3/DeFi app, planning Mini App monetization, or designing UX that follows Telegram's own conventions (MainButton, BackButton, theme adaptation, haptics) rather than generic web patterns. It delegates related concerns: bot command/handler logic to telegram-bot-builder, smart-contract/blockchain depth to blockchain-defi, general frontend framework questions to frontend, viral/referral mechanics to viral-generator-builder, and game mechanics to gamification-loops.

Critically, do not skip server-side initData validation - trusting initDataUnsafe directly on the backend is an explicitly flagged HIGH-severity security vulnerability that allows spoofing and impersonation.

Inputs and outputs

Input is a Mini App concept, feature (payments, wallet connection, viral mechanic), or an existing Mini App to audit for the listed sharp edges. Output is working code - HTML/React setup calling the Telegram Web App script, TON Connect wallet UI, Stars-based invoice code, or a Node.js validateInitData function - plus, for audits, severity-rated findings with concrete fixes.

npm install @tonconnect/ui-react

Integrations

Built on the Telegram Web App API (telegram-web-app.js), TON Connect (@tonconnect/ui-react) for TON blockchain wallet interactions, and Telegram's native Payments/Stars system for monetization. Composes with telegram-bot-builder (bot entry point), blockchain-defi (deeper TON/DeFi logic), frontend, viral-generator-builder, and gamification-loops in workflows like a tap-to-earn game or a DeFi swap/stake Mini App.

Who it's for

Developers building Telegram Mini Apps - games, DeFi tools, utilities, or social apps - who need both the platform-specific UX conventions and the security fundamentals (initData validation) that generic web app knowledge doesn't cover.

FAQ

Common questions

Discussion