TON API: How to Choose and Use Endpoints for Mainnet and Testnet

TON API Decision Checklist

Before integrating a TON API, evaluate these criteria to match your workload:

What Is a TON API?

TON (The Open Network) uses a custom binary protocol (ADNL) for node communication. A TON API acts as a bridge, translating standard HTTP/HTTPS requests into ADNL calls to liteservers. This allows developers to query blockchain data, send transactions, and subscribe to events using familiar REST or GraphQL interfaces.

Most TON APIs are built on top of the open-source ton-http-api project, which can also be self-hosted. The main differences between providers lie in indexing, rate limits, reliability, and added services like webhooks or SDKs.

TON API Providers: Main Options

1. TON Center

TON Center offers two API versions:

• v2: Direct liteserver proxy – supports proofs, but no indexing. Good for simple reads and writes.
• v3: Indexed database – enables rich queries for jettons, NFTs, traces, and historical data. No proof responses.

Both versions are free with an API key (up to a certain rate) and can be self-hosted. Testnet endpoints are available.

2. TonAPI (tonapi.io)

TonAPI is a SaaS platform providing REST, GraphQL, and streaming APIs. It features an integrated indexer, webhooks, and SDKs. Pricing is based on request volume, with a free tier for low usage. It does not return cryptographic proofs.

3. OnFinality TON API

OnFinality provides TON RPC endpoints as part of its multi-chain API service. You can access public endpoints or provision a dedicated node for higher reliability and rate limits. OnFinality also supports testnet and offers failover across multiple node instances. Check the pricing page for plan details.

4. Self-Hosted

Deploy the ton-http-api project on your own infrastructure. Recommended hardware: 1 vCPU, 2 GB RAM (without cache) or 2 vCPU, 4 GB RAM (with cache). You must also run a TON liteserver or connect to public liteservers.

TON API Endpoints: Mainnet and Testnet Settings

Below are common endpoints. Always verify the latest URLs in the official documentation.

Chain ID (workchain): 0 for basechain, -1 for masterchain.

Getting Started: Faucet and First Request

Testnet Faucet

Use the TON testnet faucet to receive free test coins. Common faucets:

• TON Center Testnet Faucet (Telegram bot)
• Third-party faucets listed in the TON documentation.

Example: Retrieve Account Balance via TON Center v2

curl -X GET "https://toncenter.com/api/v2/getAddressBalance?address=EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N&api_key=YOUR_API_KEY"

If successful, response:

{"ok":true,"result":"5000000000"}

Using OnFinality TON API

After obtaining an API key from OnFinality, you can make requests to the provided endpoint. For example:

curl -X POST "https://ton-mainnet.onfinality.io/api/v2/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"method":"getAddressBalance","params":{"address":"EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N"}}'

Common Pitfalls and Debugging

• Rate limiting: Public endpoints (no key) are heavily rate-limited. Always register for an API key. For production, consider dedicated infrastructure.
• Missing proofs: If your use case requires trustless verification, use a liteserver-based API (TON Center v2, self-hosted ton-http-api). Indexed APIs (v3, TonAPI) do not return proofs.
• Workchain confusion: Most user addresses are in workchain 0. Masterchain addresses start with -1: and require special handling.
• Transaction submission: To send transactions, you must serialize the message externally and pass it as a base64 or hex string. Most APIs provide a /sendBoc endpoint for this.
• CORS issues: If calling from a browser, ensure the API supports CORS or use a backend proxy.

Key Takeaways

• TON APIs abstract the low-level ADNL protocol, offering HTTP/JSON access.
• Choose between direct liteserver proxies (proofs, no indexing) and indexed APIs (rich queries, no proofs).
• For production workloads, evaluate rate limits, historical depth, and failover support. Dedicated nodes or multi-provider setups improve reliability.
• Testnet endpoints and faucets are essential for development. Always verify compatibility with your tools (e.g., wallet SDKs).
• OnFinality provides TON RPC endpoints and dedicated nodes with flexible pricing and global coverage.

Frequently Asked Questions

Q: What is the difference between TON Center v2 and v3? A: v2 is a direct liteserver proxy that returns Merkle proofs; v3 uses an indexed database for richer queries but does not return proofs. Choose v2 if you need verifiable responses, v3 for complex data retrieval.

Q: Can I use a TON API without an API key? A: Yes, but rate limits are very low (e.g., 1 request/second). Register for a free key to increase limits.

Q: How do I send a transaction via TON API? A: Use the sendBoc endpoint with a serialized message in base64 or hex. Example: POST /api/v2/sendBoc with body {"boc":"te6cck..."}.

Q: Does OnFinality support TON testnet? A: Yes, OnFinality provides TON testnet endpoints. See the network page for details.

Q: What is the TON mainnet chain ID? A: The workchain ID is typically 0 for basechain, -1 for masterchain. There is no separate chain ID like EVM chains; the network is identified by the global config.