Building a Telegram Stars ledger in TypeScript: payments, refunds and nanostars
Telegram's Bot API reports a bot's Stars activity as a list of StarTransaction objects, and the useful numbers (net balance, how much was refunded) are not in the response: you have to compute them. As of November 2026, a Star that a bot earns is valued by Telegram at $0.013 (per its Bot Developer Terms , section 6.2.4), so getting the ledger right is also getting the revenue right. This post…
Telegram's Bot API provides a list of StarTransaction objects containing information about a bot's Stars activity. However, the net balance and refunded amounts are not included in the response, so they must be calculated. As of November 2026, a Star earned by a bot is valued at $0.013 according to Telegram's Bot Developer Terms.
This post aims to create a TypeScript ledger from the documented fields and test it without using a bot token. The getStarTransactions function returns the bot's Star transactions in chronological order as a StarTransactions object. It takes two optional parameters: offset and limit, with the latter ranging from 1 to 100 (default is 100).
Each StarTransaction object includes fields such as id, amount, nanostar_amount, date, source, and receiver. The source and receiver fields are TransactionPartner objects, present only for incoming and outgoing transactions, respectively. The source and receiver fields help determine the direction of the transaction. To pair a refund with its payment, a map of incoming invoice_payment transactions keyed by their id is sufficient, as refunds reuse the payment's id.
This ledger keeps every amount in nanostars as a BigInt, paginates through the history 100 transactions at a time, and separates gross payments from refunds. The code is written in TypeScript, saves as ledger.mts, and can be run directly in Node 24 without a build step.
Rewritten by urgent.news; may contain errors — check the original.