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"
}
Баланс возвращается в наноTON (1 TON = 10^9 наноTON). Не забывайте делить на 10^9 при отображении пользователю.
v3 API: индексер
API v3 — это индексер поверх блокчейна, который предоставляет более высокоуровневые запросы:
- Поиск транзакций по сообщению (message hash)
- Получение состояний аккаунтов с историей
- Запросы по нескольким аккаунтам одновременно
- Фильтрация транзакций по типу и временным диапазонам
v3 удобнее для аналитических задач, где нужно агрегировать данные, а не просто получить текущее состояние.
Rate limits и эндпоинты
| Параметр | Значение |
|---|---|
| Без API-ключа | 1 запрос/сек |
| Free tier (с ключом) | 10 запросов/сек |
| Advanced tier | до 100 запросов/сек |
| Mainnet v2 | https://toncenter.com/api/v2/ |
| Mainnet v3 | https://toncenter.com/api/v3/ |
| Testnet v2 | https://testnet.toncenter.com/api/v2/ |
| Testnet v3 | https://testnet.toncenter.com/api/v3/ |
Без API-ключа доступен только 1 запрос в секунду. Для разработки обязательно получите бесплатный ключ через Telegram-бота @tonapibot.
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 для трёх языков:
| Язык | Пакет | Установка |
|---|---|---|
| TypeScript | @ton-api/client | npm install @ton-api/client |
| Python | pytonapi | pip install pytonapi |
| Go | tonapi-go | go get github.com/tonkeeper/tonapi-go |
Пример использования @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}`);
Эндпоинты и тестнет
| Среда | Эндпоинт |
|---|---|
| Mainnet | https://tonapi.io |
| Testnet | https://testnet.tonapi.io |
API-ключи для TonAPI создаются через tonconsole.com — веб-панель управления проектами TON.
Сравнение TON Center и TonAPI
| Характеристика | TON Center (v2/v3) | TonAPI (tonapi.io) |
|---|---|---|
| Тип | Self-hosted / публичный | Управляемый сервис |
| API ключ | @tonapibot в Telegram | tonconsole.com |
| Бесплатный лимит | 10 запросов/сек | Бесплатный tier для dApp |
| Эндпоинт (mainnet) | toncenter.com/api/v2/ | tonapi.io |
| Эндпоинт (testnet) | testnet.toncenter.com/ | testnet.tonapi.io |
| Streaming/Webhooks | Нет (только polling) | Да (SSE + Webhooks) |
| SDK | @ton/ton (community) | @ton-api/client (official) |
| Jetton/NFT metadata | Сырые данные | Обогащённые (с метаданными) |
| Self-hosting | Да (open source) | Нет |
| Gasless транзакции | Нет | Да |
Когда выбирать TON Center: вам нужен полный контроль, self-hosting, или достаточно низкоуровневых запросов (баланс, отправка транзакций).
Когда выбирать TonAPI: вам нужны обогащённые данные (метаданные токенов), streaming событий, или webhooks для мониторинга.
@ton/core SDK
@ton/core — это низкоуровневый SDK для работы с примитивами TON. Он не заменяет API-провайдеров, а дополняет их, предоставляя инструменты для конструирования и парсинга данных.
Основные абстракции
| Класс | Назначение |
|---|---|
Cell | Базовая единица данных в TON (до 1023 бит + 4 ссылки) |
Slice | Чтение данных из Cell |
Builder | Конструирование новых Cell |
Address | Работа с адресами (raw и user-friendly форматы) |
Contract | Базовый класс для взаимодействия со смарт-контрактами |
Эти абстракции были введены в модуле 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`);
@ton/core предоставляет примитивы (Cell, Address, Builder), а @ton/ton — клиент для отправки запросов через TON Center API. Это два разных пакета, которые работают вместе.
Управление API-ключами
Правильное управление API-ключами критически важно для production-приложений. Оба провайдера предоставляют разные механизмы получения и управления ключами.
TON Center: получение ключа
- Откройте Telegram-бота @tonapibot
- Отправьте команду
/start - Выберите тарифный план (Free tier достаточен для разработки)
- Получите API-ключ
Тарифные планы:
| План | Лимит | Стоимость |
|---|---|---|
| Free | 10 запросов/сек | Бесплатно |
| Plus | 25 запросов/сек | Платно |
| Advanced | до 100 запросов/сек | Платно |
TonAPI: получение ключа
- Зайдите на tonconsole.com
- Создайте проект
- Перейдите в раздел API-ключей
- Скопируйте ключ для использования в приложении
Безопасность ключей
Никогда не коммитьте API-ключи в репозиторий. Используйте переменные окружения и файл .env.
Рекомендации:
- Храните ключи в
.envфайле, добавленном в.gitignore - Используйте разные ключи для development и production
- Реализуйте обработку ошибок при превышении rate limit (HTTP 429)
- Для 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");
}
Ключевые выводы
- TON Center — self-hosted HTTP API с двумя версиями: v2 (JSON-RPC, низкоуровневый) и v3 (индексер, высокоуровневый). Подходит для контроля инфраструктуры и базовых запросов.
- TonAPI — управляемый сервис с обогащёнными данными, streaming (SSE) и webhooks. Выбирайте для мониторинга событий и работы с метаданными токенов.
- @ton/core и @ton/ton — SDK для конструирования и парсинга данных TON. Используются совместно с API-провайдером, а не вместо него.
- Бесплатный tier TON Center — 10 запросов/сек с ключом от @tonapibot. Без ключа — только 1 запрос/сек.
- Никогда не коммитьте API-ключи в репозиторий. Используйте
.envи переменные окружения. - Для production рассмотрите self-hosted TON Center для полной независимости от внешних сервисов.
Частые ошибки
- Используют один API-провайдер без fallback: если TonCenter недоступен, приложение полностью перестаёт работать.
- Не учитывают rate limits при проектировании: бесплатные тарифы имеют жёсткие ограничения (1-10 RPS), которые легко превысить.
- Путают TonCenter API v2 и v3: они имеют разные эндпоинты, форматы ответов и возможности.
- Не кешируют результаты get-методов: одни и те же данные запрашиваются повторно при каждом рендере, быстро исчерпывая лимиты.
Проверка знанийВ каком случае стоит выбрать TonAPI (tonapi.io) вместо TON Center для production-приложения?
Проверьте понимание
Закончили урок?
Отметьте его как пройденный, чтобы отслеживать свой прогресс
Войдите чтобы оценить урок