Fragment API SDK Guide for Telegram Bots and Mini Apps

MyStars FaaS provides a Fragment-as-a-Service fulfillment layer for Telegram bots and Mini Apps that sell Stars and Premium. The core idea is a clean split: your product keeps the UI and order database, while pricing, recipient eligibility checks, order creation and status updates run through official Node.js (@mystars-tg/faas-sdk) and Python (mystars-faas) SDKs. The guide stresses keeping the API key server-side only, proposing a three-layer architecture of Telegram front end, your own backend, and the MyStars FaaS layer.

Code samples in TypeScript and async Python walk through a realistic order flow: fetch a live quote, verify the recipient can actually receive the product, halt before creating a bad order if not eligible, and submit the order using a stable idempotency key derived from your own local order ID to avoid duplicates on retries. The article also clarifies payment currency naming — the API enum values (ton, usdt_ton) differ from what should be shown to users (Gram, USDT on TON), a detail meant to prevent confusing payment screens.

Before launch, webhook verification is treated as mandatory: validating the raw body against the X-Faas-Signature header, deduping by order ID and status, and only applying valid state transitions to local orders — backed by a polling/reconciliation job as a safety net for missed events. A reference Python blueprint bot, built with aiohttp, Postgres, Redis, and TON Center monitoring, demonstrates how all these pieces fit together in production, and a suggested set of backend endpoints (quote, recipient-check, orders, webhook, reconcile) offers a starting skeleton for teams building their own integration.