Як викликати будь-який get-метод контракту TON без SDK

Ви відкрили експлорер, щоб просто дізнатися seqno гаманця перед відправленням транзакції. Або вам потрібен total_supply жетона. Або дані NFT-лістингу з маркетплейсу. І ось ви знову ставите npm i @ton/ton, піднімаєте TonClient, шукаєте робочий ендпоінт лайтсервера, розбираєтеся, як запакувати адресу в beginCell().storeAddress(), а потім ще й парсите вихідний BOC руками. Тридцять рядків коду — заради одного числа, яке контракт і так віддає безкоштовно.

Проблема не в TON. Проблема в тому, що між вами і простим read-only викликом лежить цілий шар SDK, який треба встановити, налаштувати й не зламати під час наступного апдейту. А якщо ви підключаєте до TON ШІ-агента (Claude, Cursor, ChatGPT/Codex), то писати цей шар вручну — взагалі абсурд: агент має просто покликати метод.

Нижче — як викликати будь-який get-метод контракту TON через run_get_method, без жодного рядка SDK-клієнта.

Що таке get-метод контракту TON і чому за ним зазвичай тягнуть 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-клієнт до лайтсервера або HTTP-обгортка на кшталт toncenter, ручне збирання вхідних аргументів у комірки та ручний розбір вихідного BOC. Багато рухомих частин заради одного читання. І кожна з них — точка відмови: публічні лайтсервери з глобального конфігу спільні й лімітовані, під навантаженням відповідають not ready або ADNL-таймаутом; публічні HTTP-API у разі перевищення ліміту віддають 429 Too Many Requests (без ключа — приблизно один запит на секунду).

run_get_method: один інструмент на будь-який read-only метод будь-якого контракту

run_get_method — це MCP-інструмент, який викликає будь-який read-only get-метод будь-якого контракту TON. Ви передаєте адресу контракту, ім'я методу і список аргументів — інструмент виконує метод on-chain через TVM і повертає вихідний стек.

Що вам при цьому не потрібно:

• ставити й оновлювати SDK (ton/tonweb/tonutils);
• писати власний ADNL-клієнт;
• вручну пакувати аргументи в комірки та парсити BOC на виході.

run_get_method входить до набору читання TONNode — hosted MCP-сервера для TON. MCP (Model Context Protocol) — це стандарт, за яким ШІ-агенти викликають інструменти. Увесь набір читання доступний безкоштовно локально через npx -y @tonnode/mcp (публічний конфіг, без картки) або через hosted-ендпоінт https://mcp.tonnode.io/mcp за 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 — успіх (обидва вважаються нормальним завершенням, тож не лякайтеся одиниці);
• 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 — номер вихідної транзакції гаманця, його читають перед тим, як зібрати переказ: без нього повідомлення не пройде.

Промпт агенту: «Поклич seqno на моєму гаманці UQD… і скажи поточний номер».

Агент викликає run_get_method без аргументів, отримує одне int на вихідному стеку і віддає вам число.

get_jetton_data — метадані майстра жетона. Метод повертає total_supply, прапорець mintable, адресу адміна і content.

Промпт агенту: «Виклич get_jetton_data на цьому майстрі USDT і розклади поля».

Агент смикає 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-одиниць у реальні суми. У USDT у мережі TON decimals = 6, у більшості жетонів — 9. Якщо взяти total_supply із сирого get_jetton_data і не поділити на 10^decimals, отримаєте число, що відрізняється від реального в мільйон або мільярд разів. Докладніше про цю пастку — в розборі decimals у жетонів TON.

Правило просте:

• потрібні сирі поля контракту (емісія, admin, content, довільний кастомний метод) → run_get_method + get_jetton_data;
• потрібна готова читабельна відповідь про жетон (ім'я, символ, decimals) → get_jetton_info.

Не плутайте raw-числа з get_jetton_data з готовою відповіддю 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), працює за нативним ADNL-протоколом TON, без HTTP-прошарків. Про безкоштовний шлях є окремий розбір — MCP для TON безкоштовно.

Другий — 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 — доступний агенту як звичайні інструменти. Виклик виглядає як звичайна фраза в чаті: «виклич get_pool_data на цьому пулі DeDust», «прочитай seqno ось цього гаманця» — і агент сам добере run_get_method, аргументи й пояснить поля. А якщо завдання — дізнатися баланс USDT, є готовий однокомандний шлях: баланс USDT на TON одним викликом.

---

Візьміть безкоштовний ключ Hobby і покличте run_get_method прямо з агента → tonnode.io/dashboard?plan=hobby. Ключ видається одразу після входу, без картки, 60 запитів на хвилину — цього із запасом вистачає, щоб читати контракти.

Не хочете навіть реєструватися — запустіть локально: npx -y @tonnode/mcp. Повний список інструментів та їхні параметри — на сторінці tonnode.io/mcp.

Прочитати стан блокчейну більше не означає збирати клієнт. Означає — сформулювати запит.