API qo'llanmasi kompyuterda ishlaydi

Endpointlar, kod namunalari va sinov oynasi katta ekranga moslangan. Havolani nusxalab, kompyuterda oching.

starsapi.uz/docs
Bosh sahifa

API Dokumentatsiya

Telegram Stars va Premium sotib olish uchun oddiy REST API. Kassangizga wallet ulang — keyin faqat bitta so'rov yuboring.

Base URL
https://starsapi.uz
Auth
X-API-Key
Format
JSON / Query
Response
success · error_code

Tezkor boshlash

  1. Kassa yaratingPanelda yangi kassa yarating va Gram wallet seed ni ulang (12 yoki 24 so'z — Keeper, Tonkeeper, Trust Wallet)
  2. API kalit olingKassaning API kalitini X-API-Key headerga qo'shing
  3. So'rov yuboringusername va amount bilan POST yuboring — tayyor
API kalit xavfsizligi. Kalitni frontend yoki mobil ilovaga joylamang; so‘rovlarni faqat serveringizdan yuboring. Xarid endpointlari uchun limit: har IP manzilga daqiqasiga 30 ta so‘rov.

Birinchi xarid

Kerak bo'ladi
  • Kassaning API kaliti (panel → kassa)
  • Kassaga ulangan Gram hamyon va unda yetarli balans; gaz uchun ~0.05 TON zaxira
  • Oluvchining Telegram username'i
curl -X POST 'https://starsapi.uz/stars/buy' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: order-1042' \
  -d '{"username": "durov", "amount": 100}'
Muvaffaqiyatli javob200 OK
{
  "success": true,
  "ton_amount": 0.62,
  "data": {
    "order_id": "K7Q2MX",
    "transaction_id": "78f6a…",
    "username": "durov",
    "amount": 100
  }
}
GET /order/K7Q2MX200 OK
{
  "success": true,
  "order": {
    "order_id": "K7Q2MX",
    "status": "SUCCESS",
    "type": "STARS",
    "amount": 100
  }
}
  1. Narxni tekshiringPOST /stars/pricing
  2. Username'ni tekshiringPOST /searchUser
  3. Xarid qilingPOST /stars/buy
  4. Holatni kuzatingGET /order/{order_id}
Xariddan oldin jami summani ko'rsating

/stars/pricing va /premium/pricing javobidagi total.selected — kassa hamyonidan yechiladigan jami summa: narx va xizmat haqi. Uni oxirgi foydalanuvchiga tasdiqlash tugmasidan oldin ko'rsating. Tarmoq gazi alohida, hamyondan TON'da yechiladi. Bajarilgan tranzaksiya qaytarilmaydi.

{"ok": true, "result": {
  "amount": 60,
  "currency": "ton",
  "price": {"selected": "0.6181"},
  "fee_percent": 1.5,
  "total": {"selected": "0.6273"}
}}

202 PENDING javobida qayta to'lamang: order_id bilan har 5 soniyada holatni so'rang, yakuniy holat SUCCESS yoki FAILED bo'ladi. FAILED da pul kassaga qaytadi.

Sinab ko'rish

Kalitingiz bilan so'rov yuborib, haqiqiy javobni shu yerda ko'ring. Pul yechadigan endpointlar (/stars/buy, /premium/buy, /ton/topup) bu yerda yo'q.

Kalit faqat shu brauzerda qoladi, so'rov to'g'ridan-to'g'ri starsapi.uz ga ketadi.
cURL

        
Javob
—
Hech narsa topilmadi
Sotib olish
Sotib olish
Stars va Premium sotib olish endpointlari
POST /stars/buy
Telegram Stars sotib olish
URL
https://starsapi.uz/stars/buy
cURL
curl -X POST 'https://starsapi.uz/stars/buy' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"username": "durov", "amount": 100}'
Request body JSON
MaydonTurHolatTavsif
X-API-KeyheaderMajburiyKassaning API kaliti
Idempotency-KeyheaderIxtiyoriyShart emas — bir xil buyurtma (kassa, username, miqdor) oldingisi tugaganidan keyin 5 s ichida qayta kelsa, server uni o'zi ushlaydi va birinchi buyurtmani duplicate: true bilan qaytaradi. Kalit bilan: bir kalit bilan faqat bitta buyurtma ochiladi, qayta yuborilsa birinchi javob qaytadi (idempotent_replay: true). 1–100 belgi, 30 kun saqlanadi. JSON'da idempotency_key sifatida ham yuborsa bo'ladi
waitbooleanIxtiyoriytrue — to'lov blokcheynda tasdiqlanguncha kutadi (~3 s). Standart: kutmaydi — Fragment'ga to'lov tarmoqqa yuborilishi bilan (~1 s) success va order_id qaytadi; kam uchraydigan keyingi rad GET /order/{order_id} da FAILED bo'ladi va pul kassaga qaytariladi
usernamestringMajburiyTelegram username
amountintegerMajburiyMin: 50, max: 100,000
currencystringIxtiyoriyton yoki usdt
RequestJSON body
{
  "username": "durov",
  "amount": 100
}
Response200 OK
{
  "success": true,
  "data": {
    "transaction_id": "78f6a...",
    "username": "durov",
    "amount": 100
  }
}
Xato javoblari
MISSING_USERNAME400
{
  "success": false,
  "error_code": "MISSING_USERNAME"
}
AMOUNT_TOO_LOW400
{
  "success": false,
  "error_code": "AMOUNT_TOO_LOW"
}
AMOUNT_TOO_HIGH400
{
  "success": false,
  "error_code": "AMOUNT_TOO_HIGH"
}
INVALID_CURRENCY400
{
  "success": false,
  "error_code": "INVALID_CURRENCY"
}
MISSING_SEED400
{
  "success": false,
  "error_code": "MISSING_SEED"
}
INVALID_API_KEY401
{
  "success": false,
  "error_code": "INVALID_API_KEY"
}
RATE_LIMITED429
{
  "success": false,
  "error_code": "RATE_LIMITED"
}
SEQNO_UNAVAILABLE200
{
  "success": false,
  "error": "Hamyon seqno'sini o'qib bo'lmadi (tonapi javob bermayapti) — xabar yuborilmadi, pul yechilmadi. Birozdan keyin qayta urinib ko'ring",
  "error_code": "SEQNO_UNAVAILABLE"
}
WALLET_FROZEN200
{
  "success": false,
  "error": "Hamyon zanjirda muzlatilgan (frozen) — xabar yuborilmadi, pul yechilmadi",
  "error_code": "WALLET_FROZEN"
}
INTERNAL_ERROR500
{
  "success": false,
  "error_code": "INTERNAL_ERROR"
}
PAYMENT_PENDING202
{
  "success": null,
  "status": "PENDING",
  "error_code": "PAYMENT_PENDING",
  "retryable": false,
  "poll": {
    "method": "GET",
    "path": "/order/ABC123",
    "interval_seconds": 5,
    "final_statuses": ["SUCCESS", "FAILED"]
  },
  "data": { "order_id": "ABC123", "transaction_id": "..." }
}
POST /premium/buy
Telegram Premium sotib olish
URL
https://starsapi.uz/premium/buy
cURL
curl -X POST 'https://starsapi.uz/premium/buy' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"username": "durov", "months": 3}'
Request body JSON
MaydonTurHolatTavsif
X-API-KeyheaderMajburiyKassaning API kaliti
Idempotency-KeyheaderIxtiyoriyShart emas — bir xil buyurtma (kassa, username, miqdor) oldingisi tugaganidan keyin 5 s ichida qayta kelsa, server uni o'zi ushlaydi va birinchi buyurtmani duplicate: true bilan qaytaradi. Kalit bilan: bir kalit bilan faqat bitta buyurtma ochiladi, qayta yuborilsa birinchi javob qaytadi (idempotent_replay: true). 1–100 belgi, 30 kun saqlanadi. JSON'da idempotency_key sifatida ham yuborsa bo'ladi
waitbooleanIxtiyoriytrue — to'lov blokcheynda tasdiqlanguncha kutadi (~3 s). Standart: kutmaydi — Fragment'ga to'lov tarmoqqa yuborilishi bilan (~1 s) success va order_id qaytadi; kam uchraydigan keyingi rad GET /order/{order_id} da FAILED bo'ladi va pul kassaga qaytariladi
usernamestringMajburiyTelegram username
monthsintegerMajburiyFaqat 3, 6 yoki 12
currencystringIxtiyoriyton yoki usdt
RequestJSON body
{
  "username": "durov",
  "months": 3,
  "currency": "ton"
}
Response200 OK
{
  "success": true,
  "data": {
    "transaction_id": "78f6a...",
    "order_id": 1241,
    "username": "durov",
    "months": 3
  }
}
Xato javoblari
MISSING_USERNAME400
{
  "success": false,
  "error_code": "MISSING_USERNAME"
}
INVALID_MONTHS400
{
  "success": false,
  "error_code": "INVALID_MONTHS"
}
MISSING_SEED400
{
  "success": false,
  "error_code": "MISSING_SEED"
}
ALREADY_PREMIUM200
{
  "success": false,
  "error": "Foydalanuvchida allaqachon Telegram Premium bor",
  "error_code": "ALREADY_PREMIUM"
}
USER_NOT_FOUND200
{
  "success": false,
  "error": "Foydalanuvchi topilmadi",
  "error_code": "USER_NOT_FOUND"
}
FRAGMENT_ERROR200
{
  "success": false,
  "error": "Fragment: xato matni",
  "error_code": "FRAGMENT_ERROR"
}
INVALID_API_KEY401
{
  "success": false,
  "error_code": "INVALID_API_KEY"
}
RATE_LIMITED429
{
  "success": false,
  "error_code": "RATE_LIMITED"
}
SEQNO_UNAVAILABLE200
{
  "success": false,
  "error": "Hamyon seqno'sini o'qib bo'lmadi (tonapi javob bermayapti) — xabar yuborilmadi, pul yechilmadi. Birozdan keyin qayta urinib ko'ring",
  "error_code": "SEQNO_UNAVAILABLE"
}
WALLET_FROZEN200
{
  "success": false,
  "error": "Hamyon zanjirda muzlatilgan (frozen) — xabar yuborilmadi, pul yechilmadi",
  "error_code": "WALLET_FROZEN"
}
INTERNAL_ERROR500
{
  "success": false,
  "error_code": "INTERNAL_ERROR"
}
PAYMENT_PENDING202
{
  "success": null,
  "status": "PENDING",
  "error_code": "PAYMENT_PENDING",
  "retryable": false,
  "poll": {
    "method": "GET",
    "path": "/order/ABC123",
    "interval_seconds": 5,
    "final_statuses": ["SUCCESS", "FAILED"]
  },
  "data": { "order_id": "ABC123", "transaction_id": "..." }
}
To'ldirish
To'ldirish
Fragment TON balansini to'ldirish
POST /ton/topup
Fragment TON balansini to'ldirish
URL
https://starsapi.uz/ton/topup
cURL
curl -X POST 'https://starsapi.uz/ton/topup' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"username": "durov", "amount": 5}'
Request body JSON
MaydonTurHolatTavsif
X-API-KeyheaderMajburiyKassaning API kaliti
usernamestringMajburiyTelegram username
amountintegerMajburiyTON miqdori — min: 1, max: 10,000
RequestJSON body
{
  "username": "durov",
  "amount": 5
}
Response200 OK
{
  "success": true,
  "data": {
    "transaction_id": "a1b2c...",
    "username": "durov",
    "amount": 5
  }
}
Xato javoblari
MISSING_USERNAME400
{
  "success": false,
  "error_code": "MISSING_USERNAME"
}
AMOUNT_TOO_LOW400
{
  "success": false,
  "error_code": "AMOUNT_TOO_LOW"
}
AMOUNT_TOO_HIGH400
{
  "success": false,
  "error_code": "AMOUNT_TOO_HIGH"
}
MISSING_SEED400
{
  "success": false,
  "error_code": "MISSING_SEED"
}
CASHIER_INACTIVE403
{
  "success": false,
  "error_code": "CASHIER_INACTIVE"
}
INVALID_API_KEY401
{
  "success": false,
  "error_code": "INVALID_API_KEY"
}
RATE_LIMITED429
{
  "success": false,
  "error_code": "RATE_LIMITED"
}
SEQNO_UNAVAILABLE200
{
  "success": false,
  "error": "Hamyon seqno'sini o'qib bo'lmadi (tonapi javob bermayapti) — xabar yuborilmadi, pul yechilmadi. Birozdan keyin qayta urinib ko'ring",
  "error_code": "SEQNO_UNAVAILABLE"
}
WALLET_FROZEN200
{
  "success": false,
  "error": "Hamyon zanjirda muzlatilgan (frozen) — xabar yuborilmadi, pul yechilmadi",
  "error_code": "WALLET_FROZEN"
}
INTERNAL_ERROR500
{
  "success": false,
  "error_code": "INTERNAL_ERROR"
}
PAYMENT_PENDING202
{
  "success": null,
  "status": "PENDING",
  "error_code": "PAYMENT_PENDING",
  "retryable": false,
  "poll": {
    "method": "GET",
    "path": "/order/ABC123",
    "interval_seconds": 5,
    "final_statuses": ["SUCCESS", "FAILED"]
  },
  "data": { "order_id": "ABC123", "transaction_id": "..." }
}
Narx
Stars narxi
Stars va Premium narxi, balansga nima sig'ishi
POST /stars/pricing
Stars narxini hisoblash
URL
https://starsapi.uz/stars/pricing
cURL
curl -X POST 'https://starsapi.uz/stars/pricing' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"amount": 60}'
Request body JSON
MaydonTurHolatTavsif
X-API-KeyheaderMajburiyKassaning API kaliti
amountintegerIxtiyoriyNarxi hisoblanadigan Stars miqdori. Yuborilmasa 60 olinadi
RequestJSON body
{
  "amount": 60
}
Response200 OK
{
  "ok": true,
  "result": {
    "amount": 60,
    "currency": "ton",
    "price": {
      "ton": "0.6181",
      "usd": "0.90",
      "selected": "0.6181"
    },
    "fee_percent": 1.5,
    "total": {
      "ton": "0.6273",
      "usd": "0.91",
      "selected": "0.6273"
    }
  }
}
Javob maydonlari
MaydonTurTavsif
result.amountintegerSo'ralgan Stars miqdori
result.currencystringKassaning to'lov valyutasi: ton yoki usdt
result.price.tonstringFragment narxi, TON (4 xona)
result.price.usdstringFragment narxi, USD (2 xona)
result.price.selectedstringKassa valyutasiga mos qiymat: ton bo'lsa TON, usdt bo'lsa USD
result.fee_percentnumberKassaga qo'llanadigan xizmat haqi, %
result.totalobjectNarx + xizmat haqi — hamyondan haqiqatda yechiladigan summa (gazsiz)

Narx Fragmentdan olinadi va 60 soniya keshlanadi. 50 ta minimal chegara faqat /stars/buy da tekshiriladi — narx istalgan musbat miqdor uchun hisoblanadi.

Xato javoblari
VALIDATION_ERROR400
{
  "ok": false,
  "error_code": "VALIDATION_ERROR",
  "message": "JSON body formati noto'g'ri"
}
MISSING_API_KEY401
{
  "ok": false,
  "error_code": "MISSING_API_KEY",
  "message": "API kalit kiritilmagan (X-API-Key)"
}
INVALID_API_KEY401
{
  "ok": false,
  "error_code": "INVALID_API_KEY",
  "message": "API kalit noto'g'ri"
}
RATE_LIMITED429
{
  "ok": false,
  "error_code": "RATE_LIMITED",
  "message": "Juda ko'p so'rov. Bir daqiqa kuting."
}
FRAGMENT_ERROR502
{
  "ok": false,
  "error_code": "FRAGMENT_ERROR",
  "message": "Stars narxi hali tayyor emas"
}
POST /premium/pricing
Premium narxini hisoblash
URL
https://starsapi.uz/premium/pricing
cURL
curl -X POST 'https://starsapi.uz/premium/pricing' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"months": 3}'
Request body JSON
MaydonTurHolatTavsif
X-API-KeyheaderMajburiyKassaning API kaliti
monthsintegerIxtiyoriy3, 6 yoki 12. Yuborilmasa uchala paket qaytadi
RequestJSON body
{
  "months": 3
}
Response200 OK
{
  "ok": true,
  "result": {
    "months": 3,
    "price": {
      "ton": "8.2379",
      "usd": "11.99",
      "selected": "8.2379"
    },
    "total": {
      "ton": "8.3614",
      "usd": "12.16",
      "selected": "8.3614"
    },
    "currency": "ton",
    "fee_percent": 1.5
  }
}
Javob maydonlari
MaydonTurTavsif
result.monthsintegerPaket muddati (oy)
result.priceobjectFragment narxi: ton (4 xona), usd (2 xona), selected — kassa valyutasida
result.totalobjectNarx + xizmat haqi — hamyondan haqiqatda yechiladigan summa (gazsiz)
result.options[]arraymonths yuborilmaganda: 3, 6, 12 oylik paketlar ro'yxati

USD narx Fragmentdan olinadi, TON qiymati joriy TON/USD kursi bo'yicha hisoblanadi. Narx 60 soniya keshlanadi.

Xato javoblari
VALIDATION_ERROR400
{
  "ok": false,
  "error_code": "VALIDATION_ERROR",
  "message": "months faqat 3, 6 yoki 12 bo'lishi mumkin"
}
MISSING_API_KEY401
{
  "ok": false,
  "error_code": "MISSING_API_KEY",
  "message": "API kalit kiritilmagan (X-API-Key)"
}
INVALID_API_KEY401
{
  "ok": false,
  "error_code": "INVALID_API_KEY",
  "message": "API kalit noto'g'ri"
}
RATE_LIMITED429
{
  "ok": false,
  "error_code": "RATE_LIMITED",
  "message": "Juda ko'p so'rov. Bir daqiqa kuting."
}
FRAGMENT_ERROR502
{
  "ok": false,
  "error_code": "FRAGMENT_ERROR",
  "message": "Premium narxi hali tayyor emas"
}
POST /wallet/balance
Hamyon balansi
URL
https://starsapi.uz/wallet/balance
cURL
curl -X POST 'https://starsapi.uz/wallet/balance' \
  -H 'X-API-Key: YOUR_API_KEY'
Headers Header
MaydonTurHolatTavsif
X-API-KeyheaderMajburiyKassaning API kaliti
Response200 OK
{
  "ok": true,
  "message": "Kassa hamyoni balansi olindi.",
  "result": {
    "cashier": "Do'kon boti",
    "currency": "ton",
    "address": "UQBx3f…k9Pq",
    "balance_ton": "12.5507",
    "balance_usdt": "4.200000",
    "gas_ok": true,
    "wallet_version": "V5R1",
    "network": "TON Mainnet"
  }
}
POST /wallet/calculate
Balansga nima sig'adi
URL
https://starsapi.uz/wallet/calculate
cURL
curl -X POST 'https://starsapi.uz/wallet/calculate' \
  -H 'X-API-Key: YOUR_API_KEY'
Headers Header
MaydonTurHolatTavsif
X-API-KeyheaderMajburiyKassaning API kaliti
Response200 OK
{
  "ok": true,
  "result": {
    "currency": "ton",
    "fee_percent": 1.5,
    "balance_ton": "12.5507",
    "balance_usdt": "0.000000",
    "gas_reserve_ton": "0.0500",
    "gas_ok": true,
    "stars": {
      "max_amount": 1195,
      "asset": "TON",
      "price": {
        "ton": "12.3130",
        "usd": "17.92",
        "selected": "12.3130"
      },
      "total": {
        "ton": "12.4977",
        "usd": "18.19",
        "selected": "12.4977"
      }
    },
    "premium": {
      "packages": [
        { "months": 3, "price": {…}, "total": {…} },
        { "months": 6, "price": {…}, "total": {…} }
      ]
    }
  }
}
Javob maydonlari
MaydonTurTavsif
result.currencystringKassaning to'lov valyutasi: ton yoki usdt
result.balance_tonstringTON balansi (4 xona)
result.balance_usdtstring | nullUSDT balansi (6 xona); o'qib bo'lmasa null
result.gas_okbooleanGaz uchun TON yetadimi. false bo'lsa hech qanday xarid o'tmaydi
result.stars.max_amountintegerBalansga sig'adigan maksimal Stars (fee va gaz hisobga olingan). 50 dan kam bo'lsa 0
result.stars.assetstringHisob asosi: TON yoki USDT
result.stars.totalobjectShu Stars miqdorining fee bilan umumiy qiymati
result.premium.packages[]arrayBalansga yetadigan Premium paketlari; hech biri yetmasa bo'sh massiv

Hisob kassa fee'si va gaz zaxirasini (0.05 TON) hisobga oladi — max_amount ni to'g'ridan-to'g'ri /stars/buy ga yuborish mumkin. USDT kassada ham gaz TON'da to'lanadi.

Xato javoblari
WALLET_NOT_CONNECTED400
{
  "ok": false,
  "error_code": "WALLET_NOT_CONNECTED",
  "message": "Kassa hamyoni ulanmagan"
}
MISSING_API_KEY401
{
  "ok": false,
  "error_code": "MISSING_API_KEY",
  "message": "API kalit kiritilmagan (X-API-Key)"
}
INVALID_API_KEY401
{
  "ok": false,
  "error_code": "INVALID_API_KEY",
  "message": "API kalit noto'g'ri"
}
RATE_LIMITED429
{
  "ok": false,
  "error_code": "RATE_LIMITED",
  "message": "Juda ko'p so'rov. Bir daqiqa kuting."
}
FRAGMENT_ERROR502
{
  "ok": false,
  "error_code": "FRAGMENT_ERROR",
  "message": "Hisoblash uchun narxlar tayyor emas"
}
BALANCE_ERROR502
{
  "ok": false,
  "error_code": "BALANCE_ERROR",
  "message": "Hamyon balansini o'qib bo'lmadi, birozdan so'ng qayta urining"
}