> ## 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

# What is API v4 and what is it used for

**TON API v4** is an internal HTTP API for working with the TON blockchain. It provides access to the historical state of the blockchain and to executing get-methods of contracts at a specified block number (seqno). The API gets data from [the blockchain indexer](/whales-blockchain-indexer).\
Endpoint: [https://mainnet-v4.tonhubapi.com/](https://mainnet-v4.tonhubapi.com/)

# Main purpose

* **State at a specific block** — getting account, block and transaction data not "as of now", but at a fixed masterchain seqno. This is needed for reproducible logic (auditing, calculations, simulations).
* **Run get-method on historical block** — calling smart contract methods (e.g., `get_staking_status`, `get_pool_data`, `get_jetton_data`) in the context of the state at a selected block. Public APIs usually only provide "current" state.
* **High speed and predictable load** — reading from own indexed database (ScyllaDB) and emulation through Emulator Farm when necessary instead of relying on public limited APIs.

# Technical stack

* **ScyllaDB** — storage of block indexes, account states and transactions (tables `blocks`, `account_states`, `transactions`, `lt_buckets`, `mc_blocks_by_utime`, `sync` and others).
* **Emulator Farm** (optional) — gRPC service for executing run get-method through TVM emulation (mode `USE_EMULATOR=true`).
* **TONAPI** (external) — used only for sending messages to the network (`/v2/liteserver/send_message`)

# Which Whales projects use it

The **ton-api-v4-go** implementation and related infrastructure (ScyllaDB index, Emulator Farm) are used in Whales ecosystem products for scenarios where historical state and calling get-methods at a given block are critical.

1. **Staking (Whales Staking) -** used for correct display of stake status and calculations at a selected point in time. Also used for displaying pool states.
2. **Tonhub** - getting wallet states by address at a block. Needed for balances, metadata and history tied to a specific blockchain state.
3. **General TON infrastructure -** can be used by any internal Whales services that need fast and deterministic access to historical data.

# API v4 advantages

## Historical state at a specific block

Public APIs (e.g., TONAPI, other public indexers) are focused on current state: latest block, current balance, recent transactions.\
Whales products need access to state at an arbitrary masterchain seqno: "how it was in block N". This is needed for:

* Auditing and reproducible calculations
* Correct display of staking, pools and jettons at a selected date/block
* Simulations and tests with fixed state.

Such requests for state "at block X" are either not supported by public APIs, or are limited and unpredictable in terms of delays and limits.

## Run get-method on historical block

A critical capability of API v4 is calling run get-method in the context of a selected block (`/block/{seqno}/{address}/run/{command}`). Public APIs usually allow calling get-methods only for the current node state. Calling in the context of an old block requires either own state indexing or emulation (Emulator Farm).\
For staking, calls on historical blocks are specifically needed (e.g., `get_staking_status` or `get_pool_data` at a given seqno). This is not covered by typical third-party APIs.

## Performance and scaling

Own indexing in **ScyllaDB** provides:

* Fast access to blocks, accounts and transactions by keys suitable for product queries;
* Ability to scale the cluster and configure it for own load.

Public APIs have request limits (rate limit) shared among all users. For high-load scenarios (pool aggregation, staking, mass checks) this is insufficient.

## Control over data format and SLA

In API v4, response formats are fixed and tailored to internal clients. Also, third-party APIs can change contracts and versions without considering Whales' needs.\
Own stack provides full control over availability, index updates and protocol versions, but also imposes requirements for its support in case of critical blockchain changes.

## Emulation of heavy get-methods

Some get-methods are executed through **Emulator Farm** (mode `HandleAccountRunV2` with `USE_EMULATOR=true`). This allows executing complex or heavy methods without load on nodes and without third-party API limitations.\
Public providers do not provide emulation for non-latest blocks.

## Hybrid approach

For sending messages to the network, API v4 itself uses external TONAPI (`TONAPI_ENDPOINT` + `TONAPI_TOKEN`) and proxies requests to `v2/liteserver/send_message`. That is, third-party API is used where it is sufficient (transaction sending), while reading historical state and run get-method are provided only by own API v4.


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