OnFinality

Posted on Aug 19 Originally published at onfinality.io

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

#web3 #blockchain #ton #tutorial

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.

Workload	Recommended access	Why
Prototype, hackathon, low-traffic bot	Public endpoint with API key	Free, fast to start, but rate limits apply
Production dApp, wallet, or indexer	Managed RPC service	Reliable endpoints, scaling, and support
High-throughput, custom queries, or compliance	Dedicated node	Full control, no shared rate limits, custom configuration

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:

Method	Description
`getMasterchainInfo`	Returns the latest masterchain block information
`getAddressBalance`	Returns the balance of an address in nanoTON
`getAddressInformation`	Returns account state, balance, code, and data
`getWalletInformation`	Returns wallet-specific information
`runGetMethod`	Executes a GET method on a smart contract
`sendBoc`	Sends a serialized message (bag of cells) to the network
`getTransactions`	Returns transaction history for an address

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:

Public endpoints – Free but rate-limited (1 RPS without a key). Good for testing and low-traffic apps.
Managed RPC services – Provide reliable endpoints with higher rate limits, monitoring, and support. OnFinality offers TON RPC as a managed service.
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.

Related resources

Originally published at OnFinality.

DEV Community