Як зібрати торгового агента на TON: читати, котирувати, свапати

Проблема, з якої починається будь-який торговий агент на TON

Ви просите ШІ-агента «свапнути 50 USDT у GRAM, коли ціна просяде» — а він відправляє транзакцію на 50 000 USDT замість 50. Бо USDT у TON має decimals = 6 (50 USDT = 50 000 000 raw-одиниць), а агент за замовчуванням порахував як для звичайного жетона з дев'ятьма нулями — і заклав суму в 1000 разів більшу. Помилка в 1000 разів, реальні гроші, незворотна транзакція. Той самий корінь має й дзеркальна помилка: агент бачить на балансі сире 1000000000 і впевнено рапортує «у вас мільярд USDT», хоча там 1000.

Це не вигадані страшилки, а саме ті граблі, на які наступає кожен, хто підключає LLM до DeFi на TON безпосередньо через сирі RPC: переплутані decimals, неможливість прочитати баланс жетона без адреси жетон-гаманця, приватний ключ, що витік через контекст. Нижче — як зібрати торгового агента на TON (trading agent TON), який читає баланси, бере тверде котирування і збирає своп, жодного разу не торкнувшись ваших ключів. Інструмент — TONNode, hosted MCP-сервер для TON.

Що таке торговий агент на TON і навіщо йому MCP

Торговий агент — це LLM (Claude, Cursor, Codex або будь-який інший MCP-клієнт), яка на запит користувача вміє читати стан мережі та готувати угоди: «покажи мій баланс USDT», «скільки GRAM я отримаю за 500 USDT», «збери своп». Сама по собі модель блокчейн не бачить — їй потрібні інструменти.

Саме це й робить MCP (Model Context Protocol) — стандарт, за яким агенти викликають зовнішні інструменти. Замість того щоб навчати модель складати сирі ADNL-запити й парсити BOC-комірки, ви віддаєте їй набір типізованих функцій: «дай баланс», «дай котирування», «збери транзакцію». TONNode підключається як джерело таких інструментів і дає агенту рівно 16 функцій для роботи з мережею: читання, своп, кросчейн, генерація гаманця.

Торговому агенту з них потрібні п'ять, і всі п'ять доступні навіть на безкоштовному тарифі:

читати (get_balance, get_jetton_balance)
   -> уточнити decimals (get_jetton_info)
      -> котирувати (get_swap_quote)
         -> зібрати своп (build_swap_tx)
            -> гаманець підписує через TonConnect

Ключова деталь останнього кроку: підписує гаманець користувача, а не сервер. TONNode повертає непідписані повідомлення — чому це принципово, розберемо наприкінці.

Крок 1: агент читає баланси (get_balance, get_jetton_balance)

Перш ніж щось свапати, агент має зрозуміти, чим він розпоряджається. Два інструменти:

• get_balance — баланс GRAM на адресі. GRAM — це перейменований у червні 2026 року Toncoin; сама мережа, як і раніше, називається TON.
• get_jetton_balance — баланс жетона: USDT, NOT, будь-якого іншого. Магія тут у тому, що жетон-гаманець обчислюється ончейн. Ви передаєте адресу власника і майстер-адресу жетона, а TONNode сам виводить адресу жетон-гаманця і читає його баланс. Не треба заздалегідь знати цю адресу і десь її зберігати.

Промпт агенту виглядає буквально так:

Перевір баланс гаманця UQAbc...xyz:
скільки на ньому GRAM і скільки USDT?

Під капотом модель викликає get_balance для нативного балансу і get_jetton_balance для USDT. Одна біда: те, що повернеться, — це ще не «людські» суми, а сирі одиниці. І ось тут починається найважливіше. Про те, як отримати баланс USDT одним викликом без танців з адресами жетон-гаманців, є окремий розбір: /blog/usdt-balance-ton-one-call.

decimals вирішують усе: get_jetton_info і чому USDT = 6

Баланси й суми в TON зберігаються в raw-одиницях — цілих числах без дробової частини. Щоб отримати зрозумілу людині суму, сире число треба поділити на 10^decimals. І ось заковика: різні жетони мають різну кількість decimals.

• USDT має decimals = 6. Тобто 1 USDT = 1 000 000 raw-одиниць.
• Більшість жетонів у TON мають decimals = 9 (як і GRAM). Тобто 1 жетон = 1 000 000 000 raw-одиниць.

Переплутати 6 і 9 — це помилитися в сумі рівно в 1000 разів. Той самий «мільярд USDT» з початку статті. Для торгового агента це не косметика, а корінь довіри: якщо він плутає порядки, йому не можна давати збирати угоди.

Тому в конвеєр вбудовується get_jetton_info — він віддає метадані жетона: ім'я, символ, емісію і — найважливіше — decimals. Правильна логіка всередині агента:

raw       = get_jetton_balance(...)   // наприклад, 1000000000
decimals  = get_jetton_info(...)      // для USDT → 6
human     = raw / 10 ** decimals      // 1000000000 / 1e6 = 1000 USDT

Той самий raw при decimals = 9 дав би 1 токен — різниця колосальна. Не хардкодьте decimals у промпті й не дозволяйте моделі «додумувати» їх з пам'яті: на новому жетоні вона помилиться. Нехай щоразу тягне їх із get_jetton_info і перераховує за фактичним значенням. Детально про цю пастку і про те, чому вона коштує людям грошей: /blog/jetton-decimals-ton.

Крок 2: тверде котирування через Omniston (get_swap_quote)

Баланси прочитані й перераховані в правильних одиницях — тепер агенту потрібна ціна. У DeFi «приблизна ціна з голови» не працює: ліквідність розпорошена по кількох DEX, курс рухається, і агент має спиратися на актуальне котирування, а не на здогадку.

get_swap_quote дає тверде котирування на своп GRAM ⇄ жетон через протокол Omniston, який агрегує ліквідність одразу двох найбільших DEX у TON — STON.fi і DeDust. Агенту не треба самому опитувати пули, порівнювати ціни й рахувати прослизання: Omniston повертає найкращий маршрут з об'єднаної ліквідності.

Дай котирування: скільки GRAM я отримаю за 50 USDT просто зараз?

Модель викликає get_swap_quote із сумою 50000000 (ті самі raw-одиниці з попереднього кроку) й отримує конкретні числа: скільки на вході, скільки на виході, яким маршрутом, з яким прослизанням. Це точка ухвалення рішення: якщо агент має умову («свапай, лише якщо курс кращий за X»), він порівнює котирування з порогом і або йде далі, або чекає наступної ітерації. Важливо: котирування — це ще не угода. Жодні кошти не рухаються, нічого не підписується. Це чисте читання ринку.

Крок 3: збірка непідписаного свопу (build_swap_tx) і підпис у гаманці

Користувач побачив котирування і каже «так, свапаємо». Агент викликає build_swap_tx й отримує непідписану транзакцію свопу, готову для TonConnect.

Підкреслю слово «непідписану». Сервер збирає коректне повідомлення — адресу отримувача, payload, суму, параметри маршруту — і повертає його як є. Далі повідомлення йде в гаманець користувача (Tonkeeper, MyTonWallet, будь-який TonConnect-сумісний), користувач бачить, що саме підписує, і підтверджує сам. Підпис ставить приватний ключ користувача, який живе в його гаманці, а не на сервері.

get_balance / get_jetton_balance   →  прочитати, що є
        ↓
get_jetton_info                     →  уточнити decimals, перерахувати
        ↓
get_swap_quote (Omniston)           →  тверде котирування
        ↓
build_swap_tx                       →  непідписана транзакція
        ↓
гаманець користувача (TonConnect)   →  підпис і відправлення

Кожен крок — окремий явний виклик інструмента. Агент нічого не «доробляє на власний розсуд» із грошима: він готує, а рішення і підпис лишаються за людиною. Повний сценарій некастодіального свопу, від котирування до підпису, розібрано покроково тут: /blog/agent-swap-ton-noncustodial.

Некастодіальність: чому сервер ніколи не тримає ключі агента

Це не маркетингове формулювання, а архітектурна межа. Інструменти свопу, кросчейну й генерації гаманця в TONNode строго некастодіальні:

• Сервер ніколи не підписує транзакції.
• Сервер ніколи не зберігає приватні ключі та кошти.
• Усе, що він віддає назовні, — це непідписані TonConnect-повідомлення.

Чому це важливо саме для торгового агента? Бо агент за визначенням працює з грошима і за визначенням може помилитися — не так зрозуміти запит, переплутати суму, зациклитися. Якби ключі лежали на сервері і він підписував сам, помилка агента означала б втрату коштів без вашого відома. У некастодіальній схемі останній рубіж — ви: жодна транзакція не піде в мережу, поки її не підтвердить ваш гаманець.

Порівняйте з офіційним @ton/mcp від TON Foundation — це кастодіальний агент-гаманець: він тримає operator-ключ і підписує сам (схема split-key, де operator-ключ в агента, а owner-ключ у користувача). Він має свої сильні сторони — автономне витрачання коштів без участі людини, робота з NFT і DNS, офіційний статус Foundation. Але модель довіри інша: там агент реально може рухати кошти. TONNode свідомо обирає протилежну межу: сервер не підписує взагалі нічого. Розгорнуте порівняння двох підходів: /blog/custodial-vs-noncustodial-mcp.

Як підключити і з чого почати за 5 хвилин

Гарна новина: щоб зібрати торговий конвеєр, платити не потрібно. Але важливо не плутати два безкоштовні шляхи — у них різний набір інструментів.

Локальний публічний конфіг дає повний набір читання (8 інструментів: get_masterchain_info, get_balance, get_account_state, get_transactions, run_get_method, get_jetton_balance, parse_address, get_jetton_info). Ставиться через npx, без ключа:

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

Пакет @tonnode/mcp — open source (MIT), лежить на npm і GitHub (tonnode/mcp), працює за нативним ADNL-протоколом TON без HTTP-прошарків між агентом і мережею. Вставили конфіг у Claude Desktop, Cursor чи будь-який MCP-клієнт — і агент уже вміє читати баланси й смикати get_jetton_info.

А ось самі котирування — get_swap_quote і build_swap_tx — належать до групи СВОП і йдуть через hosted-ендпоінт. Ключовий момент: на безкоштовному ключі Hobby доступні всі 16 інструментів, включно з котируванням і збіркою свопу. Тобто весь торговий конвеєр (читання → котирування → своп) збирається безкоштовно — але саме через hosted-ключ Hobby, а не через локальний публічний конфіг. Конфіг для hosted-ендпоінта:

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

TONNode має рівно 16 інструментів, і на всіх тарифах доступні всі 16 — ви платите лише за пропускну здатність, а не за функціональність:

• Hobby — безкоштовно назавжди, 60 запитів/хв, без картки.
• Pro — $29/міс, 300 запитів/хв.
• Scale — $199/міс, 1200 запитів/хв.

Для старту й перших прогонів торгового конвеєра безкоштовного ключа Hobby вистачає із запасом: 60 запитів на хвилину — це багато послідовних викликів агента. Картка не потрібна, ключ видається одразу після входу.

Отримати безкоштовний ключ Hobby (60 req/min, без картки): tonnode.io/dashboard?plan=hobby

Повний список із 16 інструментів: tonnode.io/mcp · Тарифи: tonnode.io/pricing

---

Зберіть конвеєр із п'яти інструментів — get_balance, get_jetton_balance, get_jetton_info, get_swap_quote, build_swap_tx — тримайте decimals під контролем і віддавайте підпис гаманцю. Так у вас вийде торговий агент, який чесно читає баланси, бере тверде котирування і готує своп на реальні суми, ні на секунду не отримавши доступу до чужих ключів. Саме так і має працювати торговий агент на TON.