fragment-tg

The JavaScript SDK for Fragment.com.

Buy Stars, gift Premium, bid on auctions, manage usernames, read login codes — everything Fragment does, from code.

Zero dependencies. Works with any TON wallet.

Install

npm install fragment-tg

Node.js 18+

Usage

import { Fragment } from 'fragment-tg';

const fragment = new Fragment({
  cookies: {
    stel_dt: '-240',
    stel_ssid: '...',
    stel_token: '...',
    stel_ton_token: '...',
  },
});

// Search auctions
const results = await fragment.searchAuctions('crypto');

// List your usernames
const usernames = await fragment.assets.listAll({ type: 'usernames' });

// Assign a username to your account
await fragment.assignUsername('coolname', targetToken);

// Get a login code for an owned number
const { code } = await fragment.getLoginCode('+1234567890');

// Check if your session is alive
const valid = await fragment.isSessionValid();

Payments

Payment methods return transaction data for external signing — the SDK never touches your keys.

const fragment = new Fragment({
  cookies: { /* ... */ },
  tonconnect: {
    account: JSON.stringify({ address: '0:abc...', chain: '-239', ... }),
    device: JSON.stringify({ platform: 'linux', appName: 'MyApp', ... }),
  },
});

// 1. Get transaction from Fragment
const tx = await fragment.buyStars('durov', 100);

// 2. Sign with your wallet
const boc = await wallet.sendTransaction(tx.transaction);

// 3. Confirm
await fragment.confirmPayment(tx.confirm_method, { boc });

Auth

Login programmatically with a phone number. The only manual step is tapping "Confirm" in Telegram.

const fragment = new Fragment({ cookies: { stel_dt: '-240' } });
await fragment.init();
await fragment.getSessionCookie();

const result = await fragment.loginWithPhone('+1234567890', {
  onWaiting: (n) => console.log(`Waiting... (${n})`),
});

console.log(result.userInfo);  // { id, firstName, username }
console.log(result.cookies);   // save for reuse

Services

16 service modules covering the full Fragment API.

Service	What it does	Wallet?
stars	Buy Telegram Stars	Yes
premium	Gift Telegram Premium	Yes
starsGiveaway	Create Stars giveaways	Yes
premiumGiveaway	Create Premium giveaways	Yes
ads	Telegram Ads top-ups & revenue	Partial
gateway	Gateway API credits	Yes
auction	Search, bid, sell, cancel	Partial
assets	Manage usernames & numbers	No
nft	Convert, transfer, withdraw	Partial
auth	Login, sessions, wallet proof	No
walletApi	Wallet verification & KYC	No
history	Transaction history	No
sessions	TON session management	No
random	Provably fair random numbers	Yes
loginCodes	Login code forwarding	No
starsRevenue	Stars revenue withdrawal	No

Escape Hatch

Call any Fragment API method directly:

const result = await fragment.call('someNewMethod', { param: 'value' });

API Spec

Full OpenAPI/Swagger spec for Fragment's API is included: swagger.json

Documentation

Guide	Description
Getting Started	Installation, setup, first steps
Authentication	Cookies, phone login, wallet connection
Payments	How payment flows work, all payment methods
Services	Full API reference for all 16 services
Error Handling	Error types and handling patterns
swagger.json	Full OpenAPI spec for Fragment's API

Examples

Example	Description
search-auctions.js	Search Fragment marketplace
manage-assets.js	List and assign usernames
login-codes.js	Read codes, manage sessions
buy-stars.js	Full payment flow
auth-phone.js	Programmatic phone login
raw-api.js	Direct API calls

License

MIT