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.

Ikkala usul barcha /api/* endpointlarda (health'dan tashqari, u kalitsiz ishlaydi) bab-baravar ishlaydi — send-stars, send-premium, balance, stars-price, max-stars. Xohlagan birini tanlang.

1-usul: Header orqali (tavsiya etiladi)

curl -H "X-API-Key: LOYIHA_API_KALITINGIZ" "https://istars.uz/api/balance"

2-usul: Query parametri orqali

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

Agar ikkalasi ham birga yuborilsa, header ustunlik qiladi. Aks holda ikkalasi ham to'liq bir xil natija beradi — hech qaysi endpointda faqat bittasi ishlab, ikkinchisi ishlamay qolmaydi.

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

# 1-usul: Header orqali (tavsiya etiladi) — 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}'

# 1-usul: Header orqali (tavsiya etiladi) — 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"}'

# 2-usul: Query parametri orqali
curl -X POST "https://istars.uz/api/send-stars?api_key=LOYIHA_API_KALITINGIZ" \
  -H "Content-Type: application/json" \
  -d '{"username":"@username","quantity":100}'

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`	—

POST /api/send-premium

Belgilangan Telegram foydalanuvchisiga Telegram Premium sovg'a qiladi. 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)
`months`	integer	Ha	Premium muddati: 3, 6 yoki 12 oy
`payment_method`	string	Yo'q	gram (standart, TON bilan) yoki usdt (USDT bilan)

So'rov namunasi

# 1-usul: Header orqali (tavsiya etiladi) — gram/TON
curl -X POST https://istars.uz/api/send-premium \
  -H "X-API-Key: LOYIHA_API_KALITINGIZ" \
  -H "Content-Type: application/json" \
  -d '{"username":"@username","months":3}'

# 1-usul: Header orqali (tavsiya etiladi) — USDT
curl -X POST https://istars.uz/api/send-premium \
  -H "X-API-Key: LOYIHA_API_KALITINGIZ" \
  -H "Content-Type: application/json" \
  -d '{"username":"@username","months":3,"payment_method":"usdt"}'

# 2-usul: Query parametri orqali
curl -X POST "https://istars.uz/api/send-premium?api_key=LOYIHA_API_KALITINGIZ" \
  -H "Content-Type: application/json" \
  -d '{"username":"@username","months":3}'

Muvaffaqiyatli javob

{
  "success": true,
  "dry_run": false,
  "username": "username",
  "months": 3,
  "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_months`	Premium muddati: 3, 6 yoki 12 oy
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	`already_subscribed`	—
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.)

# 1-usul: Header orqali (tavsiya etiladi)
curl -H "X-API-Key: LOYIHA_API_KALITINGIZ" "https://istars.uz/api/balance"

# 2-usul: Query parametri orqali
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
`quantity`	integer	Yo'q	Standart: 50
`payment_method`	string	Yo'q	gram (standart) yoki usdt

# 1-usul: Header orqali (tavsiya etiladi)
curl -H "X-API-Key: LOYIHA_API_KALITINGIZ" "https://istars.uz/api/stars-price?quantity=100&payment_method=usdt"

# 2-usul: Query parametri orqali
curl "https://istars.uz/api/stars-price?api_key=LOYIHA_API_KALITINGIZ&quantity=100&payment_method=usdt"

{
  "success": true,
  "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
`payment_method`	string	Yo'q	gram (standart) yoki usdt

# 1-usul: Header orqali (tavsiya etiladi)
curl -H "X-API-Key: LOYIHA_API_KALITINGIZ" "https://istars.uz/api/max-stars?payment_method=gram"

# 2-usul: Query parametri orqali
curl "https://istars.uz/api/max-stars?api_key=LOYIHA_API_KALITINGIZ&payment_method=gram"

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

GET /api/search-user

Berilgan Telegram username'ga Stars sovg'a va (alohida-alohida) Telegram Premium sovg'a yuborish mumkinmi-yo'qmi tekshiradi — hech narsa yuborilmaydi, hech qanday mablag' sarflanmaydi, tranzaksiya tuzilmaydi. send-stars/send-premium chaqirishdan oldin qabul qiluvchini tekshirish uchun ishlating — bu stars-price'dan ham yengilroq, chunki narx hisoblamaydi, faqat mavjudligini tekshiradi.

Parametrlar

Nomi	Turi	Majburiymi	Izoh
`username`	string	Ha	Qabul qiluvchi Telegram username (@ bilan yoki bo'lmasa ham)

So'rov namunasi

# 1-usul: Header orqali (tavsiya etiladi)
curl -H "X-API-Key: LOYIHA_API_KALITINGIZ" "https://istars.uz/api/search-user?username=durov"

# 2-usul: Query parametri orqali
curl "https://istars.uz/api/search-user?api_key=LOYIHA_API_KALITINGIZ&username=durov"

Muvaffaqiyatli javob

{
  "success": true,
  "username": "durov",
  "can_receive_stars": true,
  "recipient_name": "Pavel Durov",
  "reason": null,
  "can_receive_premium": true,
  "premium_reason": null
}

{
  "success": true,
  "username": "someunknownname123",
  "can_receive_stars": false,
  "recipient_name": null,
  "reason": "not_found",
  "can_receive_premium": false,
  "premium_reason": "not_found"
}

{
  "success": true,
  "username": "alreadypro",
  "can_receive_stars": true,
  "recipient_name": "Some User",
  "reason": null,
  "can_receive_premium": false,
  "premium_reason": "already_subscribed"
}

Diqqat: bu yerda foydalanuvchi topilmasa yoki Premium'ga allaqachon obuna bo'lgan bo'lsa xam javob 200 bo'ladi (404/400 emas) — can_receive_stars/can_receive_premium maydonlariga qarang, HTTP kodga emas. reason (Stars uchun): null — yuborsa bo'ladi; "not_found" — bunday akkaunt Fragment'da yo'q; "not_a_user" — bu username kanal/bot/guruhga tegishli, shaxsiy sovg'a qabul qila olmaydi.

premium_reason (Premium uchun): null — yuborsa bo'ladi; "not_found" / "not_a_user" — Stars bilan bir xil ma'noda; "already_subscribed" — bu foydalanuvchida allaqachon Telegram Premium bor, hozircha yana sovg'a qabul qila olmaydi.

GET /api/health

Kalitsiz — xizmat va baza holatini tekshirish uchun.

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

Xizmat haqi

Har bir muvaffaqiyatli xariddan 1.7% xizmat haqi avtomatik ushlab qolinadi — alohida hisob-kitob shart emas. TON (gram) bilan to'langanda xizmat haqi TON'da, USDT bilan to'langanda esa USDT'ning o'zida ushlab qolinadi (ikkalasida ham asosiy to'lov bilan bitta tranzaksiyada).

AI-agentlar uchun

Ushbu API'ni AI-agent yoki LLM orqali avtomatik ulamoqchi bo'lsangiz, machine-readable /llms.txt faylida barcha endpointlar, parametrlar, xato kodlari va limitlar bitta joyda, batafsil tushuntirilgan.