For developers & sellers

Telegram Gift API

Buy collectible Telegram gifts programmatically and deliver them to any TON wallet.

The TGTools Telegram gift API lets your bot or platform buy collectible Telegram gifts — the upgraded gifts that live as NFTs on TON — with a REST call. GET /api/marketplace/quote returns the total for a specific gift, split into listing price, platform fee and gas buffer, together with canBuy. POST /api/marketplace/buy/auto then buys the gift and delivers it to the recipientTonAddress you specify; GET /api/marketplace/orders/{id} tracks the order until it is Complete. Collections and items can be browsed with the public marketplace endpoints, so you can build a gift shop, a bot command or an automated buyer on top. Keys are created self-serve in the dashboard, there is no subscription, and each order is paid from your wallet balance at the quoted TON total.

API endpoints preview

Free API key · No KYC
Full API documentation →

No identity verification required — sign up, generate an API key, and start sending orders in minutes.

API access is free. You only pay for Stars, Premium, or NFT purchases from your TON wallet balance.

Authenticate with X-Api-Key: tgt_… or Authorization: Bearer tgt_…

Base URL: https://api.tg-tools.shop

Telegram Stars & Premium (Fragment)

  • POST/api/purchase/stars

    Buy Telegram Stars for any username — instant Fragment delivery.

  • POST/api/purchase/premium

    Gift Telegram Premium (3, 6, or 12 months) programmatically.

  • GET/api/purchase/pricesPublic

    Live Stars & Premium prices in TON.

  • GET/api/purchase/user/{username}

    Look up a Telegram user before placing an order.

NFT gifts & marketplace

  • POST/api/marketplace/buy/auto

    Auto-buy a Telegram gift NFT and deliver to a TON wallet.

  • GET/api/marketplace/collections

    Browse gift NFT collections, supply, and floor prices.

  • GET/api/marketplace/nft?address=…

    Fetch NFT details, sale status, and pricing.

  • GET/api/marketplace/quote?address=…

    Get a buy quote with fees before purchase.

Wallet & orders

  • GET/api/wallet

    Check TON balance and deposit address.

  • GET/api/transaction

    List Stars, Premium, and NFT order history.

  • GET/api/marketplace/orders/{id}

    Track NFT buy order status.

Why build with TGTools

  • Quote first — GET /api/marketplace/quote shows price, fee and gas before you buy
  • One POST buys and delivers the gift to any TON address
  • Order status by API until delivery is complete
  • Browse collections and items programmatically
  • Self-serve API key, pay per order from your wallet
  • Same key covers Stars, Premium and gift cards

Platform features

  • GET /api/marketplace/quote?address=… — listingPriceTon, platformFeeTon, gasBufferTon, totalPriceTon, canBuy
  • POST /api/marketplace/buy/auto — { nftAddress, recipientTonAddress, clientOrderId }
  • GET /api/marketplace/orders/{id} — status, totalPriceTon, nftName
  • GET /api/marketplace/collections and /collections/{address}/items — browse the catalog
  • GET /api/marketplace/nft and /nft-by-slug — one gift by address or slug
  • Idempotent orders via clientOrderId

How it works

  1. 1

    Get your API key

    Create an account and generate an API key from your dashboard.

  2. 2

    Integrate

    Call our REST API — or use the panel — to buy Stars and Premium.

  3. 3

    Monitor

    Track every order, wallet balance and history in real time.

Frequently asked questions

What is a Telegram gift NFT?

An upgraded Telegram gift minted as a collectible NFT on the TON blockchain. It can be bought, transferred and displayed like any other NFT.

How do I buy a gift through the API?

Call GET /api/marketplace/quote with the gift address, then POST /api/marketplace/buy/auto with nftAddress, recipientTonAddress and a clientOrderId. Track it with GET /api/marketplace/orders/{id}.

Where is the gift delivered?

To the TON wallet address you pass as recipientTonAddress — yours, or your customer's.

What does an order cost?

The quote lists the listing price, platform fee and gas buffer; the total is charged from your wallet balance in TON.

Can I sell gifts through the API?

The documented integrator flow is browse, quote and buy. Listing gifts for sale is done from the TGTools web app at /sales.

How do I get a Telegram gift API key?

Create a free account, open Settings → API keys and generate a key (up to five). Documentation is at /api-docs.

Ready to get started?

Sign up in seconds. No hidden fees. Instant delivery.