TON API Keys: How Do You Get One and When Do You Need It?

If you searched for a TON API key, you probably already have a wallet, a script, or a backend service that needs to talk to The Open Network and you have hit a wall: the public endpoint works for a quick test, but you need something you can authenticate, monitor, and scale. This page answers the practical questions first — what the key is, how to get one, and how to use it — then helps you decide whether a shared keyed endpoint is enough or whether your workload needs a dedicated TON node.

Quick answer: what a TON API key is and what it is not

A TON API key is a credential issued by an RPC or API provider. You attach it to your requests, and the provider uses it to identify your project, apply the rate limits and quotas tied to your plan, and give you usage visibility. It is not a wallet key, it does not sign transactions, and it does not give you special access to the TON blockchain itself. It only controls how you reach the node infrastructure that serves your requests.

That distinction matters because TON has two common access styles:

• JSON-RPC over HTTP, where you send method calls such as runGetMethod or sendBoc to an endpoint and authenticate with a header or query parameter.
• HTTP API wrappers, where a provider exposes higher-level REST-style routes (account state, transaction history, jetton metadata) on top of the raw node.

Both styles can require a key. Neither style lets you bypass consensus or read data the node does not have.

Decide first: shared keyed endpoint or dedicated node?

Before you sign up for anything, match your workload to the access model. Most teams over-buy at the start and under-buy at launch, so use this as a quick filter.

If you are in the top half of that table, a keyed shared endpoint is the pragmatic choice. If you are in the bottom half, read the dedicated node section before you commit to a plan.

How to get a TON API key

The exact flow depends on the provider, but the shape is consistent:

1. Create an account with the RPC provider you want to use.
2. Create a project or application inside the dashboard. This is the unit that owns the key and the usage counters.
3. Generate an API key for that project. Some providers give you a key immediately; others require you to pick a plan first.
4. Choose your network: TON mainnet or TON testnet. Keep them as separate keys so a testnet script can never touch mainnet data.
5. Restrict the key if the provider supports it — allowed origins, IP allowlists, or per-method scopes.
6. Store the key in a secret manager, not in your repository. Treat it like any other credential.

OnFinality issues keys through the same project model. You can review the TON RPC network page for endpoint details and the TON Testnet page for testnet access, then check RPC pricing to see which plan matches your expected request volume.

Sending your first authenticated TON request

TON's JSON-RPC surface is not identical to EVM chains, so do not assume eth_* methods will work. A typical authenticated call looks like this:

curl -s https://ton-mainnet.example-rpc-provider.com/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TON_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "runGetMethod",
    "params": {
      "address": "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c",
      "method": "seqno",
      "stack": []
    }
  }'

Replace the host with the endpoint your provider gives you. The important parts are the X-API-Key header (some providers use an Authorization: Bearer header or an ?api_key= query parameter instead) and the JSON-RPC envelope. If you are using an HTTP API wrapper rather than raw JSON-RPC, the same key goes in the same header, but the path and body shape will differ.

A minimal JavaScript client using fetch looks like this:

const res = await fetch(process.env.TON_RPC_URL, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.TON_API_KEY
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "getMasterchainInfo",
    params: {}
  })
});

const data = await res.json();
if (data.error) throw new Error(JSON.stringify(data.error));
console.log(data.result);

Keep the URL and the key in environment variables. Rotating a leaked key should be a config change, not a code change.

TON endpoint and network settings at a glance

Always confirm the current method list and transport support against the provider's documentation, because TON tooling evolves and wrappers add or rename routes over time. The OnFinality TON network page is the canonical reference for what is supported on our side.

Common failure modes and how to debug them

Most "my TON API key does not work" reports fall into a small number of buckets. Work through them in order.

A useful habit is to log the HTTP status code and the JSON-RPC error object separately. Providers often return a valid JSON-RPC error with a non-200 HTTP status, and conflating the two makes debugging slower.

When a shared keyed endpoint stops being enough

A keyed shared endpoint is the right default for most teams. It becomes the wrong tool when one of these is true:

• You are scanning history. Backfilling transactions or building an index means long, expensive reads that compete with other tenants.
• You need consistent latency. Shared pools are fine on average but noisier at the tail, which matters for trading or real-time UX.
• You need isolation. Regulated workloads or anything with strict data boundaries usually cannot share infrastructure.
• You are hitting limits repeatedly. If you are tuning backoff more than you are shipping features, the plan is the problem.

At that point, a dedicated TON node gives you a node that serves your traffic only. You keep the same API key model, but the capacity behind it is yours. OnFinality runs dedicated nodes across many networks, and you can compare the tradeoffs in How to choose an RPC provider before committing.

Operational checklist before you go live

• Keys are stored in a secret manager, not in code or CI logs.
• Mainnet and testnet keys are separate and clearly named.
• You have a retry policy with exponential backoff and jitter for 429 and 5xx.
• You log request IDs so you can correlate failures with provider support.
• You have a fallback endpoint or a documented failover plan.
• You monitor error rate and p95 latency, not just uptime.
• You know your monthly request volume and which RPC pricing tier covers it.
• You have reviewed the full list of supported RPC networks if you plan to expand.

Key Takeaways

• A TON API key authenticates your requests to a provider; it does not sign transactions or change what the blockchain exposes.
• Public endpoints are fine for prototypes; keyed endpoints are the normal production default.
• TON uses its own JSON-RPC method surface, so do not assume EVM method names will work.
• Keep mainnet and testnet keys separate, and store them in a secret manager.
• Most key errors are header mistakes, network mismatches, or rate limits — check those first.
• Move to a dedicated TON node when you need isolation, predictable throughput, or heavy historical reads.

Frequently Asked Questions

Is a TON API key the same as a wallet private key?

No. A wallet private key signs transactions and controls funds. A TON API key only authenticates your requests to an RPC provider. Never treat them as interchangeable, and never paste a wallet key into an RPC configuration.

Can I use a TON API key for free?

Many providers offer a free or trial tier with a key, usually with lower rate limits. It is a reasonable way to prototype. Check the provider's current plan terms, including OnFinality RPC pricing, before you build a production dependency on a free tier.

Which header should I use for a TON API key?

It depends on the provider. Common options are X-API-Key, Authorization: Bearer <key>, or a query parameter. Use whatever the provider documents, and avoid putting keys in URLs that get logged by proxies.

Do I need a separate key for TON testnet?

Yes, in practice. Testnet and mainnet are different networks with different state. Separate keys prevent a test script from accidentally reading or writing mainnet data.

How do I know if I need a dedicated TON node instead?

If you are consistently hitting rate limits, need isolation, or run heavy historical queries, a dedicated node is usually the better fit. Start with the dedicated node overview and compare it against your workload.

Where can I find the current TON endpoint details?

Use the provider's network page as the source of truth. For OnFinality, start with the TON network page and the TON Testnet page.