TON JSON-RPC: Endpoint, Methods, and How to Use It

Quick decision guide: which TON RPC setup fits your app?

Before you wire up a client, decide which TON RPC access model matches your workload. The choice affects latency, rate limits, and how much infrastructure you manage.

If you need a managed endpoint with predictable performance, OnFinality offers TON RPC endpoints and TON Testnet RPC with HTTPS JSON-RPC support. For production workloads, a managed service removes the operational burden of running your own node. See RPC pricing for details.

What is TON JSON-RPC?

TON JSON-RPC is a JSON-RPC 2.0 interface to The Open Network (TON), a non-EVM layer-1 blockchain. Unlike Ethereum's JSON-RPC, TON's interface is not EVM-compatible and uses its own set of methods. It provides a single HTTPS endpoint where you can call methods to read blockchain data, run smart contract get-methods, and send transactions.

TON nodes communicate internally using the binary ADNL protocol, which is not directly accessible from web applications. TON JSON-RPC acts as a bridge, translating standard HTTP JSON-RPC requests into node calls and returning results in a familiar format.

TON JSON-RPC endpoint and authentication

The primary TON JSON-RPC endpoint is provided by TON Center:

• Mainnet: https://toncenter.com/api/v2/jsonRPC
• Testnet: https://testnet.toncenter.com/api/v2/jsonRPC

All API methods are available through this single endpoint. You authenticate by sending an API key in the X-API-Key header. Without a key, requests are limited to 1 request per second. With a key, limits are higher but still apply.

Example request:

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

Response:

{
  "ok": true,
  "result": {
    "last": {
      "workchain": -1,
      "shard": "-9223372036854775808",
      "seqno": 123456,
      "root_hash": "...",
      "file_hash": "..."
    },
    "state_root_hash": "...",
    "init": {
      "workchain": -1,
      "shard": "-9223372036854775808",
      "seqno": 0,
      "root_hash": "...",
      "file_hash": "..."
    }
  },
  "@extra": "...",
  "jsonrpc": "2.0",
  "id": "1"
}

Common TON JSON-RPC methods

TON JSON-RPC exposes a set of methods that map to the TON Center API v2. Here are the most frequently used ones:

For a full list, refer to the official TON documentation.

Using TON JSON-RPC with JavaScript

You can call TON JSON-RPC from any language. Here's a JavaScript example using fetch:

const endpoint = "https://toncenter.com/api/v2/jsonRPC";
const apiKey = "YOUR_API_KEY";

async function callTonRpc(method, params = {}) {
  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": apiKey
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method,
      params
    })
  });
  return response.json();
}

// Get balance of an address
const balance = await callTonRpc("getAddressBalance", {
  address: "EQD..."
});
console.log(balance.result);

TON JSON-RPC vs REST API

TON Center offers both REST and JSON-RPC endpoints. The REST API uses separate URLs for each method (e.g., /getAddressBalance), while JSON-RPC uses a single endpoint with a method field. JSON-RPC is useful when you want to batch multiple calls or prefer a consistent interface.

Public vs managed vs dedicated TON RPC

When using TON JSON-RPC, you have three main options:

1. Public endpoints – Free but rate-limited (1 RPS without a key). Good for testing and low-traffic apps.
2. Managed RPC services – Provide reliable endpoints with higher rate limits, monitoring, and support. OnFinality offers TON RPC as a managed service.
3. Dedicated nodes – You get your own TON node, full control over configuration, and no shared rate limits. This is ideal for high-throughput or custom use cases.

Troubleshooting common TON JSON-RPC issues

• 401 Unauthorized: Check your API key and ensure it's valid.
• 403 Forbidden: Your API key may not have permission for the requested method.
• 429 Too Many Requests: You've exceeded the rate limit. Wait or upgrade your plan.
• 422 Unprocessable Entity: Your request parameters are invalid. Check the method signature.
• 500 Internal Server Error: The node may be experiencing issues. Retry later.
• 504 Gateway Timeout: The request took too long. Consider using a dedicated node for heavy queries.

Key Takeaways

• TON JSON-RPC is a JSON-RPC 2.0 interface to The Open Network, using a single HTTPS endpoint.
• Authentication is via X-API-Key header; without a key, you're limited to 1 RPS.
• Common methods include getMasterchainInfo, getAddressBalance, and runGetMethod.
• Choose public, managed, or dedicated RPC based on your workload and reliability needs.
• For production, consider a managed service like OnFinality's TON RPC to avoid rate limits and operational overhead.

Frequently Asked Questions

Is TON JSON-RPC compatible with Ethereum JSON-RPC? No. TON is a non-EVM blockchain, so its JSON-RPC methods are different. You cannot use eth_getBalance or other EVM methods.

How do I get a TON API key? You can get a key from TON Center by registering your application. Managed providers like OnFinality also provide API keys with their endpoints.

Can I use WebSocket with TON JSON-RPC? TON JSON-RPC is HTTP-based. For real-time updates, TON offers a separate Streaming API with WebSocket support.

What is the rate limit for TON JSON-RPC? Without an API key, the limit is 1 request per second. With a key, limits are higher but vary by provider.

How do I send a transaction using TON JSON-RPC? You need to serialize your transaction into a bag of cells and use the sendBoc method. This is more complex than EVM transactions.

For more details, explore supported RPC networks and RPC pricing.