Version 0.1.3 · Registry installation commands use exact versions.

Buy Telegram Stars with Node.js / TypeScript: safe server integration

A Node.js / TypeScript backend workflow for username checks, wallet balance, Telegram Stars/Premium gifts and 429 handling without duplicate purchase retries.

Purchase requests transmit your wallet mnemonic and Fragment session/cookie to the API operator.

Start with a public username lookup in Node.js / TypeScript. It needs no account or wallet credential. Check the publication report before installing the registry version; alternatively build the corresponding source directory.

Load the wallet mnemonic and Fragment session at runtime. Read balance first; balances are decimal strings. The sample enables purchases only with FRAGMENT_ALLOW_PURCHASES=yes and FRAGMENT_PURCHASE_KIND=stars or premium; exactly one selected gift.

Decide on one intended gift: Stars amount 50–1,000,000 or Premium duration 3/6/12. The example shows both API methods for reference, not an instruction to execute both gifts. Each purchase spends real funds.

Catch the typed flood-wait error and surface its wait hint to your job scheduler. Never automatically resubmit the purchase. After a timeout or unconfirmed transaction, reconcile wallet/recipient state before a new intentional submission.

Install

npm install fragment-donor-sdk@0.1.3

Example

// Trusted server example. Opt in and choose exactly one purchase kind.
import {
  ApiError,
  FloodWaitError,
  FragmentDonorClient,
  WalletCredentials,
} from "fragment-donor-sdk";

const allowPurchase = process.env.FRAGMENT_ALLOW_PURCHASES === "yes";
const purchaseKind = process.env.FRAGMENT_PURCHASE_KIND;
if (allowPurchase && !["stars", "premium"].includes(purchaseKind)) {
  throw new Error(
    "Set FRAGMENT_PURCHASE_KIND=stars or premium; no purchase sent",
  );
}
const client = new FragmentDonorClient();
const username = process.env.FRAGMENT_USERNAME ?? "durov";
try {
  console.log("Username:", (await client.getUserInfo(username)).username);
  if (process.env.FRAGMENT_MNEMONIC) {
    const credentials = new WalletCredentials({
      mnemonic: process.env.FRAGMENT_MNEMONIC,
      cookie: process.env.FRAGMENT_COOKIE,
      providerKey: process.env.TONCONSOLE_API_KEY,
    });
    const balance = await client.walletBalance({ credentials });
    console.log("TON:", balance.ton, "USDT:", balance.usdt_ton);
    if (allowPurchase && purchaseKind === "stars") {
      // One intentional operation; NEVER retry automatically.
      await client.buyStars(username, 50, { credentials });
    } else if (allowPurchase && purchaseKind === "premium") {
      await client.buyPremium(username, 3, { credentials });
    }
  }
} catch (error) {
  if (error instanceof FloodWaitError)
    console.log("FLOOD_WAIT seconds:", error.retryAfter);
  else if (error instanceof ApiError)
    console.log(
      error.name,
      error.status,
      "unknown purchase outcome:",
      error.purchaseOutcomeUnknown,
    );
  else throw error;
}

Continue reading

Telegram Stars API: send Stars to a username · Node.js / TypeScript SDK for Telegram Stars and Premium · Payment timeout: prevent duplicate Telegram Stars purchases

OpenAPI 3.0 · Postman collection