SDK для TON: tonweb vs ton-core vs tonconnect-sdk — что выбрать в 2026

TL;DR. К середине 2026 на TON есть три рабочих TypeScript-SDK с разными задачами: tonweb (старый, легаси, не рекомендуется для новых проектов), @ton/ton + @ton/core (современный, recommended, написан с типизацией и promise-based API), @tonconnect/sdk + ui-react (для интеграции TON Connect 2.0 в dApp). В типичном production-проекте используется связка @ton/ton (бэкенд + on-chain логика) + @tonconnect/sdk (фронтенд-юзер-flow). Ниже — детальное сравнение, выбор по сценарию и пример полного стека.

Зачем выбирать SDK

Вы пишете на TypeScript/JavaScript, и вам нужно одно из:

1. Прочитать баланс адреса или метаданные jetton’а.
2. Сформировать и отправить транзакцию от имени кошелька.
3. Подключить пользовательский TON-кошелёк к своему dApp.
4. Парсить Cell, BoC, message формат.
5. Подписать данные, верифицировать подпись.
6. Обработать webhook от индексатора (новые транзакции).

Каждая из этих задач имеет один или два «правильных» SDK. Использование чужого приводит к unnecessary боли.

Обзор трёх главных SDK

1. tonweb — легаси

Origin: первый широко используемый JS-SDK для TON, развивался 2020-2022 командой Tonkeeper.

const TonWeb = require('tonweb');
const tonweb = new TonWeb();

// Получить баланс
const balance = await tonweb.provider.getBalance('EQA...');
console.log(balance);  // string в нанотонах

Плюсы:

• Хорошо документирован для базовых сценариев.
• Покрывает старые wallet-контракты (v3, v4).
• Включает дополнительные tools: ton-connect-mock, payment-channels.

Минусы:

• Нет TypeScript-типов из коробки.
• Callback-style во многих местах.
• Cell API странный (.beginCell(), .storeUint() идут не так чисто, как в @ton/core).
• API не унифицировано: где-то возвращает Promise, где-то — callback’и.
• Не поддерживает Wallet v5.

Когда использовать: только если поддерживаете старую кодовую базу на tonweb или вам нужен один специфичный helper. Никогда — для нового кода.

2. @ton/ton + @ton/core — современный стек

Origin: переписан с нуля в 2023, маинтейнят TON Foundation + сообщество.

import { TonClient, Address, beginCell, toNano } from '@ton/ton';

const client = new TonClient({
  endpoint: 'https://toncenter.com/api/v2/jsonRPC',
});

const address = Address.parse('EQA...');
const balance = await client.getBalance(address);
console.log(balance);  // bigint в нанотонах

Пакеты:

• @ton/core — типы Cell, Address, Slice, Builder; парсинг BoC; format helpers (toNano, fromNano).
• @ton/crypto — mnemonic↔key, sign/verify, sha256/sha512.
• @ton/ton — TonClient (RPC), wallet contracts V3/V4/V5, helpers для jetton/NFT.

Плюсы:

• Full TypeScript-типизация, IDE-помощь работает.
• Promise-based, async/await везде.
• Разбит на пакеты — устанавливаете только нужное (на бекенде @ton/core достаточно для парсинга, без TonClient).
• Активная разработка, новые wallet-версии добавляются быстро.
• Совместим с обоими RPC: Toncenter и TonAPI.

Минусы:

• Документация местами неполная — приходится ориентироваться на исходники.
• API меняется (минор-релизы могут ломать совместимость).

Когда использовать: по умолчанию для всего нового. Без вариантов на 2026.

3. @tonconnect/sdk + @tonconnect/ui-react — для frontend

Origin: специализированный SDK для протокола TON Connect 2.0.

import { TonConnectUI } from '@tonconnect/ui';

const tonConnectUI = new TonConnectUI({
  manifestUrl: 'https://yourdomain.com/tonconnect-manifest.json',
});

// Подключение кошелька
await tonConnectUI.openModal();
const wallet = await tonConnectUI.connector.connect({ ... });

Подпакеты:

• @tonconnect/sdk — низкоуровневый, без UI. Для серверных сценариев и кастомных интерфейсов.
• @tonconnect/ui — готовая UI-кнопка и модалка (vanilla).
• @tonconnect/ui-react — React-компоненты (<TonConnectButton />, hooks useTonConnectUI, useTonAddress).

Плюсы:

• Из коробки готовая UI для подключения.
• Поддерживает все основные TON-кошельки (Tonkeeper, MyTonWallet, Wallet-в-Telegram, Bitget, OKX).
• TonProof v2 для Sign-in with TON встроен.
• Реагирует на disconnect/reconnect/network change.

Минусы:

• Большой bundle (~50KB gzipped даже минимальный).
• Только для frontend / mini-app.
• Не сделает transaction parsing — это задача @ton/ton.

Когда использовать: всегда при работе с пользовательскими кошельками в браузере / Telegram Mini App. На бэкенде не нужен (там работаете с @ton/ton).

Сравнительная таблица

Типичный стек 2026

Полный TypeScript-проект на TON выглядит так:

// Frontend (Mini App в Telegram):
// - @tonconnect/ui-react для connect + sign
// - @ton/core для парсинга incoming data
// - axios для запросов к backend

// Backend (Node.js):
// - @ton/ton для RPC к Toncenter/TonAPI
// - @ton/core для парсинга Cell
// - @ton/crypto для mnemonic операций
// - Сервер делает все sensitive operations (deploy, mint, signature verify)

// On-chain (smart contract):
// - Tolk / FunC / Tact код
// - Acton для тестов и деплоя
// - @ton/sandbox только если вы не используете Acton (легаси)

Сценарий 1: Простой dApp — кошелёк подключение + send transaction

Frontend (React):

import { TonConnectUIProvider, TonConnectButton, useTonConnectUI, useTonAddress } from '@tonconnect/ui-react';
import { beginCell, toNano, Address } from '@ton/core';

function App() {
  return (
    <TonConnectUIProvider manifestUrl="/tonconnect-manifest.json">
      <SendButton />
    </TonConnectUIProvider>
  );
}

function SendButton() {
  const [tonConnectUI] = useTonConnectUI();
  const address = useTonAddress();

  async function sendOneTon() {
    const body = beginCell()
      .storeUint(0, 32)
      .storeStringTail('Hello TON!')
      .endCell();

    await tonConnectUI.sendTransaction({
      validUntil: Math.floor(Date.now() / 1000) + 300,
      messages: [
        {
          address: 'EQA...recipient',
          amount: toNano('1').toString(),
          payload: body.toBoc().toString('base64'),
        },
      ],
    });
  }

  return (
    <>
      <TonConnectButton />
      {address && <button onClick={sendOneTon}>Send 1 TON</button>}
    </>
  );
}

Здесь используется: @tonconnect/ui-react (для подключения и sendTransaction) + @ton/core (для построения payload). На бэкенде в этом сценарии может не быть TON-кода вообще.

Сценарий 2: Backend для приёма платежей

Node.js:

import { TonClient, Address } from '@ton/ton';
import { TonApiClient } from '@ton-api/client';

const tonClient = new TonClient({
  endpoint: 'https://toncenter.com/api/v2/jsonRPC',
  apiKey: process.env.TONCENTER_API_KEY,
});

const tonapi = new TonApiClient({ apiKey: process.env.TONAPI_KEY });

const MY_ADDRESS = Address.parse('EQA...');

async function watchIncomingPayments() {
  let lastLt = 0n;
  while (true) {
    const txs = await tonapi.blockchain.getBlockchainAccountTransactions(
      MY_ADDRESS.toString(),
      { limit: 50, after_lt: lastLt.toString() },
    );

    for (const tx of txs.transactions) {
      const inMsg = tx.in_msg;
      if (inMsg && inMsg.value && BigInt(inMsg.value) > 0n) {
        const comment = inMsg.decoded_body?.text || '';
        console.log(`Received ${Number(inMsg.value) / 1e9} TON, comment: "${comment}"`);
        // Match comment with pending order, mark as paid
      }
      lastLt = BigInt(tx.lt);
    }

    await new Promise(r => setTimeout(r, 3000));
  }
}

watchIncomingPayments();

Здесь @ton/ton (для базовых типов и RPC fallback) + TonAPI (для индексированного запроса транзакций).

Сценарий 3: Программная отправка от кошелька (без UI)

Полностью серверный сценарий — например, для бота-выплат:

import { TonClient, WalletContractV5R1, internal } from '@ton/ton';
import { mnemonicToWalletKey } from '@ton/crypto';

async function sendFromBot() {
  const key = await mnemonicToWalletKey(
    process.env.BOT_MNEMONIC!.split(' '),
  );
  const wallet = WalletContractV5R1.create({
    workchain: 0,
    publicKey: key.publicKey,
  });

  const tonClient = new TonClient({
    endpoint: 'https://toncenter.com/api/v2/jsonRPC',
  });
  const contract = tonClient.open(wallet);

  await contract.sendTransfer({
    seqno: await contract.getSeqno(),
    secretKey: key.secretKey,
    messages: [
      internal({
        to: 'EQA...recipient',
        value: '0.5',
        body: 'Daily reward',
      }),
    ],
  });
}

Здесь только @ton/ton + @ton/crypto. TonConnect не нужен — кошелёк управляется приватным ключом (mnemonic) напрямую.

Сценарий 4: Парсинг сложной jetton transfer’a

Webhook от TonAPI пришёл с jetton transfer’ом, нужно достать metadata:

import { Cell, Address } from '@ton/core';

function parseJettonTransfer(bocBase64: string) {
  const cell = Cell.fromBase64(bocBase64);
  const slice = cell.beginParse();

  const op = slice.loadUint(32); // 0x0f8a7ea5 = jetton transfer
  const queryId = slice.loadUint(64);
  const amount = slice.loadCoins();
  const destination = slice.loadAddress();
  const responseDest = slice.loadAddress();

  return { op, queryId, amount, destination, responseDest };
}

Здесь только @ton/core — больше ничего и не нужно (offline парсинг).

Распространённые ошибки

1. Использование address.toString() без bouncable-флага. В @ton/ton адреса по умолчанию non-bouncable (UQ…), а многие API ожидают bouncable (EQ…). Решение: address.toString({ bounceable: true }).

2. Смешивание tonweb и @ton/ton в одном проекте. Их Cell-форматы несовместимы; конверсии через BoC base64. Делайте миграцию полностью, не частично.

3. Не учитывать газ при sendTransaction. Если в payload указано value: '0.05', а сам transfer requires 0.1 TON gas — транзакция bouncнется. Берите запас на gas в payload value.

4. Хранение mnemonic в .env в репозитории. Никогда. Используйте secret manager (Vault, AWS Secrets Manager) или hardware security module для production.

5. Полинг RPC вместо webhook. Если у вас много кошельков для мониторинга — настройте webhook через TonAPI вместо polling. Polling сжигает квоту и медленнее реагирует.

Что выбрать в итоге

• Новый dApp (frontend + backend) с подключением кошелька → @tonconnect/ui-react + @ton/ton.
• Backend бот для приёма платежей → @ton/ton + (опционально) TonAPI.
• Indexer / Aggregator → @ton/core + TonAPI webhook + Redis.
• Mass payout (массовая выплата с одного кошелька) → @ton/ton + @ton/crypto.
• Mini App в Telegram → @tonconnect/ui-react + @ton/core (минимальный bundle).
• Поддержка старой кодовой базы → tonweb (но планируйте миграцию).

Итого

В 2026 default-выбор для новых TON-проектов — это @ton/ton + @ton/core для всего, что не UI, плюс @tonconnect/sdk/ui-react для интеграции пользовательского кошелька. tonweb имеет смысл только в legacy-контексте. SDK для других языков (Python pytoniq-core, Go tonkit-go) работают, но coverage хуже — для critical-path кода TypeScript остаётся базовым.

Гайды по конкретным сценариям:

• TON Connect 2.0 + TonProof: Sign-in with TON
• Приём TON в Telegram-боте
• ACTON: первый смарт-контракт