Choosing between v2 and v3

TON offers two distinct API versions, each optimized for different types of use cases. Understanding their core differences will help you choose the best one for your application.

Overview

Feature	TON API v2	TON API v3
Backed by	Node (real-time)	Indexer (processed)
Data type	Raw, live data	Indexed, structured data
Latency	Near-instant	Slight delay due to indexing
Query complexity	Basic queries	Complex and flexible queries
Stability	Depends on node sync	Stable and consistent
Protocol	ADNL via tonlib	PostgreSQL via HTTP API

When to Use Each

Use TON API v2 if:

• You need fast access to the most recent data
• Your app requires near real-time transaction monitoring
• You prefer low-latency, direct communication with TON nodes
• You can manage raw data parsing and less structured responses

TON API v2 is backed directly by TON nodes through the tonlib library. This approach favors speed and freshness. It’s ideal for monitoring account balances, incoming transactions, or building wallet frontends that require quick feedback.

Use TON API v3 if:

• You want structured, clean data for complex queries
• You prioritize stability over raw freshness
• You are working with historical data or advanced analytics
• You need advanced filters, sorting, or pagination

TON API v3 is powered by a full indexer that reads from the node database and stores parsed data in PostgreSQL. This allows for precise queries on transactions, smart contract calls, NFT ownership, Jetton balances, and more.

Architecture Details

TON API v2

TON API v2 connects to the network using the TON-specific ADNL protocol. Since this binary transport is not HTTP-compatible, a middleware service like TON HTTP API is used to bridge the gap, translating HTTP requests into calls through tonlibjson.

This makes v2 suitable for developers who want to stay close to the source of truth and are comfortable working with less processed data.

TON API v3

TON API v3 relies on the TON Indexer stack. This system reads data from the RocksDB database used by full nodes and imports it into PostgreSQL for easier access. The stack includes:

• A PostgreSQL database for indexed data
• A REST API server built with Fiber
• Services that classify and organize blockchain events
• Indexing workers that extract and normalize on-chain data

This setup enables structured responses and advanced querying capabilities.

Summary

Use case	Recommended API
Live monitoring	v2
Clean historical data	v3
Smart contract insights	v3
Basic wallet balances	v2
NFT or Jetton analytics	v3

Tip

If the data you need is available in v2 and you don’t require historical lookups or filters, v2 is usually faster and simpler to integrate.

---

Try It Out

• API v2
• API v3

Need help choosing? Reach out to the TON Center team.