OnFinality

Posted on Aug 8 • Originally published at onfinality.io

TON Testnet RPC: Endpoints, Setup, and Best Practices

#web3 #blockchain #ton #tutorial

Quick recommendation: which TON testnet RPC should you use?

If you are building a dApp, wallet, or bot on TON, you need a testnet endpoint that is reliable enough for continuous integration and debugging. Public endpoints like https://testnet.toncenter.com/api/v2/jsonRPC work for light testing, but they often have rate limits and no uptime guarantee. For a more stable experience, consider a managed RPC provider like OnFinality, which offers dedicated TON testnet endpoints with higher throughput and better reliability. Check the TON testnet network page for the latest endpoint details.

What is TON testnet?

TON (The Open Network) testnet is a separate blockchain network used for development and testing. It mirrors the mainnet's functionality but uses test TON tokens that have no real value. Developers use it to deploy smart contracts, test wallet integrations, and simulate transactions without financial risk.

TON testnet RPC endpoints at a glance

The following table lists common public TON testnet RPC endpoints. Note that availability and rate limits can change, so always check the provider's documentation.

Provider	Endpoint	Authentication	Notes
TON Center	`https://testnet.toncenter.com/api/v2/jsonRPC`	API key (optional)	Rate limit without key: 1 req/s
OnFinality	`https://ton-testnet.api.onfinality.io/public/jsonRPC`	API key (recommended)	Managed service with higher limits
Tatum	`https://ton-testnet.gateway.tatum.io/jsonRPC`	API key	Requires account
dRPC	`https://ton-testnet.drpc.org`	None	Public, may have rate limits

How to connect to TON testnet RPC

Using curl with JSON-RPC

The TON API v2 supports JSON-RPC. Here is a basic getMasterchainInfo call:

curl "https://testnet.toncenter.com/api/v2/jsonRPC" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getMasterchainInfo",
    "params": {}
  }'

If you have an API key, add it via header or query parameter:

curl "https://testnet.toncenter.com/api/v2/jsonRPC" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getMasterchainInfo",
    "params": {}
  }'

Using JavaScript (ton library)

If you are using the ton npm package, you can create a client with a custom HTTP endpoint:

import { TonClient } from "ton";

const client = new TonClient({
  endpoint: "https://testnet.toncenter.com/api/v2/jsonRPC",
  apiKey: "YOUR_API_KEY" // optional
});

async function main() {
  const info = await client.getMasterchainInfo();
  console.log(info);
}

main();

Authentication and rate limits

Public TON testnet endpoints often limit requests to one per second without an API key. To increase your limits, you need to register for an API key. The TON Center API v2 accepts the key in the X-API-Key header or as a api_key query parameter. Always keep your API key secret and never expose it in client-side code.

Choosing a TON testnet RPC provider

When selecting a provider for your testnet RPC, consider the following:

Reliability: Public endpoints may go down or throttle. A managed provider like OnFinality offers dedicated infrastructure with better uptime.
Rate limits: Free public endpoints often have strict limits. If your tests make many requests, you need a provider with higher allowances.
Geographic distribution: Providers with multiple regions reduce latency for your users.
Support: Managed services typically offer support channels and documentation.

For production workloads, you might also want to consider a dedicated node. See RPC pricing for options.

Common pitfalls and troubleshooting

429 Too Many Requests

This error means you exceeded the rate limit. Wait a second or add an API key to increase your limit.

Authentication errors

If you get a 401, your API key is invalid or missing. Check that you are sending it correctly in the header or query parameter.

Network issues

If the endpoint is unreachable, try a different provider or check your internet connection. You can also use a monitoring tool to test endpoint health.

Key Takeaways

TON testnet RPC endpoints allow you to interact with the testnet for development and testing.
Public endpoints are convenient but may have rate limits and reliability issues.
For serious development, consider a managed RPC provider like OnFinality for better performance and support.
Always secure your API keys and follow best practices for authentication.

Frequently Asked Questions

What is the RPC URL for TON testnet?

A common public endpoint is https://testnet.toncenter.com/api/v2/jsonRPC. OnFinality also provides a testnet endpoint at https://ton-testnet.api.onfinality.io/public/jsonRPC.

Do I need an API key for TON testnet RPC?

Not strictly, but without one you are limited to one request per second. For higher limits, you should obtain an API key from the provider.

Can I use TON testnet RPC for production?

No, testnet is for development and testing only. For production, you should use TON mainnet RPC endpoints.

How do I get test TON tokens?

You can get test TON from the TON testnet faucet. Check the official TON documentation for the current faucet URL.

What is the difference between TON testnet and mainnet RPC?

Testnet RPC connects to the testnet network, which uses test tokens and is for development. Mainnet RPC connects to the live network with real TON.

For more information on supported networks and endpoints, visit the supported RPC networks page.

Related resources

Originally published at OnFinality.

DEV Community