A wallet talks to the TON blockchain through an API that exposes read methods for balances and transaction history and write methods for broadcasting signed transfers. You call it over HTTP, point it at a specific network endpoint, and authenticate with an API key rather than running your own TON infrastructure. That’s the whole mechanism — the complexity shows up in TON’s own architecture, not in the API call itself.
This guide walks through what that API actually does, why a wallet can’t skip it, and who relies on it in practice, before getting into TON’s cell-based data model, the difference between TON Connect and direct API access, and a working example that checks a wallet’s balance. By the end you’ll know enough to choose the right interface and avoid the mistakes that trip up most first-time TON integrations.
What Is the TON API?
The TON API is the interface a wallet, bot, or dApp uses to read blockchain state and submit transactions on The Open Network, without operating a liteserver or full node itself. It’s the same role an Ethereum RPC endpoint plays for an EVM wallet: fetch a balance, look up a transaction, push a signed message to the network.
One naming note matters here. In June 2026, TON’s native token was renamed from Toncoin to Gram — ticker TON became GRAM — but the network itself kept its name. As crypto.news explains, “the blockchain is still called The Open Network, often shortened to TON; only the currency that runs on it took the new name.” Balances, addresses, and every API method described below are unaffected — this was a token-layer rename, not an infrastructure change.
TON itself isn’t a single service but a family of interfaces built on different layers of the protocol. Liteservers offer direct, cryptographically verifiable access to raw chain data; Toncenter’s HTTP API wraps that into simpler JSON calls; and an indexed layer (TON Index) adds the historical queries a wallet actually needs for a transaction list. A provider like NOWNodes packages these under one API key so you don’t have to run any of the underlying layers yourself.
Why Does a Wallet Need TON API Access?
Without it, a wallet has exactly one alternative: run a liteserver or full node and sync it with the network directly. That means downloading and maintaining chain state, handling TON’s asynchronous, sharded consensus, and keeping the software patched against protocol updates — a maintenance job most wallet teams have no interest in taking on.
API access solves three concrete problems. It lets a wallet show a live balance without polling a self-hosted node, it lets the app broadcast a signed transaction and get a confirmation back, and it lets the app query transaction history for a specific address instead of scanning every block itself.
That last point is the one raw liteserver access can’t solve on its own. A liteserver gives you cryptographic proofs for individual queries, but it has no built-in index of “every transaction for this address” — that’s what the indexed API layer exists to provide.
Who Uses the TON API?
Self-custody wallets are the most direct use case: Tonkeeper, MyTonWallet, and Trust Wallet’s TON integration all sit on top of some combination of these interfaces to show balances, build transactions, and track history. Telegram’s own built-in wallet — recently expanded and rebranded alongside the Gram token — is the highest-volume example, given its access to Telegram’s user base.
Beyond wallets, Telegram Mini Apps and bots use the same methods to accept payments and read on-chain state without their developers ever touching liteserver infrastructure directly. DeFi front ends such as STON.fi, the largest DEX on TON by locked value, depend on the indexed API for the trade history and pool data their interfaces display in real time.
Exchanges, custodial wallets, and block explorers round out the list, typically pulling from the same balance and transaction endpoints a self-custody wallet would use, just at higher volume and with additional monitoring layered on top.
TON Connect vs. the TON API: What’s the Difference?
This is where a lot of first-time TON integrations go wrong. TON Connect is the protocol that lets a dApp request a signature or a transaction from a user’s existing wallet — it’s a connection and signing standard, comparable to WalletConnect on Ethereum.
TON Connect does not give you blockchain data. The official documentation is direct about this: “TON Connect does not provide deeper integrations with the TON blockchain. Implement them manually.” Reading a balance, checking transaction status, or building a transfer still requires the API methods covered in this guide — TON Connect only handles getting a signature out of the user’s wallet once you already know what to sign.
A wallet built from scratch needs both: the API for chain reads and broadcasting, and TON Connect only if it also needs to act as a signer for third-party dApps. Most standalone wallets only need the former.
How TON’s Architecture Changes Wallet Integration
TON’s data model is the real source of integration difficulty, and it’s worth understanding before writing any code. Vadim Volodin, a blockchain engineer who worked on TON’s integration into Trust Wallet, put the core distinction plainly in his write-up of that project: “In TON, a wallet isn’t just an address — it’s a full-fledged smart contract.”
That single fact cascades into several practical differences. A TON address doesn’t exist until its wallet contract is deployed on-chain, so “creating a wallet” means preparing a contract deployment, not just generating a key pair. Volodin also notes that “the same seed phrase produces different keys in Tonkeeper vs. Trust Wallet” — TON’s key-derivation path diverges from the BIP-39 standard most other chains share, so a mnemonic isn’t portable between wallet implementations the way it is on Ethereum or Bitcoin.
Underneath all of this sits TON’s storage format: every piece of on-chain data is a cell in a structure called a Bag of Cells, where “each cell holds up to 1023 bits of data and up to 4 references to other cells,” as Volodin describes it. An API abstracts this away for basic balance and transaction queries, but anything involving raw contract data or custom message construction eventually runs into cell serialization directly.
Types of TON APIs Available to Developers
| Interface | What it provides | Best fit |
|---|---|---|
| Liteserver / ADNL | Direct, cryptographically provable chain access | Trust-minimized applications, custom node operators |
| Toncenter API v2 | Simple balance, transaction, and contract-query methods | Lightweight wallets and quick integrations |
| TON Index (v3) | Indexed queries — transaction history, Jettons, NFTs | Wallets and explorers needing historical data |
| Streaming API | Real-time updates over SSE or WebSocket | Live balance tickers, monitoring dashboards |
| NOWNodes unified API | Full node, v2 explorer, and v3 index behind one key | Teams that want all three without managing separate providers |
None of these interfaces is strictly better — a wallet showing a simple balance doesn’t need the same layer as an explorer rendering full transaction history. TON’s own documentation frames the choice around exactly this trade-off: proofs versus convenience, and simple queries versus indexed history.
How to Get Started: Integrating the TON API via NOWNodes
Getting a working connection takes four steps, and none of them require deploying any TON infrastructure yourself.
- Create an account and generate an API key from the NOWNodes dashboard.
- Choose the TON interface your feature needs — the full node API for direct reads and broadcasting, or the Index API for transaction history and Jetton data.
- Send a request to the relevant endpoint with your key in the
api-keyheader. - Parse the response and handle rate-limit and error codes before shipping the integration.
Example: Checking a Wallet’s Balance
A basic balance check against the indexed API looks like this:
bash
curl --request GET \
--url 'https://ton-index.nownodes.io/api/v3/addressInformation?address=EQBwCK26MZ1yEUR9dnSO5reQRbnN9LJcaMtAvvqSk4mbgZBx' \
--header 'api-key: YOUR_API_KEY'The response returns the balance in nanotons — TON’s smallest unit, where 1,000,000,000 nanotons equal 1 unit of the network’s native asset. Divide by 10^9 before displaying it, the same way a wallet converts wei to ETH on Ethereum.
Broadcasting a Transaction
Sending a transfer works differently from most account-based chains: the wallet signs and serializes the transaction into a BoC (Bag of Cells) locally, then submits that serialized payload through the sendBoc method rather than sending raw parameters like sender, recipient, and amount directly to the API.
That split matters for security. The API never sees a private key — it only receives an already-signed, already-serialized message — so signing has to happen in the wallet’s own code before the API is involved at all. Never pass a seed phrase or private key through any API call, request header, or logging statement; if a library asks for one to “help construct” a transaction, that’s a red flag, not a convenience.
Best Practices for TON API Integration
Test on testnet before touching mainnet funds — a malformed BoC or wrong address format fails the same way in both places, but only one of them costs real money. TON Center’s rate limits cap unauthenticated requests at 1 per second, so an API key isn’t optional for anything beyond a quick manual test.
Handle the 429 rate-limit response explicitly rather than letting a burst of balance checks silently fail. Keep the API key server-side or in a securely stored client config — never hardcode it into a published mobile app binary, where it can be extracted from the compiled package.
Validate every address format before submitting a transaction. TON supports both a raw hex-style address and a user-friendly base64 form with a built-in checksum, and mixing them up in application logic is a common source of failed or misdirected transfers.
Risks and Limitations
Coverage varies by interface, so confirm a given provider actually exposes the specific method your feature needs before building around it — not every TON API implementation supports every Toncenter v2 or v3 endpoint. Rate limits scale with plan tier, and a free-tier key that works fine in development can throttle a production wallet under real user load.
The wallet-as-smart-contract model also means a lost or misconfigured wallet contract isn’t recoverable the way a simple address might be on another chain — this is a protocol characteristic, not something any API layer can work around.
Conclusion
Integrating the TON API comes down to picking the right interface for what you’re building — a simple balance check needs far less than a full transaction-history view — and respecting the fact that TON’s wallets are smart contracts, not plain addresses. Get the address format and rate limits right, keep signing on the client side, and the actual API calls are a small piece of the work compared to understanding TON’s data model. Test everything on testnet first, and the mainnet integration is mostly a matter of swapping the endpoint.
FAQ
Do I need TON Connect if I’m only building a wallet, not a dApp?
No. TON Connect exists for dApps to request signatures from an existing wallet. A standalone wallet only needs the API methods for reading balances and broadcasting transactions.
What’s the difference between Toncenter v2 and v3?
V2 offers simple, direct balance and transaction-query methods. V3 (TON Index) adds indexed historical queries — transaction history, Jetton transfers, NFT data — that v2 can’t provide on its own.
Can I use the same seed phrase across different TON wallets?
Not reliably. TON’s key-derivation path differs from the BIP-39 standard most wallets share, so a seed phrase generated in one TON wallet can produce different keys in another.
Is the Gram/Toncoin rebrand relevant to my integration?
Only cosmetically. Addresses, balances, and API methods are unchanged — only the token’s name and ticker changed, not the network or its infrastructure.
How do I test a TON integration without risking real funds?
Use TON’s public testnet endpoints and a testnet wallet before pointing the same code at mainnet — the request format is identical, only the base URL and funds differ.
