Fragment API SDK for Telegram Apps and Bots: A Practical Guide (Node.js & Python)

Fragment API SDK for Telegram Apps and Bots: A Practical Guide (Node.js & Python)

MyStars FaaS offers a Fragment-as-a-Service layer that simplifies Telegram commerce fulfilment. The service includes official SDKs for Node.js/TypeScript (@mystars-tg/faas-sdk) and Python (mystars-faas), with webhook verification and idempotency support.

Why This Matters

Most Telegram commerce ideas hit the same wall right after the prototype stage: the bot or Mini App itself is easy to build, but Stars and Premium fulfilment still need a dependable backend flow. Keeping the API key in a Telegram Mini App frontend is a security risk — client talks to your backend; your backend talks to MyStars. This clean architecture prevents exposure of sensitive credentials while ensuring reliable order creation, recipient checks, and payment processing.

Key Insights

• The clean architecture separates Telegram API (visible parts like bot commands, keyboards) from MyStars FaaS layer (pricing, recipient checks, fulfilment) via your own server for business logic.
• $@mystars-tg/faas-sdk$ for Node.js/TypeScript and $mystars-faas$ for Python are the official MyStars FaaS SDKs, compatible with FaaS API v1.9.0 as of this guide.
• $getPricing(…)$ gives current quotes — prices should not be hardcoded in bot UI; use it to avoid stale estimates.
• $checkRecipient(…)$ protects buyers from paying for products that can’t be fulfilled by checking eligibility before order creation.
• $idempotencyKey$ prevents duplicate orders when HTTP requests time out after server-side creation — use stable local order IDs.

Working Examples

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 };
}

# pip install mystars-faas
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",
)
done...recipient = await client.check_recipient(username, type="premium")
done...if not recipient.eligible:
done...return {"ok": False, "message": recipient.telegram_message}
done...order = await client.create_order(
type="premium",
done...recipient=username,done...months=months,done...payment_currency="usdt_ton",done...callback_url="https://your-app.example.com/webhooks/mystars",done...idempotency_key=f"local-{local_order_id}",done...)done...return {"ok": True, "quote": quote, "order": order}

Practical Applications

• • Use case (Telegram bot + Stars fulfilment): Create an end-to-end flow where users select a Stars quantity via inline buttons; your backend calls getPricing() then checkRecipient() before creating the order with idempotencyKey. -Pitfall (Hardcoding prices in bot UI): Without getPricing(), stale quotes can cause user frustration or failed payments if rates change between display and purchase.

• Use case (Premium reseller marketplace): Integrate checkRecipient() before showing buy button; if user isn’t eligible (e.g., already has Premium), stop early instead of charging them. -Pitfall (Skipping webhook verification): Without signature verification on /webhooks/mystars endpoint you risk fake status updates that could trigger erroneous fulfilments or chargebacks.

• Use case (Multi-step admin reconcile job): Run POST /api/admin/reconcile periodically as backup when webhooks miss events due to network failures at scale. -Pitfall (Ignoring expires_at field): Hardcoding payment timeout instead of reading order’s expires_at may reject valid payments if window extends beyond your static limit.

References: