TON hamyonida USDT balansini bitta chaqiruv bilan bilish

Agentning hamyoni ochiq, get_balance halol bir necha GRAM qaytardi — USDT esa nol. Holbuki siz shu manzilga steyblkoinlar kelganini aniq bilasiz. Tanishmi? Hamyon boʻsh koʻrinadi, garchi unda 500 USDT yotgan boʻlsa ham. Bu bag ham emas, yoʻqolgan pul ham emas — siz shunchaki notoʻgʻri kontraktdan soʻradingiz. AI agentni TONga ulashdagi birinchi integratsiyalarning koʻpchiligi aynan shu yerda yiqiladi: agent notoʻgʻri manzilni oʻqiydi.

Nega USDT balansi — bu TON-hamyon balansi emas

Ethereumda siz ERC-20 tokeni «manzilda yotadi» degan holatga oʻrganib qolgansiz: token kontrakti address → balance jadvalini saqlaydi, balansni bilish uchun esa siz shu bitta kontraktdan soʻraysiz. TONda model boshqacha — bu chalkashlikning birinchi manbayi.

Nativ tanga GRAM (avvalgi Toncoin; tarmoq esa hamon TON deb ataladi) toʻgʻridan-toʻgʻri hamyoningizning smart-kontraktida yotadi — uni get_balance akkaunt holatiga bitta murojaat bilan oʻqiydi. USDT esa — jetton (jetton, TONning oʻzaro almashinadigan tokenlar standarti). Jetton balansi esa sizning asosiy hamyoningizda emas, alohida kichik kontraktda — jetton-hamyonda (jetton wallet) saqlanadi.

Oʻxshatish: sizning asosiy TON-hamyoningiz — bu odam sifatidagi siz. USDTning jetton-hamyoni esa — aniq bir bank (USDTning master-kontrakti) sizning nomingizga ochgan alohida hisob raqami. «Menda qancha dollar bor» deb odamning oʻzidan soʻrash maʼnosiz — pul hisobda, choʻntakda emas. Har bir «ega + jetton» juftligining oʻz jetton-hamyoni bor: USDT uchun bitta manzil, NOT uchun boshqasi, istalgan jetton uchun uchinchisi.

Yaxshi xabar: bu jetton-hamyonning manzili tasodifiy emas. U ikkita narsadan deterministik tarzda kelib chiqadi:

• eganing manzili (sizning odatiy TON-hamyoningiz, EQ…/UQ…);
• jetton master-kontraktining manzili (jetton master — USDT uchun bu bitta qatʼiy kontrakt).

Yomon xabar: bu manzilni halol hisoblab chiqarish uchun master-kontraktga borib, uning get-metodini chaqirish, soʻngra jetton-hamyonning holatini oʻqish kerak. Qoʻlda bu bir necha qadam boʻladi va integratsiyalar aynan shu yerda qoqiladi.

get_jetton_balance: indekser oʻrniga bitta chaqiruv

Odatda bu vazifa ikki usuldan biri bilan hal qilinadi va ikkalasi ham noqulay:

• Oʻz indekseringiz. Noda koʻtarish, jetton-oʻtkazmalarni bazaga indekslash, uni dolzarb holatda ushlab turish. Bitta son uchun qimmat va moʻrt, maʼlumotlar esa har doim cheyndan biroz ortda qoladi.
• Ommaviy HTTP-API. Tezda limitlarga tiqilib qoladi: kalitsiz bu taxminan sekundiga bitta soʻrov, limitdan oshganda esa siz halol HTTP 429 Too Many Requests olasiz. Ustiga-ustak, siz birovning indeksatsiyasiga va uning chuqurligiga bogʻlanib qolasiz.

TONNodeʼning get_jetton_balance tooli ikkala muammoni ham yoʻqotadi. Siz unga uzatasiz:

• eganing manzili — foydalanuvchining odatiy TON-hamyoni (EQ…/UQ…);
• jetton identifikatori — masalan, USDT.

Keyin server butun ishni on-chain oʻzi bajaradi:

1. jettonning master-kontrakt get-metodini chaqiradi — u eganing manzili boʻyicha uning jetton-hamyoni manzilini qaytaradi (aynan oʻsha deterministik hisob);
2. shu jetton-hamyondan balansni oʻqiydi va uni sizga qaytaradi.

Hech qanday begona indekser, hech qanday baza, hech qanday desinxronizatsiya — faqat kontraktlarning get-metodlari orqali tarmoq holatini toʻgʻridan-toʻgʻri oʻqish.

TONNode — bu TON uchun hosted MCP-server. MCP (Model Context Protocol) — AI agentlar (Claude, Cursor, ChatGPT/Codex va istalgan MCP-klient) tashqi toollarni chaqiradigan standart. Yaʼni get_jetton_balance — bu sizning kodingizdagi satr emas, balki foydalanuvchi balans haqida soʻraganda agentning oʻzi chaqiradigan tool. Kapot ostida @tonnode/mcp paketi (open source, MIT) TONning nativ ADNL-protokoli boʻyicha ishlaydi, oraliq HTTP-qatlamlarsiz — agent tarmoq bilan yana bir REST-shlyuz orqali emas, toʻgʻridan-toʻgʻri muloqot qiladi.

Misol: agentga prompt va nima qaytadi

Ulanish lokal, kalitsiz va kartasiz. MCP-klient konfigiga qoʻshing (Claude Desktop, Cursor, istalgan MCP-mos klient):

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

Shundan soʻng agentga inson tilidagi oddiy prompt yetarli:

UQAbc…xyz hamyonida qancha USDT bor? Odam oʻqiydigan qiymatni qaytar.

Agent get_jetton_balance toolini oʻzi tanlaydi, eganing manzili va USDT jettonini uzatadi, server esa balansni qaytaradi — lekin odatdagi «dollar»larda emas, raw-birliklarda (jettonning minimal boʻlinmas birliklarida). Balansning oʻzidan tashqari javobda server on-chain hisoblab chiqqan jetton-hamyon manzili ham keladi — bu keyinchalik aynan shu kontraktning oʻtkazmalarini kuzatmoqchi boʻlsangiz foydali. Bizning misolimizdagi balansning oʻzi — 12500000 koʻrinishidagi qiymat.

Ammo 12500000 — bu 12.5 million USDT emas. Shu yerda ikkinchi tuzoq boshlanadi — unda adashish juda oson.

Raw-birliklar va decimals: nega USDTda 6, 9 emas

Blokcheynlar kasr sonlar bilan ishlamaydi. Barcha summalar butun sonli raw-birliklarda saqlanadi, «odamcha» qiymat esa 10^decimals ga boʻlish orqali olinadi, bu yerda decimals — aniq bir jettonning xossasi. Bu xuddi tiyin va soʻmga oʻxshaydi: past darajada hammasi tiyinda, decimals esa vergulni qayerga qoʻyishni aytadi.

TONdagi asosiy nozik jihat: turli jettonlarda decimals soni har xil.

• Nativ GRAMda va TON jettonlarining koʻpchiligida decimals = 9.
• TONdagi USDTda esa decimals = 6.

Shuning uchun aynan bir xil raw-qiymat butunlay har xil summani anglatadi. Misolimizni toʻgʻri qayta hisoblaymiz:

raw      = 12500000
decimals = 6            // aynan USDT uchun
human = 12500000 / 10^6 = 12500000 / 1_000_000 = 12.5 USDT

12.5 USDT, 12.5 million emas. Agar odat boʻyicha 10^9 ga boʻlganingizda (odatiy jetton uchun boʻlgani kabi), 0.0125 chiqqan boʻlardi — ming barobar xato. Bitta son — orada esa uch tartib farq. Naiv integratsiyalarda pul aynan shunday yoʻqoladi: hamma narsa uchun qatʼiy hardkod qilingan 10^9 boʻluvchi. Shuning uchun decimals ni hech qachon hardkod qilmang — ularni jettonning oʻz metadatasidan oling.

get_jetton_info: decimals va jetton metadatasini qayerdan olish

Taxmin qilmaslik uchun juft tool bor — get_jetton_info. U jettonning master-kontraktini oʻqiydi va uning metadatasini beradi:

• nom (name);
• simvol (symbol);
• decimals — boʻluvchi hisoblanadigan oʻsha son;
• emissiya (total supply).

Agent uchun ishonchli stsenariy — ikkita chaqiruv: agar jetton notanish boʻlsa, avval decimals ni bilish uchun get_jetton_info, soʻngra raw-balansni olish uchun get_jetton_balance, va faqat shundan keyin koʻrsatish uchun raw / 10^decimals boʻlish.

1) get_jetton_info(USDT)            -> decimals = 6
2) get_jetton_balance(owner, USDT)  -> raw = 12500000
3) human = 12500000 / 10^6          -> 12.5 USDT

Promptni agent bu qadamlarni oʻzi ulab ketadigan qilib shakllantirish mumkin:

get_jetton_info orqali USDT uchun decimals ni ol, soʻngra get_jetton_balance orqali UQAbc…xyz hamyonining balansini ol va raw ni odam oʻqiydigan songa oʻgir.

Agar siz faqat USDT bilan emas, ixtiyoriy jettonlar bilan ishlayotgan boʻlsangiz, bunday tartib majburiy: notanish token uchun uning decimals i 6 mi yoki 9 mi — buni oldindan bilmaysiz. USDT uchun decimals = 6 — konstanta, lekin uni get_jetton_info dan tortib olish odati sizni birinchi nostandart jettondayoq qutqaradi. Xuddi shu usul TONda kiruvchi USDT-toʻlovlarni aniqlashning ham asosida yotadi — u yerda 1 USDT ni mikroskopik chang bilan chalkashtirib yubormaslik uchun decimals hal qiluvchi ahamiyatga ega.

parse_address: soʻrovdan oldin manzilni oflayn tekshirish

«Nol» balansning yana bir tez-tez uchraydigan sababi — egasining notoʻgʻri manzili. Foydalanuvchilar manzillarni har xil formatda joʻnatishadi: EQ… (bounceable), UQ… (non-bounceable), raw (0:…). Balansni soʻrashdan oldin manzilni parse_address orqali normallashtirish foydali — u oflayn (tarmoqqa murojaat qilmasdan) istalgan formatdagi manzilni oladi, uni uchalasiga (EQ/UQ/raw) konvertatsiya qiladi va u umuman toʻgʻrimi-yoʻqmi — aytib beradi.

Bu arzon, bir zumda ishlaydi va «manzil notoʻgʻri boʻlgani uchun balans 0» degan butun bir xatolar sinfini yoʻqotadi — ayniqsa manzil ishonchsiz manbadan, foydalanuvchi kiritmasidan yoki chatdan kelgan boʻlsa.

Qanday ulash: lokalda bepul yoki hosted

Uchta tool — parse_address, get_jetton_info, get_jetton_balance — «hamyonda qancha USDT bor» degan savolga birorta ham begona indeksersiz toʻliq va halol javob beradi.

Lokalda bepul

@tonnode/mcp paketi — open source (MIT), npm va GitHubda yotibdi. Yuqoridagi misoldagi oʻsha ommaviy konfig (npx -y @tonnode/mcp) oʻqish toollarining toʻliq toʻplamini beradi, jumladan get_jetton_balance, get_jetton_info va parse_address — alohida kalit kerak emas.

Klientni qayta ishga tushirasiz — va agent allaqachon jetton balanslarini ADNL boʻyicha oʻqiydi. Agentga umuman nega limitli ommaviy shlyuz emas, alohida MCP-server kerakligini TONdagi AI agentlar uchun MCP haqidagi maqolada koʻrib chiqqandik. Bepul ommaviy konfig qayerda tugashi va nega — TONning ommaviy laytserverlari limitlari tahlilida.

Hosted — throughput kerak boʻlganda

Lokal soʻrov tezligi yetmay qolganda (botlar, backendlar, prodakshn yuki), oʻz kalitli hosted-endpointga oʻtasiz. Toollar toʻplami hamma joyda bir xil — barcha 16 tasi, jumladan oʻqish bloki; tariflar faqat kafolatlangan throughput bilan farqlanadi:

• Hobby — abadiy bepul, 60 soʻrov/daq;
• Pro — $29/oy, 300 soʻrov/daq;
• Scale — $199/oy, 1200 soʻrov/daq.

Hosted-ulanish faqat bitta narsa bilan farq qiladi — siz umumiy endpointga oʻz kalitingiz bilan murojaat qilasiz:

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": { "Authorization": "Bearer tn_live_…" }
    }
  }
}

Agar dashboard, balanslarni tekshiruvchi bot yoki manzillarni tez-tez soʻrab turadigan agent qilayotgan boʻlsangiz — ommaviy API limitlariga tiqilib qolmaslik va eng nomunosib paytda 429 ga duch kelmaslik uchun kalit oling.

Qisqacha

• TONdagi USDT — jetton, uning balansi esa asosiy manzilda emas, alohida jetton-hamyonda yotadi.
• get_jetton_balance jetton-hamyon manzilini on-chain oʻzi hisoblaydi va balansni oʻqiydi — indekser ham, oʻz bazangiz ham kerak emas.
• Balans raw-birliklarda keladi; koʻrsatish uchun 10^decimals ga boʻling.
• USDTda decimals = 6 (boʻluvchi 1_000_000), jettonlarning koʻpchiligida — 9. Hardkod qilmang — get_jetton_info dan oling.
• Butun yoʻlni bepul tekshirib koʻrish mumkin: npx -y @tonnode/mcp, ommaviy konfig, toʻliq oʻqish toʻplami.

Bepul Hobby kaliti — 60 soʻrov/daq, kartasiz — tizimga kirgandan soʻng darhol beriladi: kalit olish. U real hamyonda parse_address → get_jetton_info → get_jetton_balance zanjirini oʻtkazib koʻrish va 12500000 raw roppa-rosa 12.5 USDTga aylanishiga — 12.5 millionga ham, 0.0125 ga ham emas — ishonch hosil qilish uchun yetarli.