TON API и SDK: работа с блокчейном

Выбор правильного API и SDK — это фундаментальное инфраструктурное решение, которое определяет производительность, надёжность и стоимость обслуживания вашего приложения. В экосистеме TON существует несколько провайдеров API (TonCenter, TonAPI, Tonconsole), каждый со своими преимуществами. Неправильный выбор приводит к downtime, превышению лимитов и деградации пользовательского опыта.

При разработке приложений для TON вам не нужно запускать собственную ноду, чтобы читать данные из блокчейна или отправлять транзакции. Экосистема TON предоставляет несколько API-провайдеров с разными уровнями абстракции — от низкоуровневых RPC-запросов до обогащённых данных с метаданными токенов. В этом уроке мы разберём ландшафт API-экосистемы, сравним основных провайдеров и научимся работать с SDK.

Ландшафт API-экосистемы TON

В отличие от Ethereum, где Infura и Alchemy доминируют как API-провайдеры, TON исторически развивал децентрализованную инфраструктуру доступа к блокчейну. Это привело к появлению нескольких независимых API-сервисов, каждый из которых решает свои задачи:

• TON Center (toncenter.com) — self-hosted HTTP API для прямых запросов к блокчейну
• TonAPI (tonapi.io) — управляемый сервис с обогащёнными данными и streaming
• @ton/core — низкоуровневый SDK для конструирования и парсинга данных

Выбор провайдера зависит от задачи: для простого чтения баланса достаточно TON Center v2, для мониторинга Jetton-переводов в реальном времени лучше подходит TonAPI с webhooks.

TON Center (toncenter.com)

TON Center — это open-source HTTP API, который можно как использовать через публичный эндпоинт, так и развернуть на собственном сервере. Это основной низкоуровневый способ взаимодействия с блокчейном TON.

v2 API: JSON-RPC стиль

API v2 предоставляет прямой доступ к данным блокчейна в стиле JSON-RPC. Основные методы:

• getAddressBalance — баланс аккаунта
• getTransactions — список транзакций аккаунта
• sendBoc — отправка сериализованной транзакции (bag-of-cells)
• getAddressInformation — полная информация об аккаунте (баланс, код, данные)
• runGetMethod — вызов get-метода смарт-контракта

Пример запроса баланса:

curl "https://toncenter.com/api/v2/getAddressBalance?address=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF_3Rvvr"

Ответ:

{
  "ok": true,
  "result": "1500000000"
}

v3 API: индексер

API v3 — это индексер поверх блокчейна, который предоставляет более высокоуровневые запросы:

• Поиск транзакций по сообщению (message hash)
• Получение состояний аккаунтов с историей
• Запросы по нескольким аккаунтам одновременно
• Фильтрация транзакций по типу и временным диапазонам

v3 удобнее для аналитических задач, где нужно агрегировать данные, а не просто получить текущее состояние.

Rate limits и эндпоинты

TonAPI (tonapi.io)

TonAPI — это управляемый сервис от TON Console, который предоставляет REST API с обогащёнными данными. В отличие от TON Center, который возвращает сырые данные блокчейна, TonAPI автоматически резолвит метаданные Jetton и NFT, агрегирует события и предоставляет streaming.

Ключевые возможности

• Обогащённые данные — метаданные Jetton (имя, символ, decimals) и NFT (изображения, атрибуты) уже включены в ответы
• Event streaming — SSE (Server-Sent Events) для мониторинга транзакций в реальном времени
• Webhooks — push-уведомления о событиях на ваш сервер
• Gasless-транзакции — поддержка отправки транзакций без TON на балансе (через relay)
• Swagger UI — интерактивная документация для тестирования запросов

SDK для TonAPI

TonAPI предоставляет официальные SDK для трёх языков:

Пример использования @ton-api/client:

import { Api, HttpClient } from "@ton-api/client";

const httpClient = new HttpClient({
  baseUrl: "https://tonapi.io",
  baseApiParams: {
    headers: {
      Authorization: `Bearer ${process.env.TONAPI_KEY}`,
      "Content-type": "application/json",
    },
  },
});

const client = new Api(httpClient);

// Получение информации об аккаунте
const account = await client.accounts.getAccount(
  "EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF_3Rvvr"
);

console.log(`Balance: ${account.balance / 1e9} TON`);
console.log(`Status: ${account.status}`);

Эндпоинты и тестнет

API-ключи для TonAPI создаются через tonconsole.com — веб-панель управления проектами TON.

Сравнение TON Center и TonAPI

@ton/core SDK

@ton/core — это низкоуровневый SDK для работы с примитивами TON. Он не заменяет API-провайдеров, а дополняет их, предоставляя инструменты для конструирования и парсинга данных.

Основные абстракции

Эти абстракции были введены в модуле 2 (TVM и Исполнение) и модуле 3 (Смарт-контракты на Tact). В контексте production-инфраструктуры важно понимать, что @ton/core используется совместно с API-провайдером:

import { TonClient } from "@ton/ton";
import { Address } from "@ton/core";

// TonClient использует TON Center API под капотом
const client = new TonClient({
  endpoint: "https://toncenter.com/api/v2/jsonRPC",
  apiKey: process.env.TONCENTER_API_KEY,
});

const address = Address.parse("EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF_3Rvvr");
const balance = await client.getBalance(address);

console.log(`Balance: ${balance} nanoTON`);

Управление API-ключами

Правильное управление API-ключами критически важно для production-приложений. Оба провайдера предоставляют разные механизмы получения и управления ключами.

TON Center: получение ключа

1. Откройте Telegram-бота @tonapibot
2. Отправьте команду /start
3. Выберите тарифный план (Free tier достаточен для разработки)
4. Получите API-ключ

Тарифные планы:

TonAPI: получение ключа

1. Зайдите на tonconsole.com
2. Создайте проект
3. Перейдите в раздел API-ключей
4. Скопируйте ключ для использования в приложении

Безопасность ключей

Рекомендации:

1. Храните ключи в .env файле, добавленном в .gitignore
2. Используйте разные ключи для development и production
3. Реализуйте обработку ошибок при превышении rate limit (HTTP 429)
4. Для production рассмотрите self-hosted TON Center для независимости от внешних сервисов

Пример обработки rate limit:

async function fetchWithRetry(url: string, maxRetries = 3): Promise<Response> {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") || "1");
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error("Max retries exceeded");
}

Ключевые выводы

1. TON Center — self-hosted HTTP API с двумя версиями: v2 (JSON-RPC, низкоуровневый) и v3 (индексер, высокоуровневый). Подходит для контроля инфраструктуры и базовых запросов.
2. TonAPI — управляемый сервис с обогащёнными данными, streaming (SSE) и webhooks. Выбирайте для мониторинга событий и работы с метаданными токенов.
3. @ton/core и @ton/ton — SDK для конструирования и парсинга данных TON. Используются совместно с API-провайдером, а не вместо него.
4. Бесплатный tier TON Center — 10 запросов/сек с ключом от @tonapibot. Без ключа — только 1 запрос/сек.
5. Никогда не коммитьте API-ключи в репозиторий. Используйте .env и переменные окружения.
6. Для production рассмотрите self-hosted TON Center для полной независимости от внешних сервисов.

Частые ошибки

1. Используют один API-провайдер без fallback: если TonCenter недоступен, приложение полностью перестаёт работать.
2. Не учитывают rate limits при проектировании: бесплатные тарифы имеют жёсткие ограничения (1-10 RPS), которые легко превысить.
3. Путают TonCenter API v2 и v3: они имеют разные эндпоинты, форматы ответов и возможности.
4. Не кешируют результаты get-методов: одни и те же данные запрашиваются повторно при каждом рендере, быстро исчерпывая лимиты.