Як ШІ-агенту свапати токени на TON некастодіально

Хто тримає ключ — головне питання некастодіального свопу токенів на TON агентом

Уявіть: ви доручаєте ШІ-агенту стежити за курсом і, коли USDT просяде, докупити його за GRAM. Агент оцінює ринок, знаходить момент, готує угоду — і тут постає питання, про яке зазвичай згадують надто пізно. Щоб агент реально виконав своп, хтось має підписати транзакцію приватним ключем. Хто тримає цей ключ?

Якщо відповідь — «сервіс, через який працює агент», то ви віддали чужому коду право розпоряджатися вашими грошима. Одна промпт-ін'єкція, один витік логів — і агент підписує зовсім не те, що ви думали. І проблема тут не в тому, «як смикнути DEX», а в тому, як дати агентові зібрати угоду, залишивши підпис строго за гаманцем людини. Нижче розберемо, як зробити своп токенів TON агентом некастодіально.

Дві частини свопу: розрахунок безпечний, підпис — ні

У свопу на DEX дві принципово різні частини. Перша — обчислювальна й безпечна: дізнатися курс, порахувати проковзування, зібрати тіло транзакції. Друга — незворотна й небезпечна: підписати це тіло приватним ключем і відправити в мережу. Звідси й розвилка:

• Кастодіальна модель. Агент (або сервер за ним) тримає ключ і підписує сам. Зручно — агент діє автономно. Але ключ підпису опиняється поруч із LLM, а LLM — недетермінована штука, яку можна вмовити недовіреним текстом (описи жетонів, відповіді інших інструментів, повідомлення користувача). Саме так, наприклад, і влаштовано офіційний @ton/mcp від TON Foundation: це агент-гаманець з operator-ключем, який самостійно підписує відправлення й своп (схема split-key: operator-ключ в агента, owner-ключ у користувача). Модель робоча, у неї є сильні сторони — автономні витрати коштів, робота з NFT і DNS, статус офіційного пакета. Але це довіра до тримача ключа.
• Некастодіальна модель. Сервер лише готує транзакцію і повертає її непідписаною. Підпис ставить гаманець користувача через TonConnect. Сервер ніколи не бачить і не зберігає приватний ключ.

Для торгового агента, який крутиться цілодобово, друга модель знімає головний ризик: навіть якщо інфраструктуру скомпрометовано, максимум, що «зіпсується», — непідписана заготовка, яку ви все одно підтверджуєте вручну або політикою свого гаманця. Докладніше цю розвилку розібрано в чесному порівнянні TONNode з офіційним @ton/mcp.

Некастодіальна модель TONNode: сервер віддає непідписану транзакцію

TONNode — це hosted MCP-сервер для TON. MCP (Model Context Protocol) — стандарт, за яким ШІ-агенти (Claude, Cursor, ChatGPT/Codex і будь-який MCP-клієнт) викликають зовнішні інструменти. TONNode дає агентові 16 інструментів для роботи з TON, і інструменти свопу, кросчейну та генерації гаманця строго некастодіальні.

Ключовий інваріант: сервер НІКОЛИ не підписує і не зберігає кошти та приватні ключі. Для свопу це означає, що підсумковий інструмент повертає не «виконану угоду», а непідписане TonConnect-повідомлення — готовий до підпису об'єкт. Сервер фізично не може підмінити отримувача коштів після підпису, бо підпису в нього немає.

Своп у TONNode — це рівно два інструменти:

• get_swap_quote — тверде котирування,
• build_swap_tx — непідписана транзакція, готова для TonConnect.

Обидва працюють через протокол Omniston, який агрегує ліквідність STON.fi і DeDust одразу — котирування рахується за обома DEX, і ви отримуєте найкраще з доступних. Своп іде в парах GRAM⇄жетон. GRAM — це перейменований Toncoin (перейменований у червні 2026); сама мережа, як і раніше, називається TON. Тобто «GRAM» у котируванні — це нативна монета мережі.

get_swap_quote: тверде котирування через Omniston (STON.fi + DeDust)

Перший крок — дізнатися, скільки ви реально отримаєте. get_swap_quote повертає тверде котирування: очікувану суму на виході та курс. Оскільки під капотом Omniston опитує STON.fi і DeDust одночасно, агентові не треба самому обходити пули й порівнювати вручну — він бачить уже агрегований результат.

Отримай котирування на своп 100 USDT → GRAM.
Використай get_swap_quote. Покажи очікуваний вихід і курс.

Важливий нюанс, через який котирування часто рахують неправильно: котирування оперує raw-одиницями (мінімальними неподільними частками токена), а не «людськими» числами. Тому перш ніж рахувати суму свопу жетона, треба знати його decimals.

get_jetton_info: навіщо потрібні decimals перед свопом (USDT = 6)

Ось типова помилка, яка ламає свопи: агент бере «100 USDT» і підставляє 100 у поле суми. Але on-chain у жетона немає поняття «100» — є лише raw-одиниці. Скільки raw-одиниць в одному токені, задає параметр decimals, а сума рахується як кількість × 10^decimals.

• У USDT на TON decimals = 6 → 100 USDT — це 100 × 10^6 = 100 000 000 raw-одиниць.
• У більшості жетонів decimals = 9 → 100 токенів — це 100 000 000 000 raw-одиниць.

Якщо наївно дописати до «100 USDT» дев'ять нулів (як у GRAM), ви запросите своп на суму, в 1000 разів більшу за задуману. Помилитися на три порядки тут дуже легко. Тому get_jetton_info — обов'язковий крок: він повертає ім'я, символ, decimals та емісію жетона.

Перед свопом дізнайся decimals вхідного жетона через get_jetton_info,
і лише потім рахуй суму в raw-одиницях.

Глибше цю тему розібрано в статті про підключення ШІ-агентів до TON через MCP.

Допоміжні інструменти: parse_address і get_jetton_balance

Стануть у пригоді й два допоміжні інструменти, які варто викликати перед збиранням транзакції:

• parse_address — офлайн-перевірка та конвертація адреси (EQ/UQ/raw). Дешева страховка від одруку в адресі жетона чи отримувача до того, як щось збирати.
• get_jetton_balance — баланс жетона за основною адресою гаманця. Адресу джетон-гаманця для балансу інструмент обчислює он-чейн сам, тож передавати треба основну адресу, а не адресу джетон-гаманця. Часта помилка — підсунути адресу джетон-гаманця; не треба, дайте основну.

build_swap_tx: непідписане повідомлення для TonConnect

Коли котирування отримано й суми пораховано в правильних raw-одиницях, build_swap_tx збирає саму транзакцію. І ось тут — суть некастодіальності: інструмент повертає НЕПІДПИСАНЕ TonConnect-повідомлення. Це не відправлена угода, а заготовка: адреса контракту, сума, payload. Сервер віддав вам «конверт», але не запечатав його — печатку (підпис) ставить ваш гаманець.

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

Збери транзакцію свопу за останнім котируванням через build_swap_tx.
Поверни непідписане TonConnect-повідомлення — я підпишу його в гаманці.

Повний потік: від котирування до підпису в гаманці

Типова послідовність для свопу жетона має такий вигляд:

1. parse_address — перевірити й нормалізувати адресу жетона та отримувача (офлайн).
2. get_jetton_info — дізнатися decimals (для USDT — 6, найчастіше — 9), ім'я, символ.
3. get_jetton_balance — переконатися, що коштів вистачає (основна адреса, не джетон-гаманець).
4. get_swap_quote — отримати тверде котирування через Omniston (STON.fi + DeDust).
5. build_swap_tx — зібрати непідписану TonConnect-транзакцію.
6. Гаманець користувача підписує через TonConnect — підпис на боці користувача.

На рівні промпту для агента це звучить природно:

Хочу обміняти 50 GRAM на USDT.
Спершу перевір адресу жетона USDT через parse_address,
дізнайся його decimals через get_jetton_info,
перевір баланс через get_jetton_balance,
візьми котирування get_swap_quote і збери транзакцію build_swap_tx.
Транзакцію не відправляй — поверни мені непідписане повідомлення для TonConnect.

Агент сам розкладе це на виклики інструментів, а на виході ви отримаєте заготовку, яку підписуєте у своєму гаманці. Зверніть увагу: останній крок — не інструмент TONNode. Підпис виконує гаманець, і саме тут проходить некастодіальна межа. Якщо будуєте повноцінного торгового агента, погляньте на розбір затримок і латентності під час торгівлі на TON — там цей потік вбудовано в цикл ухвалення рішень. А для угод за межами TON у TONNode є п'ять некастодіальних кросчейн-інструментів на базі атомарного HTLC-ескроу.

Як підключити інструменти свопу до Claude, Cursor чи ChatGPT

Інструменти свопу доступні на всіх тарифах, включно з безкоштовним Hobby (60 запитів/хв), адже Hobby — це hosted-ключ. Платите ви лише за пропускну здатність, набір із 16 інструментів однаковий на всіх ключах.

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

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

Hosted-ендпоінт — для свопу та решти. Власний ключ (безкоштовного Hobby достатньо), гарантована пропускна здатність і всі 16 інструментів, включно з get_swap_quote і build_swap_tx:

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

Цей конфіг додають у налаштування MCP вашого клієнта — Claude Desktop, Cursor, ChatGPT/Codex чи будь-якого іншого MCP-сумісного агента. Після підключення hosted-ключа інструменти get_swap_quote і build_swap_tx з'являються в агента автоматично. Ключ tn_live_… видається одразу після входу, без картки.

Коротко про головне

• Своп у TONNode — це два інструменти: get_swap_quote (тверде котирування) і build_swap_tx (непідписана транзакція для TonConnect).
• Обидва йдуть через Omniston — агрегатор ліквідності STON.fi і DeDust.
• Підпис завжди в користувача. Сервер не зберігає й не підписує ключі — на відміну від кастодіального офіційного @ton/mcp.
• Перед свопом жетона дізнайтеся decimals через get_jetton_info (USDT = 6, більшість = 9), інакше сума в raw-одиницях порахується неправильно.
• Своп-інструменти працюють на будь-якому hosted-ключі, включно з безкоштовним Hobby.

Некастодіальний своп на TON для агента — це дисципліна розділення ролей: сервер рахує і збирає, гаманець підписує. У TONNode це рівно два інструменти поверх Omniston плюс get_jetton_info для коректних decimals — і жоден приватний ключ не залишає користувача.

Почати найпростіше з безкоштовного ключа. Отримайте Hobby-ключ без картки й підключіть інструменти свопу за кілька хвилин: tonnode.io/dashboard?plan=hobby. Хочете спершу роздивитися весь набір інструментів — зазирніть на сторінку інструментів.