> ## Documentation Index
> Fetch the complete documentation index at: https://whalescorp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API v4

# Что такое API v4 и зачем он нужен

**TON API v4** — это внутренний HTTP API для работы с блокчейном TON. Он предоставляет доступ к историческому состоянию блокчейна и позволяет выполнять get-методы контрактов на указанном номере блока, то есть seqno. API получает данные из [индексера блокчейна](/ru/whales-blockchain-indexer).\
Эндпоинт: `https://mainnet-v4.tonhubapi.com/`

# Основные задачи

* **Состояние на конкретном блоке** — получение данных об аккаунтах, блоках и транзакциях не "на сейчас", а на фиксированном masterchain seqno. Это нужно для воспроизводимой логики, например аудита, расчетов и симуляций.
* **Запуск get-метода на историческом блоке** — вызов методов смарт-контрактов, например `get_staking_status`, `get_pool_data`, `get_jetton_data`, в контексте состояния на выбранном блоке. Публичные API обычно предоставляют только текущее состояние.
* **Высокая скорость и предсказуемая нагрузка** — чтение из собственной индексированной базы данных ScyllaDB и эмуляция через Emulator Farm, когда это необходимо, вместо зависимости от публичных API с ограничениями.

# Технический стек

* **ScyllaDB** — хранение индексов блоков, состояний аккаунтов и транзакций, включая таблицы `blocks`, `account_states`, `transactions`, `lt_buckets`, `mc_blocks_by_utime`, `sync` и другие.
* **Emulator Farm** — опциональный gRPC-сервис для выполнения run get-method через TVM-эмуляцию в режиме `USE_EMULATOR=true`.
* **TONAPI** — внешний сервис, который используется только для отправки сообщений в сеть через `/v2/liteserver/send_message`.

# Какие проекты Whales используют этот API

Реализация **ton-api-v4-go** и связанная с ней инфраструктура, то есть индекс ScyllaDB и Emulator Farm, используются в продуктах экосистемы Whales в тех сценариях, где критически важны историческое состояние и вызов get-методов на заданном блоке.

1. **Staking (Whales Staking)** — используется для корректного отображения статуса стейка и расчетов на выбранный момент времени. Также применяется для отображения состояний пулов.
2. **Tonhub** — получение состояний кошельков по адресу на конкретном блоке. Это нужно для балансов, метаданных и истории, привязанных к определенному состоянию блокчейна.
3. **Общая TON-инфраструктура** — может использоваться любыми внутренними сервисами Whales, которым нужен быстрый и детерминированный доступ к историческим данным.

# Преимущества API v4

## Историческое состояние на конкретном блоке

Публичные API, например TONAPI и другие публичные индексеры, ориентированы в первую очередь на текущее состояние: последний блок, текущий баланс, последние транзакции.\
Продуктам Whales нужен доступ к состоянию на произвольном masterchain seqno, то есть возможность ответить на вопрос "каким было состояние в блоке N". Это необходимо для:

* аудита и воспроизводимых расчетов,
* корректного отображения стейкинга, пулов и jetton на выбранную дату или блок,
* симуляций и тестов с фиксированным состоянием.

Такие запросы на состояние "в блоке X" либо вообще не поддерживаются публичными API, либо доступны только с ограничениями и непредсказуемыми задержками.

## Запуск get-метода на историческом блоке

Ключевая возможность API v4 — запуск `run get-method` в контексте выбранного блока через маршрут `/block/{seqno}/{address}/run/{command}`. Публичные API обычно позволяют вызывать get-методы только для текущего состояния ноды. Вызов в контексте старого блока требует либо собственного индексирования состояния, либо эмуляции через Emulator Farm.\
Для стейкинга вызовы на исторических блоках особенно важны, например `get_staking_status` или `get_pool_data` на конкретном seqno. Обычные сторонние API этого не покрывают.

## Производительность и масштабирование

Собственное индексирование в **ScyllaDB** дает:

* быстрый доступ к блокам, аккаунтам и транзакциям по ключам, удобным для продуктовых запросов;
* возможность масштабировать кластер и настраивать его под собственную нагрузку.

У публичных API есть ограничения на частоту запросов, и эти лимиты делятся между всеми пользователями. Для высоконагруженных сценариев, например агрегации пулов, стейкинга и массовых проверок, этого недостаточно.

## Контроль над форматом данных и SLA

В API v4 форматы ответов зафиксированы и адаптированы под внутренних клиентов. Кроме того, сторонние API могут менять контракты и версии без учета потребностей Whales.\
Собственный стек дает полный контроль над доступностью, обновлением индексов и версиями протокола, но одновременно требует собственной поддержки в случае критических изменений блокчейна.

## Эмуляция тяжелых get-методов

Некоторые get-методы выполняются через **Emulator Farm**, то есть в режиме `HandleAccountRunV2` с `USE_EMULATOR=true`. Это позволяет исполнять сложные или тяжелые методы без нагрузки на ноды и без ограничений сторонних API.\
Публичные провайдеры не предоставляют эмуляцию для блоков, отличных от последних.

## Гибридный подход

Для отправки сообщений в сеть API v4 сам использует внешний TONAPI через `TONAPI_ENDPOINT` и `TONAPI_TOKEN`, проксируя запросы в `v2/liteserver/send_message`. То есть сторонний API используется там, где его достаточно, а чтение исторического состояния и запуск `run get-method` обеспечиваются только собственным API v4.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.