Version 0.1.3 · Registry installation commands use exact versions.

Node.js / TypeScript SDK for Telegram Stars and Premium

Install the independent Fragment Donor Node.js / TypeScript SDK, check usernames, gift Stars/Premium, and handle rate limits safely.

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

Runtime: Node.js 20+. Version 0.1.3 is published; use the exact registry command shown on this page.

The client exposes username lookup, Stars purchase, Premium gift, and wallet balance with native naming for Node.js / TypeScript. Required request bodies use form-urlencoded. Wallet balances remain decimal strings; unknown response fields are retained.

Configure a request timeout and wallet credentials on your backend. Read retries are opt-in and bounded; purchase calls never retry automatically. Review the package README for the exact constructor and error classes.

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

Source · typescript

Continue reading

Handle Telegram Stars API 429, Retry-After, and flood wait · Protect wallet credentials in API integrations · Fragment Donor API and SDK FAQ

OpenAPI 3.0 · Postman collection