API hujjatlari

Telegram Stars API — Fragment.com orqali Stars sotib olish, narx tekshirish va wallet balansini so'rash uchun REST endpointlar. Barcha javoblar JSON formatida qaytadi.

Autentifikatsiya

Har bir so'rovda loyihangizning API kalitini X-API-Key header orqali (yoki api_key query parametri sifatida) yuboring. Har bir loyiha — mustaqil wallet va statistikaga ega, shuning uchun kalit ham loyiha darajasida beriladi.

Ro'yxatdan o'tish / Kirish — Ro'yxatdan o'ting yoki kiring — API kalitingizni loyiha sahifasida topasiz.

POST /api/send-stars

Belgilangan Telegram foydalanuvchisiga Stars sotib olib yuboradi. To'lov API kalit tegishli loyihaning walletidan amalga oshadi.

Parametrlar

Nomi	Turi	Majburiymi	Izoh
`username`	string	Ha	Qabul qiluvchi Telegram username (@ bilan yoki bo'lmasa ham)
`quantity`	integer	Ha	50 dan 10 000 000 gacha
`payment_method`	string	Yo'q	gram (standart, TON bilan) yoki usdt (USDT bilan)

So'rov namunasi

# gram/TON
curl -X POST https://istars.uz/api/send-stars \
  -H "X-API-Key: LOYIHA_API_KALITINGIZ" \
  -H "Content-Type: application/json" \
  -d '{"username":"@username","quantity":100}'

# USDT
curl -X POST https://istars.uz/api/send-stars \
  -H "X-API-Key: LOYIHA_API_KALITINGIZ" \
  -H "Content-Type: application/json" \
  -d '{"username":"@username","quantity":100,"payment_method":"usdt"}'

Muvaffaqiyatli javob

{
  "success": true,
  "dry_run": false,
  "username": "username",
  "amount": 100,
  "transaction_id": "..."
}

Xato kodlari

HTTP	error	Izoh
401	`unauthorized`	Email yoki parol noto'g'ri
422	`invalid_username`	Qabul qiluvchi Telegram username (@ bilan yoki bo'lmasa ham)
422	`invalid_quantity`	50 dan 10 000 000 gacha
422	`invalid_payment_method`	gram (standart, TON bilan) yoki usdt (USDT bilan)
429	`rate_limited`	Juda ko'p urinish. Birozdan keyin qayta urinib ko'ring.
404	`user_not_found`	—
400	`config_error`	—
400	`fragment_error`	—
400	`verification_required`	—

GET /api/balance

Loyihangizning wallet manzili, turi, joriy GRAM (TON) va USDT balansini qaytaradi. (Eski nomi: /api/wallet-balance — hali ham ishlaydi.)

curl "https://istars.uz/api/balance?api_key=LOYIHA_API_KALITINGIZ"

{
  "success": true,
  "address": "UQ...",
  "wallet_version": "v5r1",
  "gram_balance": 1.2345,
  "usdt_balance": 3.5
}

GET /api/stars-price

Belgilangan miqdordagi stars uchun Fragment'dan real narxni oladi (TON yoki USDT). Shu bilan birga username'ning Fragment'da Stars qabul qila olishini ham tekshiradi.

Parametrlar

Nomi	Turi	Majburiymi	Izoh
`username`	string	Ha	Narx aniqlanadigan qabul qiluvchi
`quantity`	integer	Yo'q	Standart: 50
`payment_method`	string	Yo'q	gram (standart) yoki usdt

curl "https://istars.uz/api/stars-price?api_key=LOYIHA_API_KALITINGIZ&username=@username&quantity=100&payment_method=usdt"

{
  "success": true,
  "username": "username",
  "quantity": 100,
  "payment_method": "usdt",
  "price": 1.5,
  "currency": "USDT"
}

GET /api/max-stars

Loyihangiz walletidagi joriy balans (GRAM yoki USDT) qancha stars'ga yetishini hisoblab beradi — real Fragment narxidan kelib chiqib.

Parametrlar

Nomi	Turi	Majburiymi	Izoh
`username`	string	Ha	Narx bazasi uchun (real qabul qiluvchi bo'lishi kerak)
`payment_method`	string	Yo'q	gram (standart) yoki usdt

curl "https://istars.uz/api/max-stars?api_key=LOYIHA_API_KALITINGIZ&username=@username&payment_method=gram"

{
  "success": true,
  "payment_method": "gram",
  "rate_per_star": 0.010086,
  "currency": "TON",
  "max_stars": 4820,
  "gram_balance": 48.912
}

GET /api/health

Kalitsiz — xizmat va baza holatini tekshirish uchun.

curl "https://istars.uz/api/health"

Xizmat haqi

Har bir muvaffaqiyatli (gram/TON bilan to'langan) xariddan 1.7% xizmat haqi avtomatik ushlab qolinadi — alohida hisob-kitob shart emas. USDT bilan to'langan xaridlarda xizmat haqi hozircha ushlab qolinmaydi.