REST API

API Documentation

Integrate TGTools into your own services. Purchase Telegram Stars and Premium programmatically, check wallet balances, and track orders — all via a simple REST API.

Authentication

Protected endpoints accept either a short-lived JWT or a long-lived API key (tgt_...) from Settings.

JWT (browser login)

Get a token from POST /api/auth/telegram. Expires in ~60 minutes.

Authorization: Bearer <your-jwt-token>

API key (programmatic)

Generate from Settings → API Keys. No expiry until revoked. Use X-Api-Key or Authorization: Bearer tgt_...

X-Api-Key: tgt_<your-api-key>

Authorization: Bearer tgt_<your-api-key>

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

POST/api/auth/telegramPublic

Authenticate via Telegram Login Widget

Request Body

{ "id": 123456789, "firstName": "...", "authDate": 1710000000, "hash": "..." }

Response

{ "token": "eyJ...", "username": "...", "walletBalance": 1.5, "commissionRate": 0.05 }

POST/api/auth/telegram/miniappPublic

Authenticate via Telegram Mini App initData

Request Body

{ "initData": "query_id=...&user=...&hash=..." }

Response

{ "token": "eyJ...", "username": "...", "walletBalance": 0 }

GET/api/walletAuth required

Get your wallet balance and deposit info

Response

{ "balance": 1.5, "depositAddress": "UQ...", "depositMemo": "TGT-ABCD" }

GET/api/wallet/deposits?page=1&pageSize=20Auth required

List your deposit history

Response

{ "items": [...], "total": 5 }

GET/api/purchase/pricesPublic

Get current prices (public; logged-in users get their commission rate applied)

Response

{ "stars_price_ton": 0.0105, "premium_3m_ton": 8.3, "premium_6m_ton": 14.2, "premium_12m_ton": 24.5 }

GET/api/purchase/user/{username}Auth required

Look up a Telegram user by username — returns profile info, whether the account exists, and Premium eligibility (requires authentication)

Example

curl -X GET https://api.tg-tools.shop/api/purchase/user/johndoe \
  -H "X-Api-Key: tgt_YOUR_API_KEY"

Response

{ "username": "johndoe", "found": true, "displayName": "John Doe", "photoUrl": "https://...", "premiumEligible": true }

POST/api/purchase/starsAuth required

Purchase Telegram Stars for any username

Request Body

{ "recipientUsername": "johndoe", "amount": 100, "paymentMethod": "ton", "payFromBalance": true }

Response

{ "transactionId": 42, "status": "Completed", "costTon": 1.05, "createdAt": "2026-07-01T00:00:00Z" }

POST/api/purchase/premiumAuth required

Purchase Telegram Premium (3, 6, or 12 months)

Request Body

{ "recipientUsername": "johndoe", "months": 3, "paymentMethod": "ton", "payFromBalance": true }

Response

{ "transactionId": 43, "status": "Completed", "costTon": 8.37, "createdAt": "2026-07-01T00:00:00Z" }

GET/api/transaction?page=1&pageSize=20&status=Completed&type=StarsAuth required

List your orders with optional filters

Response

{ "items": [...], "total": 10 }

GET/api/transaction/{id}Auth required

Get a single order by ID

Response

{ "id": 42, "status": "Completed", "costTon": 1.05, "recipientUsername": "johndoe" }

GET/api/marketplace/quote?address=0:...Auth required

Get purchase quote for a gift NFT

Example

curl -X GET "https://api.tg-tools.shop/api/marketplace/quote?address=0:..." \
  -H "X-Api-Key: tgt_YOUR_API_KEY"

Response

{ "nftAddress": "0:...", "totalPriceTon": 1.115, "canBuy": true }

GET/api/marketplace/collections?offset=0&limit=100&search=lolAuth required

List all Telegram gift NFT collections

Example

curl -X GET "https://api.tg-tools.shop/api/marketplace/collections?limit=50" \
  -H "X-Api-Key: tgt_YOUR_API_KEY"

Response

{ "items": [{ "address": "0:...", "name": "Lol Pop", "supply": 100000 }], "total": 120, "hasMore": true }

GET/api/marketplace/collections/{address}Auth required

Get collection summary (floor, supply, listed count)

Example

curl -X GET https://api.tg-tools.shop/api/marketplace/collections/0:... \
  -H "X-Api-Key: tgt_YOUR_API_KEY"

Response

{ "address": "0:...", "name": "Lol Pop", "supply": 100000, "floorTon": 1.2, "listedForSale": 42 }

GET/api/marketplace/collections/{address}/items?offset=0&limit=50&sort=price_asc&onSaleOnly=trueAuth required

List NFTs in a collection (paginated, filterable)

Example

curl -X GET "https://api.tg-tools.shop/api/marketplace/collections/0:.../items?onSaleOnly=true" \
  -H "X-Api-Key: tgt_YOUR_API_KEY"

Response

{ "items": [{ "address": "0:...", "name": "Lol Pop #1", "salePriceTon": 1.5, "isOnSale": true }], "hasMore": true }

GET/api/marketplace/nft?address=0:...Auth required

Get full NFT detail (metadata, sale/rental state, history)

Example

curl -X GET "https://api.tg-tools.shop/api/marketplace/nft?address=0:..." \
  -H "X-Api-Key: tgt_YOUR_API_KEY"

Response

{ "address": "0:...", "name": "Lol Pop #1", "isOnSale": true, "salePriceTon": 1.5, "platformSaleListing": { "priceTon": 1.4 } }

GET/api/marketplace/nft-by-slug?collection=lol-pop&number=392829Auth required

Look up NFT by collection slug and number (e.g. lol-pop #392829)

Example

curl -X GET "https://api.tg-tools.shop/api/marketplace/nft-by-slug?collection=lol-pop&number=392829" \
  -H "X-Api-Key: tgt_YOUR_API_KEY"

Response

{ "address": "0:...", "name": "Lol Pop #392829", "isOnSale": true }

POST/api/marketplace/buy/autoAuth required

API-only: buy a gift NFT from wallet balance (no Tonkeeper). Requires 500+ TON lifetime deposits. Poll GET /api/marketplace/orders/{id}.

Example

curl -X POST https://api.tg-tools.shop/api/marketplace/buy/auto \
  -H "X-Api-Key: tgt_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nftAddress":"0:...","recipientTonAddress":"UQ...","clientOrderId":"order-001"}'

Request Body

{ "nftAddress": "0:...", "recipientTonAddress": "UQ...", "clientOrderId": "order-001" }

Response

{ "orderId": 12, "status": "PaymentReceived", "totalPriceTon": 1.115, "recipientTonAddress": "UQ..." }

GET/api/marketplace/orders/{id}Auth required

Poll NFT purchase order status (PaymentReceived → Complete)

Response

{ "orderId": 12, "status": "Complete", "nftAddress": "0:...", "totalPriceTon": 1.115 }