Как вызвать любой 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.

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