Telegram is preparing to let users trade gifts that already live on the blockchain right inside the app. Between November 7 and 11, the Telegram for macOS 13.2.0 beta gained API methods for buying such gifts, listing them for sale and taking them off sale, for price offers on them, and for withdrawing earned Gram to the built-in wallet. The interface strings for these screens are already on Telegram's translation platform for iOS: gifts from Fragment get their own filter on Telegram's marketplace, and they are paid for and sold from the "Money" section. None of this is in the stable versions; it is all still in testing. It affects owners of collectible gifts moved to the blockchain and anyone who earns Gram from channels, bots and gifts.

Fragment gifts on Telegram's marketplace

A collectible gift can stay on your profile or be moved to the blockchain as an NFT. Since October 21 there has been a built-in wallet for that, and such NFTs are sold on Fragment and other TON marketplaces. Until now, the marketplace inside Telegram has only shown gifts listed from profiles, for Stars or Gram.

On the translation platform for iOS, the marketplace filters gained two new items: From Fragment and On-Chain Sales. Next to them are strings describing how such a listing is bought:

  • Fragment listings are paid for and sold from the Telegram wallet, and without a wallet they can't be bought;
  • such a listing can only be bought for yourself, not as a gift for someone else;
  • after the purchase, the gift "will appear in your wallet once the network confirms it", and if you are short of Gram, the app names the amount including network fees.

The From Fragment filter in the marketplace dropdown was already spotted in a client on November 7.

Buying and selling from the wallet

On November 7, three methods appeared in the macOS beta's API schema (layer 234):

MethodWhat the client sendsWhat it does, judging by the name
payments.buyStarGiftOnchainthe gift's short name and the expected pricebuys a gift from the blockchain
payments.updateStarGiftOnchainPricethe gift's short name and the new pricelists the gift or changes its price
payments.cancelStarGiftOnchainSalethe gift's short nametakes the gift off sale

All three return the same thing: the NFT address, an amount and a ready-made message body for the blockchain. The server doesn't move the gift itself: the user's wallet signs the transaction, and Telegram only assembles its contents. That is why every action has a pending state in the strings: the gift "will be listed for sale once the network confirms it", "will be removed from sale once the network confirms it". Judging by the strings, a price change takes two steps: the listing is removed from sale and then listed again. There is a separate string for a failure between the steps: the gift was removed from sale, but listing it at the new price failed. The price is limited to a range, and outside it the server returns an error.

These operations get their own entries in the wallet history: Put on sale, Removed from sale, Purchased.

Price offers for gifts on the blockchain

Gifts on a profile already have price offers: the buyer names the recipient, the gift and an amount in Stars or Gram, and a service message appears in the chat. On November 8, the beta's schema gained the same mechanism for gifts on the blockchain, but built differently.

The payments.sendStarGiftOnchainOffer request carries only the gift's short name, an amount in Gram, a duration and a random number. There is no recipient in it: the server finds the owner from the gift. In return, the client gets not a finished deal but a transaction it has to sign itself: the address of a separate offer contract, the expiry, the amount and, if the contract doesn't exist yet, its code and data. Judging by the response fields, a dedicated contract is deployed on the network for each offer, and the buyer's Gram sit on it until the offer ends: an interface string says outright that the amount is "held until" a given date. The response also includes a budget for storing the contract on the network, an execution allowance and a fine.

From there, the deal goes the way the iOS strings describe:

  • The buyer enters an amount in Gram and picks how long the owner has to respond. An offer below the minimum price isn't allowed: a separate gift field that appeared in the November 11 build sets it. The confirmation window shows "You pay", the platform fee and the expiry.
  • The owner receives a service message "You were offered … for …" with a Review button. Next comes a Confirm Sale window with the price and Sell and Decline buttons. If the gift is currently listed for sale, the offer can't be accepted until the listing is removed.
  • The owner declines or the offer expires: the Gram go back to the buyer automatically.
  • The buyer withdraws the offer early: there is a charge for that, and the rest is returned. According to the strings, offers are withdrawn "in your chat with Telegram", and a second offer for the same gift can't be sent until the first is withdrawn.

The offer's service message stores the amount, the platform fee in basis points, the expiry, the contract address, the buyer's refund and the fine. A separate "The sale is being completed" status shows that a confirmed deal is still going through the network. The strings don't name the fee or the fine: the server fills them in.

In the November 11 build, the offer response gained a second, optional message for gasless sending. Telegram already pays the network fee for transfers in the built-in wallet itself, and this is probably the same thing for offers.

Withdrawing Gram Earnings to "Money"

Gram Earnings is the Gram balance an account receives from gifts, ads and Fragment. Right now it can only be withdrawn through the Fragment website, and that requires identity verification.

On November 7, the beta's schema gained the payments.withdrawStarsRevenueToWallet method, spotted the same day. It takes the owner of the revenue (a channel, a bot or the account itself), an amount and a temporary two-step verification password, and simply returns "yes" or "no", with no Fragment link like the one the current withdrawal method returns. Its iOS strings are the Ton.WithdrawToWallet set: "The Grams will go to your self-custodial wallet" with the address in brackets, the errors "This amount exceeds the withdrawal limit" and "Your wallet is being set up", and advice to check your transaction history if the withdrawal couldn't be confirmed.

It also ties into trading. If the wallet doesn't have enough Gram for a gift, the app offers to take them from Gram Earnings: the amount moves to the wallet balance and goes toward the purchase. While the transfer is on its way, the gift can't be bought: the purchase has to be repeated once the Gram arrive.

Stars or Gram

The method is named after Stars revenue, but its strings talk only about Gram. Telegram stores revenue in Stars and in Gram in one structure, and the current withdrawal method via Fragment tells them apart with a ton flag. In the schema extracted from the macOS beta, such toggle flags are invisible: the revenue statistics method loses its dark and ton flags, and gift transfer to the wallet loses keep_on_profile, although the Telegram Desktop schema has them. In the new method, the optional amount sits on flag 1, while flag 0 isn't visible in the schema — probably it is the same ton flag. Whether Stars themselves will be withdrawable directly doesn't follow from the schema: Stars are not a blockchain coin, and there are no strings about withdrawing Stars to the wallet.

What is confirmed and what isn't

  • The methods for buying, selling, offers and withdrawal to the wallet exist only in the Telegram for macOS beta; the Telegram Desktop schema (layer 233) doesn't have them. The API documentation doesn't have them either.
  • The interface strings are so far English-only and iOS-only; the macOS section and the Telegram Desktop strings don't have them.
  • How much of the price the platform takes, how big the early withdrawal fine is and what the withdrawal limit is can't be seen from the client.
  • Whether identity verification will be required to withdraw Gram Earnings to the Telegram wallet is not yet known.