Fragment API SDK Guide for Telegram Apps and Bots

Most Telegram commerce ideas hit the same wall after the prototype: the bot or Mini App is easy to build, but Stars and Premium fulfilment still need a dependable backend flow. That is why developers search for a Fragment API.

MyStars FaaS gives you that missing layer. FaaS means Fragment as a Service: your Telegram product keeps the user experience and order database, while MyStars exposes the fulfilment workflow through an API, official SDKs, and signed status updates.

Use this guide when you want to wire a real Telegram app, bot, marketplace, creator tool, or reseller flow — not just read another API overview.

The clean architecture: Telegram API in front, Fragment API behind it

Keep the boundary simple.

Your Telegram API layer handles the parts users can see: bot commands, inline keyboards, Mini App screens, order cards, messages, and support replies.

Your server layer owns your business logic: local orders, margin, fraud rules, admin controls, database writes, and support evidence.

The MyStars FaaS layer handles the Fragment as a Service workflow: pricing, recipient checks, order creation, payment instructions, and fulfilment status.

That separation is important for security. Do not put the MyStars API key in a Telegram Mini App frontend. The client should talk to your backend; your backend should talk to MyStars.

Install the SDK for your stack

For Node.js and TypeScript backends, use the official @mystars-tg/faas-sdk:

npm install @mystars-tg/faas-sdk

For Python backends, use the official mystars-faas package:

pip install mystars-faas

Both packages are published as official MyStars FaaS SDKs and point builders back to the interactive API documentation. The current package docs describe compatibility with FaaS API v1.9.0, which is useful when you are checking SDK examples against the API reference.

Build the first backend route in TypeScript

The first route should not try to do everything. Start with a server-only action that quotes, checks the recipient, and creates one fulfilment order from your own local order ID.

Before the code, here is the plain-English version of what it does:

• creates a MyStars client on the backend using MYSTARS_API_KEY;
• asks MyStars for the current price of the selected Stars quantity;
• checks whether the Telegram username can receive the product;
• stops early if the recipient is not eligible, instead of creating a bad order;
• creates the fulfilment order with your own stable localOrderId as the basis for idempotency;
• returns the quote and the MyStars order object so your app can store and show the payment instruction.

import { MyStarsClient } from "@mystars-tg/faas-sdk";

const client = MyStarsClient.production(process.env.MYSTARS_API_KEY!);

export async function createStarsOrder(input: {
  username: string;
  quantity: number;
  localOrderId: string;
}) {
  const quote = await client.getPricing({
    type: "stars",
    quantity: input.quantity,
    payment_currency: "ton",
  });

  const recipient = await client.checkRecipient({
    type: "stars",
    recipient: { username: input.username },
  });

  if (!recipient.eligible) {
    return { ok: false, message: recipient.telegram_message };
  }

  const order = await client.createOrder(
    {
      type: "stars",
      recipient: { username: input.username },
      quantity: input.quantity,
      payment_currency: "ton",
      callback_url: "https://your-app.example.com/webhooks/mystars",
    },
    { idempotencyKey: `local-${input.localOrderId}` },
  );

  return { ok: true, quote, order };
}

The important part is the idempotency key. Use something stable from your own system. If the HTTP request times out after the order was created server-side, retry with the same key instead of making a duplicate.

A few lines deserve extra attention:

• MyStarsClient.production(...) means the request goes to the live MyStars API, so use a test/local order in your own system until you are ready for real traffic.
• getPricing(...) gives your backend a current quote. Do not hardcode prices in the bot UI.
• payment_currency: "ton" is the API enum/name for the native payment route in this SDK example. In your product UI, label that route as Gram or Gram (ex. TON). Keep TON for the blockchain/network name.
• checkRecipient(...) protects the buyer from paying for a username or product that cannot be fulfilled.
• callback_url is where MyStars can send order status updates after creation.
• idempotencyKey is the duplicate-order guard. It should come from your database order, not from a random value generated in the browser.

Build the same flow in async Python

Python teams usually want async code because their Telegram bot framework is already async. The Python SDK supports that directly.

This example does the same job as the TypeScript route, but in Python:

• opens an async MyStars client for the duration of the request;
• asks for a Premium quote in usdt_ton;
• checks the recipient before order creation;
• returns a safe error message if the recipient cannot receive Premium;
• creates the order with a callback URL for status updates;
• returns the quote and order so your bot can store them and show the next step to the user.

from mystars_faas import AsyncMyStarsClient

async def create_premium_order(username: str, months: int, local_order_id: str):
    async with AsyncMyStarsClient.production(MYSTARS_API_KEY) as client:
        quote = await client.get_pricing(
            type="premium",
            months=months,
            payment_currency="usdt_ton",
        )

        recipient = await client.check_recipient(username, type="premium")
        if not recipient.eligible:
            return {"ok": False, "message": recipient.telegram_message}

        order = await client.create_order(
            type="premium",
            recipient=username,
            months=months,
            payment_currency="usdt_ton",
            callback_url="https://your-app.example.com/webhooks/mystars",
            idempotency_key=f"local-{local_order_id}",
        )

        return {"ok": True, "quote": quote, "order": order}

When you move this into production, use exact money handling, keep the API key in an environment variable, and store the payment instruction exactly as returned. If the instruction includes a memo/comment, treat it as data, not copy you can rewrite.

For a less experienced developer, the key idea is this: the code example is not a full bot. It is the backend part your bot calls when the user has already picked a product. The Telegram bot still needs its own handlers, buttons, database writes, and user messages around this function.

Add webhook verification before launch

A Fragment API-style integration is not finished when order creation works. Your app also needs a trustworthy status path.

Minimum webhook handler:

1. Receive the raw request body.
2. Read the X-Faas-Signature header.
3. Verify the signature with your webhook secret.
4. Dedupe by MyStars order ID and status.
5. Update your local order only if the transition is valid.
6. Notify the user through your Telegram bot or Mini App.

The TypeScript SDK documents webhook helpers such as constructEvent, Express middleware, and Fastify support. The Python SDK includes WebhookVerifier and integrations for common Python web frameworks.

Keep a polling or reconcile job as a backup. Webhooks are the fast path; reconciliation is what saves you when a network edge case appears at 3 a.m.

Use the blueprint bot as a working reference

The MyStars Python blueprint bot is the best source when you want to see the moving parts together. It uses mystars-faas==0.1.3 for fulfilment, an aiohttp server for health checks and MyStars webhooks, Postgres and Redis for state, TON Center monitoring for on-chain payments, and admin commands for margin and reconciliation.

Do not treat the blueprint as a brand template. Treat it as an engineering map:

• where to create the local order;
• where to call recipient checks;
• where to apply margin;
• where to monitor payment;
• where to call fulfilment;
• where to edit the Telegram order card after a terminal status.

The MyStars GitHub account also publishes the SDK repositories, so you can inspect source, examples, and package structure when you need to debug deeper than a README.

Backend endpoints to create in your own app

A small production-grade integration usually starts with these routes:

POST /api/faas/quote
POST /api/faas/recipient-check
POST /api/orders
POST /webhooks/mystars
GET  /api/orders/:id
POST /api/admin/reconcile

The Telegram bot or Mini App should call your own /api/orders route, not MyStars directly. Your route can then validate the user, create a local order, call the SDK, store the returned fulfilment order, and send back only the safe fields your client needs.

Payment details users must not guess

If your product shows a payment screen, be precise. For MyStars flows, USDT means USDT on TON. Other USDT networks are not interchangeable. For the native route, current API examples can still use payment_currency: "ton"; buyer-facing copy should use Gram / GRAM (ex. TON) for the token and TON for the network.

Read the order’s expires_at field instead of hardcoding a payment timeout. The docs note that the payment window was extended to 1 hour, and expires_at remains the source of truth.

What to test before real traffic

Run these checks before sending users into the flow:

• one Stars order and one Premium order;
• one ineligible recipient path;
• retrying order creation with the same idempotency key;
• valid and invalid webhook signatures;
• duplicated webhook event delivery;
• expired order handling;
• support evidence: username, local order ID, MyStars order ID, payment hash, memo/comment, and status;
• admin-only access for margin, reconcile, refund, broadcast, and manual fulfilment commands.

This is the unglamorous part, but it is what makes a Telegram Stars bot feel reliable instead of experimental.

FAQ

Is this a direct public Fragment API?

MyStars FaaS is a Fragment as a Service layer. Your app integrates with MyStars APIs and SDKs, while MyStars handles the fulfilment workflow behind that interface.

Can I use it from a Telegram Mini App?

Yes. Keep the API key on your backend. The Mini App should call your server, and your server should call MyStars FaaS.

Which package should I start with?

Use @mystars-tg/faas-sdk for Node.js and TypeScript. Use mystars-faas for Python and async Telegram bots.

Do I need the blueprint bot?

No, but it is helpful if you are building a reseller-style bot with payments, admin commands, reconciliation, and status updates.

What is the safest first milestone?

Build one end-to-end test: quote → recipient check → local order → MyStars order → verified webhook or polling update. After that works, add margin, refund policy, admin tools, and support workflows.

For the API reference, SDK links, and current contract notes, start with the MyStars docs.