TON контрактінің get-әдісін SDK-сыз қалай шақыруға болады

Транзакция жіберер алдында әмиянның seqno санын білу үшін ғана эксплорер аштыңыз. Немесе сізге жетонның total_supply керек. Немесе маркетплейстегі NFT-листингтің деректері. Сөйтіп тағы да npm i @ton/ton орнатасыз, TonClient көтересіз, лайтсервердің жұмыс істейтін эндпоинтін іздейсіз, мекенжайды beginCell().storeAddress() арқылы қалай орау керегін түсінуге тырысасыз, содан соң шығыс BOC-ты қолмен талдайсыз. Отыз жол код — контракт өзі тегін беріп тұрған бір ғана сан үшін.

Мәселе TON-да емес. Мәселе мынада: сіз бен қарапайым read-only шақырудың арасында тұтас бір SDK қабаты жатыр — оны орнату, баптау және келесі жаңартуда сындырып алмау керек. Ал егер сіз TON-ға AI-агентті (Claude, Cursor, ChatGPT/Codex) қосып жатсаңыз, бұл қабатты қолмен жазу мүлде абсурд: агент жай ғана әдісті шақыруы тиіс.

Төменде — TON контрактінің кез келген get-әдісін run_get_method арқылы, SDK-клиенттің бір жолын да жазбай, қалай шақыруға болатыны.

TON контрактінің get-әдісі деген не және оны шақыру үшін неге әдетте SDK-ға жүгінеді

Get-әдіс — смарт-контрактінің read-only функциясы. Әмиян seqno береді, жетонның мастер-контрактісі — get_jetton_data, NFT сату контрактісі — get_sale_data, STON.fi/DeDust пулы — get_pool_data. Кілт сөз — read-only:

• әдіс контракттің күйінде ештеңені өзгертпейді;
• ол қолтаңбаны талап етпейді және пайдаланушының газын жұмсамайды;
• ол транзакция жіберу арқылы емес, лайтсерверде немесе TVM-эмуляторында (TON Virtual Machine) орындалады.

Яғни get-әдісті шақыру — бұл транзакция емес. Мұнда қол қоятын да, төлейтін де, блокта күтетін де ештеңе жоқ. Түптеп келгенде бұл «тірі контракттан мәнді оқы» деген функция.

Бірақ оны «ескіше» шақыру үшін тұтас бір әбзел керек: SDK (ton, tonweb, tonutils), лайтсерверге дейінгі өз ADNL-клиентіңіз немесе toncenter секілді HTTP-қаптама, кіріс аргументтерін ұяшықтарға қолмен жинау және шығыс BOC-ты қолмен талдау. Бір ғана оқу үшін тым көп қозғалмалы бөлшек. Әрі олардың әрқайсысы — істен шығу нүктесі: жаһандық конфигтегі ашық лайтсерверлер ортақ әрі лимиттелген, жүктеме кезінде not ready немесе ADNL-таймаутымен жауап береді; ашық HTTP-API лимиттен асқанда 429 Too Many Requests қайтарады (кілтсіз — шамамен секундына бір сұрау).

run_get_method: кез келген контракттің кез келген read-only әдісіне бір ғана құрал

run_get_method — кез келген TON контрактінің кез келген read-only get-әдісін шақыратын MCP-құрал. Сіз контракт мекенжайын, әдіс атауын және аргументтер тізімін бересіз — құрал әдісті on-chain, TVM арқылы орындап, шығыс стекті қайтарады.

Ал бұл кезде сізге керек емес нәрселер:

• SDK орнату және жаңарту (ton/tonweb/tonutils);
• өз ADNL-клиентіңізді жазу;
• аргументтерді ұяшықтарға қолмен орап, шығыстағы BOC-ты талдау.

run_get_method TONNode-тың — TON үшін hosted MCP-сервердің — оқу жиынтығына кіреді. MCP (Model Context Protocol) — AI-агенттер құралдарды шақыратын стандарт. Оқудың бүкіл жиынтығы npx -y @tonnode/mcp арқылы жергілікті әрі тегін (ашық конфиг, картасыз), не болмаса https://mcp.tonnode.io/mcp hosted-эндпоинті арқылы Bearer-кілтпен қолжетімді. Ештеңе сатып алмай-ақ дәл қазір байқап көруге болады.

Аргументтер мен стек: TVM-ге кірісті қалай беру және шығысты қалай талдау

TVM стекпен жұмыс істейді. Ұқсастық келтірейік: сіз үстелге кіріс мәндері жазылған бірнеше «карточка» қоясыз, әдіс оларды алып, өңдеп, нәтижесі бар «карточкаларды» кері шығарады.

Кіріс TVM стегіне қойылатын мәндер ретінде беріледі. Әдетте бұл:

• int — бүтін сандар (мысалы, индекс, raw-бірліктердегі сома, query id);
• мекенжай-slice — ұяшық тіліміне оралған мекенжай;
• cell — деректердің еркін ұяшығы.

Шығыс мәндердің шығыс стегі ретінде қайтады: int, slice, cell, tuple. Агент оны позициялары бойынша талдайды — бірінші мән, екінші, үшінші. Мысалы, get_jetton_data кезегімен мыналарды қайтарады: total_supply (int), mintable жалаушасы, admin (slice-мекенжай), content (cell) және әмиян коды (cell). Мағынаны позиция айқындайды — бұл контракттің өзінің ABI-келісімінің бөлігі.

Пайдалы әдістердің көбі (seqno, get_jetton_data) кірісті мүлде талап етпейді — аргументтер стегі бос. Аргументтер әдіс бірдеңені кілт бойынша іздейтін жерде пайда болады: мысалы, иесінің мекенжайы бойынша жетон-әмиянның мекенжайын есептеу.

Маңызды нюанс: run_get_method raw-бірліктердегі шикі стекті қайтарады. Сандар қалай бар солай келеді — decimals бойынша қайта есептеусіз әрі ұяшықтарды оқуға болатын жолдарға айналдырусыз. Бұл икемді, бірақ нені оқып отырғаныңызды түсінуді талап етеді — оған get_jetton_info туралы бөлімде ораламыз.

exit_code: әдіс дұрыс орындалғанын қалай түсінуге болады

Get-әдісті әр шақырғанда exit_code, яғни TVM-нің аяқталу коды, қайтарылады. Шығыс стекті талдаудың мәні шақыру сәтті болғанда ғана бар. Get-әдістерге қатысты ереже интуицияға қайшы, сондықтан оны есте сақтаған жөн:

• exit_code 0 және 1 — сәттілік (екеуі де қалыпты аяқталу саналады, сондықтан 1 деген мәннен қорықпаңыз);
• exit_code > 1 — қате, шығыстағы стекке сенуге болмайды.

Жиі кездесетін қате кодтары:

exit_code	Нені білдіреді
2	stack underflow — стекке әдіс күткеннен аз аргумент берілген
4	integer overflow / нөлге бөлу
11	әдетте — жоқ әдісті шақыру (атауындағы қате)
13	out of gas

Іс жүзінде: 2 алдыңыз — барлық аргументті әрі дұрыс ретпен бергеніңізді тексеріңіз. 11 алдыңыз — сірә, әдіс атауында қате жібергенсіз немесе контракт оны іске асырмаған. 13 алдыңыз — әдіс ауыр болып, газ лимитіне тірелген.

Агент арқылы мысалдар: seqno, get_jetton_data, get_sale_data

Ең жағымдысы — run_get_method-ты адам емес, агенттің өзі шақырғанда. Сіз тапсырманы сөзбен айтасыз, агент мекенжайды, әдіс атауын және аргументтерді өзі таңдап, стекті алып, өрістерді түсіндіріп береді.

Жіберу алдындағы seqno. seqno — әмияннан шығатын транзакцияның нөмірі, оны аударымды құрастырар алдында оқиды: онсыз хабарлама өтпейді.

Агентке промпт: «Менің UQD… әмиянымда seqno шақыр да, ағымдағы нөмірді айт».

Агент run_get_method-ты аргументсіз шақырады, шығыс стектен бір int алады да, сізге санды береді.

get_jetton_data — жетон мастерінің метадеректері. Әдіс total_supply-ды, mintable жалаушасын, админ мекенжайын және content-ті қайтарады.

Агентке промпт: «Осы USDT мастерінде get_jetton_data шақыр да, өрістерін жіктеп бер».

Агент run_get_method-ты мастер мекенжайымен және get_jetton_data атауымен шақырады, стекті оқып, позицияларын түсіндіреді. Мұнда маңызды нюанс бар — ол туралы төменде.

get_sale_data — NFT-листингтің деректері. Бұл бөлек NFT-құрал емес, дәл сол run_get_method: сіз маркетплейстегі сату контрактінің өз get-әдісін оқисыз. get_sale_data бағаны, сатушыны, мәміле мәртебесін қайтарады — NFT сатылып кеткенін, әлде әлі сатылымда тұрғанын түсінуге ыңғайлы.

Агентке промпт: «Мына сату контрактінен get_sale_data оқы да, бағаны GRAM-мен айт».

Сіз ешқандай клиент жазбайсыз. Агент бір ғана құралды шақырады. Басқа жиі қолданылатын әдістер — get_wallet_data (жетон-әмиянның деректері), get_pool_data (STON.fi/DeDust пулдары) — дәл осылай шақырылады: әдіс атауы, мекенжай, қажет болса аргументтер.

get_jetton_data немесе get_jetton_info: адам оқитын жауап керек болғанда

Міне, басты қақпан осында. run_get_method шикі стекті қайтарады: get_jetton_data сізге total_supply-ды raw-бірліктердегі алып бүтін сан түрінде, ал content-ті одан әлі атау мен символды суырып алу керек ұяшық түрінде береді. Ешқандай «USDT», «6 decimals» және әдемі сан жоқ — бұл төмен деңгейлі TVM-шығысы. Егер сізге дәл мастер-контрактіге төмен деңгейлі қатынау немесе стандартты емес өріс керек болса — бұл сіздің құралыңыз.

Ал егер тапсырма жетонның атауын, символын және decimals мәнін дайын күйде білу болса, ұяшықтарды талдаумен әуре болмаңыз. Ол үшін бөлек құрал — get_jetton_info бар: ол атауды, символды, decimals-ты және эмиссияны талданған күйде береді.

Бұл неге маңызды: decimals raw-бірліктерді нақты сомаларға қайта есептеу үшін керек. TON желісіндегі USDT-де decimals = 6, жетондардың көпшілігінде — 9. Егер total_supply-ды шикі get_jetton_data-дан алып, 10^decimals-қа бөлмесеңіз, шындықтан миллион не миллиард есе алшақ сан аласыз. Бұл қақпан жайлы толығырақ — TON жетондарындағы decimals талдауында.

Ереже қарапайым:

• контракттің шикі өрістері керек (эмиссия, admin, content, еркін кастом әдіс) → run_get_method + get_jetton_data;
• жетон туралы дайын, адам оқитын жауап керек (атау, символ, decimals) → get_jetton_info.

get_jetton_data-дан шыққан raw-сандарды get_jetton_info-ның дайын жауабымен шатастырмаңыз.

Екі пайдалы көмекші: parse_address және get_account_state

Әдісті шақырар алдында мекенжайды ретке келтіріп, контракттің тірі екеніне көз жеткізген жөн:

• parse_address — мекенжайды EQ/UQ/raw форматтары арасында офлайн, желіге шықпай қалыпқа келтіреді. TON-да формат бірнешеу, әрі әр әдіс олардың кез келгенін қабылдай бермейді; пайдаланушының EQ… мекенжайын аргументтерге қоярдың алдында керекті пішінге келтіру ыңғайлы.
• get_account_state — контракттің мәртебесін, жалаушаларын және соңғы транзакциясын тексереді. Егер аккаунт деплой етілмеген (uninit) не мұздатылған болса, кез келген get-әдіс болжамды түрде құлайды — түсініксіз exit_code ұстағанша, күйін алдын ала тексерген арзанға түседі.

Клиенттің бір жолын да жазбай қалай қосу және шақыру керек

Екі жол бар. Біріншісі — жергілікті әрі тегін, оқудың бүкіл жиынтығы ашық конфиг бойынша, картасыз:

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

@tonnode/mcp пакеті — open source (MIT), npm мен GitHub-та (tonnode/mcp) жатыр, HTTP-аралық қабаттарсыз, TON-ның нативті ADNL-протоколы бойынша жұмыс істейді. Тегін жол туралы бөлек талдау бар — TON үшін MCP тегін.

Екіншісі — кепілді өткізу қабілеті мен өз кілті бар hosted-эндпоинт:

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

Барлық тарифтерде 16 құралдың бәрі қолжетімді — сіз тек өткізу қабілеті үшін төлейсіз. Тегін Hobby кілті (минутына 60 сұрау) кірген бойда, картасыз беріледі.

Қосылғаннан кейін оқудың бүкіл жиынтығы — оның ішінде run_get_method, get_jetton_info, parse_address, get_account_state — агентке кәдімгі құралдар ретінде қолжетімді болады. Шақыру чаттағы қарапайым сөйлем түрінде көрінеді: «мына DeDust пулында get_pool_data шақыр», «мына әмиянның seqno-сын оқы» — агент run_get_method-ты, аргументтерді өзі таңдап, өрістерді түсіндіреді. Ал тапсырма USDT балансын білу болса, дайын бір командалық жол бар: TON-дағы USDT балансы бір шақырумен.

---

Тегін Hobby кілтін алып, run_get_method-ты тікелей агенттен шақырыңыз → tonnode.io/dashboard?plan=hobby. Кілт кірген бойда, картасыз беріледі, минутына 60 сұрау — контракттерді оқуға бұл артығымен жетеді.

Тіркелгіңіз де келмесе — жергілікті іске қосыңыз: npx -y @tonnode/mcp. Құралдардың толық тізімі мен олардың параметрлері — tonnode.io/mcp бетінде.

Блокчейн күйін оқу енді клиент жинау деген сөз емес. Ол — сұрауды тұжырымдау деген сөз.