Telegram Mini Apps with Stars Payments — Expert Skill
A production-grade reference for building Telegram Mini Apps (TWA) on Next.js:
@telegram-apps/sdkv3 init, native capabilities (CloudStorage, biometry, fullscreen, shareStory), server-side initData HMAC validation, grammY bot webhooks, Stars (XTR) payments, and serverless deployment. Scope is the bot + Mini App + Stars billing stack; for advanced BotFather configuration and Bot API specifics, cross-check core.telegram.org/bots/webapps and docs.telegram-mini-apps.com.
Tested version matrix (as of Jun 2026)
These versions were verified to work together. Always confirm latest at each package's releases page before pinning.
| Package / runtime | Pin used here | Notes |
|---|---|---|
| Node.js | 22 LTS or 24 LTS | Node 18 and 20 are both EOL, do not target them for new deploys. |
@telegram-apps/sdk | ^3 | v2 → v3 renamed several mount/signal APIs (see migration note below). |
@telegram-apps/sdk-react | ^3 | React bindings (useSignal, useLaunchParams). |
grammy | ^1.30 | Verify method signatures at grammy.dev; sendInvoice dropped positional provider_token in 1.24+ (Bot API 7.4 support). |
next | ^15 (App Router) | Next.js 16 is current — verify at nextjs.org; RSC/route-handler APIs unchanged for this skill. |
react / react-dom | ^19 | |
@libsql/client (Turso) | ^0.15 | Verify at github.com/tursodatabase/libsql-client-ts. |
typescript | ^5.6+ | |
| Telegram Bot API | 7.x+ | Stars/XTR, refundStarPayment, getStarTransactions. |
| Telegram WebApp platform | 8.0+ | requestFullscreen, shareStory, home-screen shortcuts require 8.0+. |
Do not confuse the two "versions". The npm package
@telegram-apps/sdk(major v3 in mid-2026) is independent of the Telegram WebApp platform version (e.g.8.0) reported in launch params. Older docs/skills saying "TMA SDK 7.x" conflated the two — there is no npm SDK 7.x.
Reference guide
Read only the references needed for the current request:
- Table of Contents: references/table-of-contents.md
- 1. Overview & Architecture: references/1-overview-architecture.md
- 2. TWA SDK Setup (v3) + v2→v3 Migration: references/2-twa-sdk-setup-v3-v2-v3-migration.md
- 3. Native Capabilities: CloudStorage, Biometry, Fullscreen, shareStory: references/3-native-capabilities-cloudstorage-biometry-fullscreen-sharestory.md
- 4. initData HMAC Validation: references/4-initdata-hmac-validation.md
- 5. Bot Setup with grammY: references/5-bot-setup-with-grammy.md
- 6. Webhook Handlers: references/6-webhook-handlers.md
- 7. Stars Payments (XTR): references/7-stars-payments-xtr.md
- 8. Deep Linking: references/8-deep-linking.md
- 9. Telegram Theme CSS Variables: references/9-telegram-theme-css-variables.md
- 10. MarkdownV2 Escaping: references/10-markdownv2-escaping.md
- 11. Database Options: references/11-database-options.md
- 12. Next.js Deployment: references/12-next-js-deployment.md
- 13. Security Hardening: references/13-security-hardening.md
- 14. Complete Example App: references/14-complete-example-app.md
- 15. Troubleshooting: references/15-troubleshooting.md
- Quick Reference: references/quick-reference.md
- Rules for the Agent: references/rules-for-the-agent.md