TON Node and RPC API: Connecting to The Open Network

TON Architecture and the Sharded Chain Model

TON is not a single linear chain. It is organised as a masterchain, which stores protocol state and validator information, plus one or more workchains, each of which can be further partitioned into shardchains. This means that when you query an account, the node must resolve which shard and workchain hold that account. An address carries a workchain id and, for shards, a shard prefix, so the mental model is many chains rather than one.

This sharded design is why TON nodes and APIs differ from EVM JSON-RPC endpoints. A generic EVM endpoint can answer eth_getBalance for any address without shard resolution because there is one canonical chain. In TON, the node must first determine the correct shard, which is encoded in the address. The TON network page provides an overview of these components.

The asynchronous execution model further distinguishes TON. Transactions are messages that can trigger other messages, and execution may span multiple blocks. There is no synchronous receipt that returns the final state of a complex interaction. Instead, you observe confirmation by polling transaction history for the relevant account. The TON documentation on messages and transactions explains this model in detail.

• Masterchain: stores protocol state, validator set, and configuration.
• Workchains: independent chains with their own rules; at least one workchain exists for smart contracts.
• Shardchains: subdivisions of workchains that process accounts in parallel.
• Address format: workchain id + account hash, sometimes with a shard prefix for internal routing.

Node Roles: Validators, Full Nodes, and Liteservers

A validator secures the network by participating in consensus. Validators must stake TON, maintain eligibility, and manage keys. Running a validator is a separate operational concern from serving API queries. A full node, by contrast, syncs the chain and can serve queries via the liteserver protocol. A liteserver-enabled node exposes a binary TCP interface that clients can use to request blocks, account states, and run methods.

The TON documentation on running a full node describes the setup process and the liteserver configuration. For most application developers, running a full node is not required; instead, they connect to an HTTP API that wraps a liteserver. This separation of concerns means you can choose a managed endpoint from a provider rather than operating infrastructure yourself.

If you do operate a node, the node troubleshooting guide covers common issues such as sync stalls and port configuration. The key takeaway is that the liteserver protocol is binary and provider-specific, so direct integration is rare outside of infrastructure teams.

• Validator: requires stake, key management, and eligibility; secures consensus.
• Full node: syncs the chain and can enable liteserver for queries.
• Liteserver: binary TCP protocol for direct node queries.
• HTTP API: JSON over HTTP wrapper around a liteserver, used by most apps.

API Layers: Liteserver, HTTP Wrappers, and Indexer APIs

There are three practical API layers. First, the liteserver protocol over TCP is what a self-hosted node exposes directly. It is efficient but binary and not human-readable. Second, HTTP API wrappers speak JSON over HTTP to a liteserver; these are what most applications integrate with. TON Center and similar services provide v2 and v3 HTTP APIs. Third, indexer or explorer APIs offer historical and aggregate lookups, often with additional indexing for transactions and messages.

The v3 HTTP API is the current recommended interface for new work. It exposes methods for run-method execution, account state, transaction history, block lookup, and sending BOCs (bags of cells). Keyed requests use an API key header for higher rate limits. The v2 API is legacy and should be avoided for new projects. For a comparison of protocol styles, see JSON-RPC vs gRPC vs REST.

When choosing an endpoint, consider whether you need historical depth. Indexer-backed APIs can serve deep history, but a liteserver-only endpoint may only retain recent blocks. The accessing historical blockchain data article discusses archive requirements. For TON-specific endpoints, the TON RPC endpoints page lists managed options.

• Liteserver: binary TCP, direct node access, provider-specific.
• HTTP API v3: JSON over HTTP, recommended for new integrations.
• HTTP API v2: legacy, avoid for new work.
• Indexer APIs: historical and aggregate queries, may require archive nodes.

Practical Integration Surface: v3 HTTP API Methods

The v3 HTTP API exposes a set of methods that cover common integration needs. For account state, you can call getAddressInformation or getAccountState to retrieve balance, status, and code hash. For run-method execution, runGetMethod allows you to call a smart contract's get method without sending a transaction. For transaction history, getTransactions returns a list of transactions for an account. For block lookup, getBlockHeader and getMasterchainInfo provide block metadata. For sending messages, sendBoc accepts a base64-encoded BOC.

Keyed requests use an API key header, typically X-API-Key, to authenticate and receive higher rate limits. Without a key, public endpoints may impose strict limits. The exact header name and rate limits vary by provider, so consult the provider's documentation. OnFinality's API service provides managed TON endpoints with API key support.

When constructing requests, pay attention to address format. The API may accept both user-friendly and raw forms, but some methods require a specific format. Always validate the address before sending a request to avoid errors.

• getMasterchainInfo: returns latest masterchain block seqno and shard.
• getAddressInformation: returns account balance, status, and code.
• runGetMethod: executes a get method on a contract.
• getTransactions: returns transaction history for an account.
• sendBoc: broadcasts a signed external message.

Address Formats and Message Semantics in TON

TON addresses are often represented in two forms: user-friendly (base64url) and raw (workchain:hash). The user-friendly form includes a checksum and flags, making it safer for display and input. The raw form is a 64-bit workchain id followed by a 256-bit account hash, typically written as workchain:hex_hash. Converting between them requires care because the user-friendly form encodes the workchain and hash with a specific tag and checksum.

Transfers in TON are asynchronous messages. An external-in message initiates a transaction, which may produce internal messages to other accounts. There is no synchronous receipt that returns the final outcome. Instead, you must poll the transaction history of the destination account to confirm that the message was processed. This is a fundamental difference from EVM chains, where a transaction receipt is returned immediately after mining.

The TON documentation on messages and transactions provides the canonical explanation of this model. When integrating, design your application to handle asynchronous confirmation, for example by polling getTransactions for the destination address until the expected transaction appears.

• User-friendly address: base64url with checksum, e.g. EQD....
• Raw address: workchain:hash, e.g. 0:abc....
• External-in message: initiates a transaction from outside the chain.
• Internal message: sent between accounts, may trigger further transactions.
• Confirmation: observed by polling transaction history, not a synchronous receipt.

Verifying Endpoint Liveness with Masterchain Info

Before integrating deeply, verify that your chosen endpoint is serving live data. A lightweight method such as getMasterchainInfo returns the latest masterchain block seqno. If the seqno advances over time, the endpoint is syncing and serving current data. You can also read an account state and confirm that the last transaction time is recent.

The following curl example queries the masterchain head info from a TON HTTP API endpoint. Replace YOUR_API_KEY and the base URL with your provider's details. The response includes the seqno, which you can compare across calls to confirm liveness.

For a more thorough check, query an active account's state and a run-method result. The next section provides a Node.js example that does all three.

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://toncenter.com/api/v3/masterchainInfo" | jq '.result.last.seqno'

Runnable Node.js Example: Masterchain, Account State, and Run-Method

This Node.js script queries a TON HTTP API endpoint for the masterchain head, an account's state, and a run-method result. It uses the built-in fetch API (Node.js 18+). Replace YOUR_API_KEY and the base URL with your provider's details. The script prints the masterchain seqno, the account status, and the method result.

The example also contrasts a user-friendly address with its raw form. You can convert between them using libraries such as @ton/core, but for demonstration we show both strings. The raw form is derived from the user-friendly form by decoding the base64url and extracting the workchain and hash.

Run the script and observe the output. If the masterchain seqno is a large number and the account status is active, the endpoint is serving live data. If the run-method returns a result, the contract is callable.

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://toncenter.com/api/v3';
const USER_FRIENDLY = 'EQD...'; // replace with a real address
const RAW = '0:...'; // replace with the raw form

async function main() {
  const headers = { 'X-API-Key': API_KEY };

  // 1. Masterchain info
  const mc = await fetch(`${BASE_URL}/masterchainInfo`, { headers }).then(r => r.json());
  console.log('Masterchain seqno:', mc.result.last.seqno);

  // 2. Account state (user-friendly)
  const state = await fetch(`${BASE_URL}/addressInformation?address=${USER_FRIENDLY}`, { headers }).then(r => r.json());
  console.log('Account status:', state.result.status);
  console.log('Balance (nanotons):', state.result.balance);

  // 3. Run-method (raw address)
  const run = await fetch(`${BASE_URL}/runGetMethod?address=${RAW}&method=seqno`, { headers }).then(r => r.json());
  console.log('Run-method result:', run.result.stack);
}

main().catch(console.error);

Reproducible Results Table for Your Endpoint

To systematically verify an endpoint, fill in the following table with your observations. Use the methods described above. The table helps you compare providers and detect inconsistencies. Record the endpoint URL, the method called, the expected field, the observed value, and any notes such as latency or errors.

For each method, call it at least twice with a short delay to see if values advance. For getMasterchainInfo, the seqno should increase. For getAddressInformation, the balance may change if the account is active. For runGetMethod, the result should be consistent for a deterministic method.

This method is reproducible and does not rely on fabricated benchmarks. It is a verified-by-reader approach: you measure against your own endpoint and record the results.

• Method: getMasterchainInfo | Expected field: result.last.seqno | Observed: [fill] | Notes: [fill]
• Method: getAddressInformation | Expected field: result.status | Observed: [fill] | Notes: [fill]
• Method: runGetMethod | Expected field: result.stack | Observed: [fill] | Notes: [fill]
• Method: getTransactions | Expected field: result.length | Observed: [fill] | Notes: [fill]

Limitations and Tradeoffs of TON Node and API Integration

The liteserver protocol is binary and provider-specific, so most teams use an HTTP wrapper rather than speaking it directly. This adds a dependency on the wrapper's availability and rate limits. The v2 API is legacy and should be avoided for new work in favour of v3. Historical depth depends on the endpoint's indexer; deep history may require an archive-capable provider, as discussed in archive node vs full node.

API keys are required for meaningful rate limits on public endpoints. Without a key, you may encounter throttling. TON's asynchronous message model means that 'transaction succeeded' must be derived from transaction history rather than a synchronous receipt. This complicates integration for developers accustomed to EVM-style receipts.

Finally, address conversion errors can lead to lost funds or failed queries. Always validate addresses and use well-tested libraries for conversion. The Bittensor RPC node guide offers a comparison of node integration patterns in another ecosystem.

• Liteserver: binary, provider-specific, rarely integrated directly.
• v2 API: legacy, avoid for new projects.
• Historical depth: depends on indexer; archive providers needed for deep history.
• API keys: required for higher rate limits.
• Asynchronous model: confirmation via polling, not synchronous receipts.

Troubleshooting Common TON API Integration Issues

If getMasterchainInfo returns a stale seqno, the endpoint may be out of sync or rate-limited. Check your API key and try another endpoint. If runGetMethod fails, ensure the address is in the correct format and the method name is correct. Some methods require arguments; pass them as an array in the request body.

If sendBoc returns an error, verify that the BOC is properly base64-encoded and signed. The external message must have a valid signature and sequence number. If transactions do not appear in getTransactions, the message may not have been processed yet; wait and poll again. The node troubleshooting guide covers node-side issues.

For rate limit errors, reduce request frequency or upgrade to a higher tier. OnFinality's RPC pricing page outlines available plans. Always handle HTTP 429 responses with exponential backoff.

• Stale seqno: check sync status and API key.
• Run-method failure: verify address format and method name.
• SendBoc error: check BOC encoding and signature.
• Missing transactions: poll again after a delay.
• Rate limits: use API key and backoff on 429.

Next Steps for TON Integration

To move forward, choose a managed TON endpoint from a provider that offers v3 API support and sufficient historical depth. The TON RPC endpoints page lists options. If you need to run your own node, follow the full node guide and enable liteserver.

For application development, start with the v3 HTTP API and use the runnable examples above to verify connectivity. Implement polling for transaction confirmation and handle asynchronous message flows. Explore the OnFinality Learn hub for more guides on blockchain integration.

Finally, consider your archival needs. If you require deep history, select an archive-capable provider. The accessing historical blockchain data article explains the tradeoffs. With these steps, you can integrate TON into your application reliably.

• Choose a managed endpoint with v3 API and API key support.
• Run your own node if you need direct liteserver access.
• Implement polling for asynchronous confirmation.
• Select an archive provider for deep history.
• Refer to OnFinality Learn for more integration guides.