gramdocs.tech
Документация

TonAPI: чтение ончейн-данных через REST

Прочитаешь баланс, jetton и события аккаунта через TonAPI REST (tonapi.io) с реальными curl и TypeScript.

Что такое TonAPI

TonAPI (tonapi.io) — индексированный HTTP API к TON: аккаунты, jetton, NFT, события и трассы уже разобраны в удобные JSON-модели. Базовый URL mainnet: https://tonapi.io/v2. Ключ — на tonconsole.com; без ключа запросы сильно троттлятся.

Читаем аккаунт

Адрес — любой user-friendly или raw. Пример — известный mainnet-кошелёк (не testnet):

bash
# TonAPI v2 — GET /v2/accounts/{account_id}
curl -s "https://tonapi.io/v2/accounts/EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N" \
  -H "Authorization: Bearer $TONAPI_KEY" \
  -H "Accept: application/json"

Тот же запрос из TypeScript:

typescript
// fetch + TonAPI v2 (ключ с tonconsole.com)
const accountId = "EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N";

const res = await fetch(`https://tonapi.io/v2/accounts/${accountId}`, {
  headers: {
    Authorization: `Bearer ${process.env.TONAPI_KEY}`,
    Accept: "application/json",
  },
});

if (!res.ok) {
  throw new Error(`TonAPI ${res.status}: ${await res.text()}`);
}

const account = (await res.json()) as {
  balance: number; // nanotons
  status: string;
  address: string;
};

console.log(account.balance / 1e9, account.status);

Jetton-балансы владельца:

bash
curl -s "https://tonapi.io/v2/accounts/${ACCOUNT}/jettons" \
  -H "Authorization: Bearer $TONAPI_KEY"

События аккаунта (высокоуровневые actions поверх трасс):

bash
curl -s "https://tonapi.io/v2/accounts/${ACCOUNT}/events?limit=20" \
  -H "Authorization: Bearer $TONAPI_KEY"

Как это работает

  • GET /v2/accounts/{id} — человекочитаемый снимок: баланс в nanotons, статус (active / uninit / …), интерфейсы.
  • .../jettons — уже разобранные jetton-кошельки, не нужно вручную звать get-методы master/wallet.
  • .../events — индексёр склеивает трассу в actions (transfer, swap и т.д.); для жёсткой бизнес-логики лучше опираться на raw traces/transactions, не только на actions.
  • Заголовок Authorization: Bearer <key> — основной способ аутентификации; testnet: https://testnet.tonapi.io/v2.

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

HTTP 429 → превышен rate limit. Добавь ключ, снизь частоту polling, используй backoff — см. Ошибка: TonAPI — rate limit.

Путаешь mainnet и testnet base URL → «пустой» или чужой аккаунт. Для тестнета — testnet.tonapi.io.

Строишь критичную логику только на events.actions → набор actions может меняться. Для денег и инвариантов читай транзакции/traces или свой индекс.

Что дальше

Материалы gramdocs.tech носят образовательный характер и не являются финансовой, юридической или инвестиционной рекомендацией. Работа с блокчейном TON и токеном Gram связана с рисками потери средств. Правовая информация