TON API v4: infrastructure, tools and use cases

Pick the wrong TON API version and you’ll find out the hard way: a dashboard that hammers a raw node and gets rate-limited, or a wallet that misses a balance change because it’s polling a database that’s still catching up to the chain. If you’re building on TON, you’ll eventually run into three different HTTP APIs — v2, v3, and v4. v2 talks to a node directly. v3 is a proper indexer. v4 keeps responses close to the network but makes them cacheable and subscribable. This guide walks through what v4 actually is under the hood, how it stacks up against v2 and v3, how indexing works underneath it, how to get a production TON endpoint running in minutes, and which tools matter for developers building on TON.

What is TON?

If you’re mainly here for the RPC and want to learn how to build on TON, skip down to “TON Infrastructure” below.

TON (The Open Network) is a Layer 1 blockchain originally developed by Telegram and continued by the open-source community. The architecture relies on dynamic sharding to maintain throughput during periods of high demand. The network processes transactions with sub-second finality, providing execution speeds required for high-frequency trading applications and consumer-facing decentralized finance (DeFi) platforms.

💎 The Sub-Second mainnet activation starts now!

TON Core has just shared the completion of the Bug Bounty & stated that changes were already implemented. Now they are moving to the next stage – Sub-Second Mainnet activation.

For additional reliability, activation will be… pic.twitter.com/ddSdwXDnYM

— TON 💎 (@ton_blockchain) April 1, 2026

According to network statistics as of 7th September 2026, the network currently runs on:

• Validators: 393 active validators securing the consensus mechanism
• Nodes: 1,053 operational nodes propagating blocks and managing state
• Smart Contracts: 180 million deployed smart contracts executing decentralized logic
• Active Wallets: 2.3 million monthly active wallets engaging with the network
• Transaction Volume: 4.3 million transactions processed per 24-hour period

A sharded, high-throughput chain with millions of daily transactions puts real pressure on whichever API layer sits between an application and the network, which is exactly the problem TON’s API v2, v3, and now v4 has been built to solve at different points in the stack.

What is TON API v4?

TON does not natively expose a REST API. Its nodes communicate using native protocols such as ADNL, a binary peer-to-peer protocol, while applications typically need HTTP or WebSocket interfaces to interact with the network. TON HTTP API v4 provides that application-facing layer.

📖 For a deeper understanding of how TON works and the common terminology used across the ecosystem, this guide is worth a read: TON: The Ultimate Guide to APIs and Interaction Libraries.

Under the hood, v4 stays close to TON’s native infrastructure. It uses the JavaScript library ton-lite-client to communicate with TON liteservers that speaks ADNL directly, and TON libraries such as @ton/core and @ton/ton to work with the blockchain’s native data structures and operations. It also runs a BlockSync process that continuously tracks the chain head and keeps a local view of recent blocks in sync. v4 provides a network-close, deterministic, cacheable, and real-time access layer for TON blockchain data:

• Block-pinned state: account and contract data can be queried against a specific block sequence number (seqno) instead of always resolving against the latest state. Once a block is finalized, its state does not change, making the response deterministic and safe to cache.
• Real-time updates: v4 provides WebSocket endpoints for monitoring new blocks and account changes. Applications can maintain a persistent connection and receive updates as they occur instead of continuously polling the API.
• Network-close access: v4 stays close to the TON network, retrieving blockchain data through the lite-client stack rather than relying on a separate indexed database.

Understanding this architecture makes the comparison from TON API v2 to v3 and v4 much easier to follow: each version takes a different approach to making TON data available to applications.

🆕 Chainstack added TON API v4 support in September 2026 — see TON v4 API is live on Chainstack for what shipped and how to start using it.

TON API v4 vs v3 vs v2

Understanding the progression of TON’s network APIs requires examining the structural differences between versions 2, 3, and 4:

API v2 provides a REST and JSON-RPC bridge over tonlib, which itself queries liteservers directly. Data is as fresh as the network allows, but the responses look like raw node output rather than a clean, pre-joined data model for convenience. It accepts generic method calls and returns state data based on the most recent block the lite-client has processed. Applications utilizing v2 send commands like getAddressInformation or getMasterchainInfo. v2 is the right choice when near-instant visibility into new transactions matters more than convenience. For the endpoints themselves, the TON v2 API reference has the full list.

API v3 reads raw data from a node’s RocksDB storage, parses and decodes it, and stores the result in PostgreSQL. That’s what makes it an indexer. It’s not just forwarding raw data — it’s building its own database derived from the chain, which is what enables richer queries: traces, Jetton histories, NFT metadata, and other multi-step lookups that would take several round trips against a raw node. TON Center provides primary infrastructure components for the ecosystem, including an open-source indexer. The TON Center Indexer extracts block data from the liteservers and structures it for rapid retrieval. The tradeoff is a small indexing delay between a block landing onchain and that block’s data becoming queryable through v3. The TON v3 API reference covers the available endpoints in detail.

API v4 introduces block-pinned queries, letting applications request account and contract state at a specific seqno. This makes responses deterministic and easier to cache. v4 also natively supports WebSocket subscriptions for block and account changes, where v2 and v3 depend on server-sent events or separate streaming services for similar functionality. In practice, this makes v4 a strong fit for applications that need both freshness and cacheability at the same time — wallets checking balance changes, or dashboards rendering the latest block without hammering the origin server on every page load.

For most teams, the choice comes down to what the application actually does with the data. If the use case needs the freshest possible view of a single account or block, v2 or v4 both work; if it needs joined, historical, or aggregate views — all Jettons held by an address, or a full transaction trace — v3’s indexed model is the better starting point.

❓ Still deciding between v2 and v3? The v2 vs. v3 guide has a detailed comparison. For v4, keep reading below.

For production applications, choosing the right API is only part of the infrastructure decision. A reliable RPC endpoint is important for consistent access and performance. Chainstack supports TON API v2, v3, and v4, so you can use whichever API a given workload needs without managing the underlying TON infrastructure.

The next section walks through setting up a production-ready TON RPC endpoint with Chainstack.

TON Infrastructure

One thing that makes this easier than it sounds: there is no need to pick one version and commit. Chainstack serves TON API v2, v3, and v4, with both REST and WebSocket access, through the same endpoint and API key on Mainnet and Testnet. For applications that require lower-level access than the HTTP APIs provide, Dedicated Nodes also support ADNL directly.

How to get a TON RPC endpoint on Chainstack

1. Select TON by searching through the 70+ protocols, then choose the node type your workload needs, and click Continue.
2. Give the node a name, review the deployment details, and click Deploy Node.
3. Head to Access and credentials to grab your HTTPS and WebSocket endpoint URLs.

That’s it — the node is deployed and ready to use.

⚠️ TON is a non-EVM blockchain and does not natively use standard Ethereum-style Chain IDs. However, tools that integrate cross-chain standards may use specific ecosystem IDs to identify TON networks. The native currency symbol is GRAM rather than ETH.

Not all wallets support TON. The TON tooling documentation has a detailed breakdown of TON-compatible wallets and tooling.

TON is now $GRAM.

Same chain. Same network. New name, ticker & logo.

All TON holdings convert 1:1 to GRAM automatically. No swap, no migration, no action required from holders.

Why GRAM?

Gram was the original name of the token in TON's first whitepaper. Returning to the… pic.twitter.com/0r2cceVXzl

— TON 💎 (@ton_blockchain) June 15, 2026

The basechain uses workchain ID 0, where regular accounts and smart contracts operate, while the masterchain uses workchain ID -1 and handles network-level information such as configuration and validator data. It is important not to confuse the TON network ID with a workchain ID: the network ID identifies the TON network itself, while the workchain ID identifies a specific chain within that network.

Network ID	-239
Mainnet	https://ton-mainnet.core.chainstack.com
Network name	TON Mainnet
Testnet Network ID	-3
Testnet	https://ton-testnet.core.chainstack.com
Network name	TON Testnet
Currency symbol	GRAM (prev. TON)

API Reference

The API exposes a focused set of endpoints for reading blocks and account state, executing contract methods, retrieving network configuration, and submitting transactions. The core endpoints include:

• GET /block/latest — the current chain head
• GET /block/:seqno — full block data at a given seqno
• GET /block/utime/:utime — whichever block is closest to a given unix timestamp
• GET /block/:seqno/:address — full account state as of a specific block
• GET /block/:seqno/:address/lite — the same idea, but a lighter response
• GET /block/:seqno/:address/changed/:lt — a quick check for whether an account has changed since an earlier logical time, genuinely useful if you’re trying to poll efficiently instead of re-fetching everything
• GET /block/:seqno/:address/run/:command — execute a smart contract’s get-method at a specific block
• GET /block/:seqno/config — network configuration parameters at that block
• GET /account/:address/tx/:lt/:hash — a specific transaction by its logical time and hash, with a /parsed/ variant for a decoded response
• POST /send — submit a signed external message (a BoC) to the network

For example, GET /block/latest retrieves the sequence number and header information of the most recently validated masterchain block. This provides the reference point for determining the latest known state of the TON network and can be used to obtain the seqno required by other block-specific endpoints.

const options = {
  method: 'GET'
};

fetch('https://ton-mainnet.core.chainstack.com/<KEY>/api/v4/block/latest', options)
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

Response:

{
    "last": {
        "seqno": 91563571,
        "shard": "-9223372036854775808",
        "workchain": -1,
        "fileHash": "lfnXmrxgoHl4gG/J3eY0s5N0+kyOnstLDa3m0gt+msw=",
        "rootHash": "rNGlbDZSwSdjplrdgJl8Xnl+o15q6oJzRUo0GQ4lUXI="
    },
    "init": {
        "fileHash": "XplPz01CXAps5qeSWUtxcyBfdAo5zVb1N979KLSKD24=",
        "rootHash": "F6OpKZKqvqeFp6CQmFomXNMfMj2EnaUSOXN+Mh+wVWk="
    },
    "stateRootHash": "WGMRXvWicDZhI4mq4LnZJfiQicc1t8w/oAnWMC4E6nM=",
    "now": 1788940223
}

📖 For a full side-by-side of RPC providers, see Top 6 TON RPC providers for production apps in 2026.

WebSocket

WebSocket connections allow applications to receive real-time updates regarding transaction confirmations and account state changes. Implementing WebSockets reduces the necessary HTTP polling frequency and conserves infrastructure resources.

v4 gives you two WebSocket routes worth knowing:

• /block/watch opens a connection, immediately sends you whatever block is currently known, and then streams new blocks as they’re produced, including seqno, block time, and server time.
• /block/watch/changed works the same way but scopes what it sends you to relevant changes — the pattern you want for something like a wallet balance widget that should only re-render when there’s actually something new to show.

This persistent connection maintains an open socket, allowing the infrastructure to push data to the client the moment the specified address undergoes a state transition.

TON Client

Interacting with TON’s endpoints directly via raw HTTP requests is possible, but it is rarely the best approach for production applications. TON’s data model is uniquely built around cells and Bag-of-Cells (BoC) serialization. Getting the request-building and response-parsing right from scratch is significantly more complex than it appears at first glance.

To streamline development and ensure data is decoded accurately, developers implement standard client libraries that handle the heavy lifting:

• JavaScript / TypeScript: @ton/ton (or the legacy ton package) will handle most of the complex formatting for you. TonWeb is another excellent alternative that covers similar ground, particularly for wallets and Jettons.
• Python: pytonlib and tonsdk are the standard, battle-tested choices for Python environments.

It is worth using one of these SDKs rather than hand-rolling requests, even for something simple. Attempting to manually parse TON’s native binary structures introduces unnecessary overhead and potential points of failure to your application. By letting the client library manage the serialization and deserialization of network data, you can focus on the application logic rather than the low-level mechanics of the TON blockchain.

Builder Tools

• TonWeb: a JavaScript SDK for wallets, Jettons, and NFTs, usable directly against a Chainstack TON endpoint
• Ton.js / @ton/ton: the community-maintained TypeScript client for building dApps against TON’s HTTP APIs
• Blueprint: the standard TON smart contract development framework for writing, testing, and deploying FunC and Tolk contracts
• TON RPC: mainnet and testnet nodes across v2, v3, v4, and ADNL, with Global and Dedicated deployment options
• TON API reference: full method reference across v2 and v3, with JSON-RPC examples alongside REST
• Chainstack TON testnet faucet: free testnet TON for development
• toncenter/ton-indexer: the open-source indexer underlying API v3, useful reading for understanding how TON data gets normalized into a queryable form
• docs.ton.org: the canonical documentation for TON’s API versions, smart contract language (Tolk/FunC), and network protocols

Conclusion

TON’s three HTTP API versions are not competing implementations of the same idea — they answer different questions. v2 stays close to the node and prioritizes freshness. v3 trades a small indexing delay for the ability to answer rich, historical, and multi-step queries. v4 keeps the lite-client connection close to the network like v2 does, while adding block-pinned caching and native WebSocket subscriptions, which makes it a strong default for applications that need both current data and real-time updates without building a custom streaming layer.

Picking the right version, or combining more than one, comes down to what an application actually asks of the chain: a wallet reading balances benefits from v4’s subscriptions, a Jetton analytics dashboard benefits from v3’s indexed history, and a low-latency trading bot may reach for ADNL directly.

Chainstack serves all three versions, plus native ADNL on Dedicated Nodes, from a single TON endpoint on both Mainnet and Testnet, along with a dedicated testnet faucet and an MCP server that lets AI coding assistants provision nodes and query TON data directly.

FAQ

Related reading

• TON v4 API is live on Chainstack
• Top 6 TON RPC providers for production apps in 2026
• TON: Ultimate developer guide from smart contracts to Jettons
• Build better on TON with Chainstack