How do I connect to the TON testnet?

Quick recommendation: pick an endpoint that matches your workload

Before you write any code, decide how you will interact with the TON testnet. The right choice depends on whether you are building a simple script, a production-grade dApp, or a high-throughput indexer.

• For quick experiments and one-off calls, a public endpoint or the TON Center HTTP API is enough. You can start with a free API key and a rate limit of one request per second.
• For staging, QA, and load testing, you need a dedicated testnet RPC endpoint that can handle sustained traffic without throttling. Public endpoints often rate-limit aggressively, which can break your test suite.
• For production planning, treat the testnet as a rehearsal for mainnet. Choose a provider that offers the same endpoint types and reliability on both networks, so you can migrate with minimal code changes.

If you are unsure, start with a managed RPC service like OnFinality's TON testnet endpoint and check the RPC pricing to see if a free tier fits your needs. You can always switch later.

What is the TON testnet?

The TON testnet is a separate blockchain network maintained by the TON Foundation and community validators. It mirrors the mainnet's functionality but uses testnet TON (tGRM) that has no real value. Developers use it to deploy smart contracts, test wallet integrations, and simulate transactions without financial risk.

The testnet has its own explorers, such as testnet.tonscan.org and testnet.tonviewer.com, and its own HTTP API at testnet.toncenter.com. Note that the original testnet resources at test.ton.org are outdated and no longer supported; always use the current community-maintained endpoints.

Chain settings at a glance

These settings are enough to configure a wallet or a dApp. For a full list of supported networks, see supported RPC networks.

Getting testnet coins

To interact with the testnet, you need testnet TON (tGRM). The official faucet is a Telegram bot called @testgiver_ton_bot. Here is how to use it:

1. Open Telegram and search for @testgiver_ton_bot.
2. Start the bot and click Get 2 GRAM in testnet.
3. Complete the captcha and enter your testnet wallet address.
4. Wait a few seconds for the bot to process the request.
5. Verify the transfer using a testnet explorer.

You can request 2 tGRM per hour. For larger amounts, you may need to run your own faucet or use a community faucet. Always double-check that the address you provide is a testnet address, not a mainnet one.

Connecting via HTTP API

The simplest way to interact with the TON testnet is through the TON Center HTTP API. You can use it without an API key, but the rate limit is 1 request per second. For higher limits, register an API key via the @toncenter bot.

Here is a basic curl example to get the balance of an address:

curl -X GET \
  'https://testnet.toncenter.com/api/v2/getAddressBalance?address=EQD...' \
  -H 'accept: application/json'

Replace EQD... with your testnet address. The response will include the balance in nanoTON.

Using a dedicated RPC endpoint

For development and testing, a managed RPC endpoint is often more reliable than a public one. OnFinality provides a TON testnet endpoint that you can use with the same JSON-RPC interface as mainnet. Here is how to make a request:

curl -X POST \
  https://ton-testnet.onfinality.io/api/v3 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "ton_getAddressBalance",
    "params": ["EQD..."],
    "id": 1
  }'

Note: The exact endpoint URL and method names may vary. Check the TON testnet network page for the latest details.

Choosing a testnet RPC provider

When evaluating a testnet RPC provider, consider the following criteria:

A managed service like OnFinality offers consistent endpoints across testnet and mainnet, which can save you time when you move to production. Check the RPC pricing to see if a free tier fits your needs.

Common pitfalls and how to avoid them

• Using mainnet addresses on testnet: Testnet and mainnet addresses look similar but are not interchangeable. Always generate a fresh testnet wallet.
• Ignoring rate limits: Public endpoints are heavily rate-limited. If your test suite makes many requests, you will hit 429 errors. Use a dedicated endpoint or add retry logic.
• Assuming testnet is always up: Testnets can have downtime or resets. Monitor your endpoints and have a fallback plan.
• Forgetting to verify transactions: After requesting testnet coins, verify the transfer on an explorer. The faucet does not send a confirmation message.

Debugging your testnet connection

If you are having trouble connecting, follow this debug path:

1. Check your endpoint URL: Ensure you are using the correct testnet URL, not mainnet.
2. Test with a simple request: Use curl to call getMasterchainInfo and see if you get a response.
3. Check your API key: If you are using a key, verify it is valid and not expired.
4. Look for rate limit errors: If you see 429 responses, wait or switch to a higher-tier endpoint.
5. Verify your address: Make sure you are using a testnet address and that it is correctly formatted.

Here is a curl command to check the masterchain info:

curl -X POST \
  https://ton-testnet.onfinality.io/api/v3 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "ton_getMasterchainInfo",
    "id": 1
  }'

If you get a response, your connection is working. If not, check your network settings and firewall.

Key Takeaways

• The TON testnet is a public sandbox for development, with its own explorers, APIs, and faucets.
• Use the official Telegram bot @testgiver_ton_bot to get testnet coins.
• For reliable development, choose a dedicated RPC endpoint over a public one, especially for staging and QA.
• Evaluate providers based on rate limits, uptime, method support, and mainnet parity.
• Always verify your testnet address and transactions to avoid common mistakes.

Frequently Asked Questions

What is the difference between TON testnet and mainnet?

The testnet uses testnet TON (tGRM) with no real value, while mainnet uses real TON. The testnet is for development and testing, and its state can be reset at any time.

How do I get testnet TON?

Use the Telegram bot @testgiver_ton_bot to request 2 tGRM per hour. You need a testnet wallet address to receive the coins.

Can I use the same RPC endpoint for testnet and mainnet?

Yes, if your provider supports both networks. OnFinality offers endpoints for both TON testnet and mainnet, so you can switch with minimal code changes.

What are the rate limits for the TON testnet API?

Public endpoints like TON Center limit you to 1 request per second without an API key. With a key, limits are higher. Managed providers may offer different limits; check their documentation.

How do I verify a transaction on the testnet?

Use a testnet explorer like testnet.tonscan.org or testnet.tonviewer.com. Enter your wallet address or transaction hash to see the details.