@core-ease/fragment

Unofficial TypeScript client for Fragment.com — buy Telegram Stars, gift Telegram Premium, and top up a Telegram Ads (TON) balance for any Telegram username. Every purchase is paid for from your own TON wallet via a mnemonic seed phrase, and requires a logged-in Fragment session (cookies).

Features

| Method | Description | |---|---| | client.purchaseStars(username, amount) | Send Telegram Stars to a Telegram username | | client.purchasePremium(username, months) | Gift Telegram Premium (3, 6, or 12 months) | | client.topupTon(username, amount) | Top up a username's Telegram Ads (TON) balance | | client.getWallet() | Read your wallet address / state / TON balance |

Install

npm install
npm run build

Core dependencies: @ton/core, @ton/crypto, @ton/ton.

Usage

Log in to fragment.com in a browser, then copy these four cookies from devtools (Application → Cookies): stel_ssid, stel_dt, stel_token, stel_ton_token.

import { FragmentClient } from "@core-ease/fragment";

const client = new FragmentClient({
  seed: "word1 word2 ... word24",
  walletVersion: "V5R1",
  cookies: {
    stel_ssid: "...",
    stel_dt: "...",
    stel_token: "...",
    stel_ton_token: "...",
  },
});

await client.purchaseStars("username", 100);
await client.purchasePremium("username", 3);
await client.topupTon("username", 5);

cookies also accepts a raw "k=v; k2=v2" string or a JSON string.

Errors

All errors extend FragmentBaseError:

• ConfigError — invalid input (seed length, amount, months, payment method)
• CookieError — missing/invalid Fragment cookies
• FragmentPageError / FragmentAPIError — Fragment request failed
• UserNotFoundError — username not found on Fragment
• VerificationError — account requires KYC on Fragment
• WalletError — invalid seed or insufficient TON balance
• ProxyError — tonapi.io unreachable
• TransactionError / ConfirmationTimeout — broadcast failed or confirmation timed out

import { UserNotFoundError, WalletError } from "@core-ease/fragment";

try {
  await client.purchaseStars("someuser", 100);
} catch (e) {
  if (e instanceof UserNotFoundError) {
    // handle unknown username
  } else if (e instanceof WalletError) {
    // handle insufficient balance
  } else {
    throw e;
  }
}

Project structure

src/
  client.ts              FragmentClient
  types.ts                Public types
  errors.ts                Error classes
  constants.ts               Fragment URLs, headers, limits
  utils/
    http.ts                  Fragment HTTP calls
    wallet.ts                TON wallet: balance/seqno/sign/broadcast/confirm
  methods/
    purchaseStars.ts
    purchasePremium.ts
    topupTon.ts

Each Fragment flow (Stars / Premium / TON topup) follows the same 5 steps: resolve recipient → init request → get transaction link → sign & broadcast via executeTransaction → confirm via client.confirmRequest. To adapt to a Fragment API change, only the relevant method files under src/methods/ need updating — client.ts, utils/http.ts, and utils/wallet.ts stay untouched.