Skip to main content

Documentation Index

Fetch the complete documentation index at: https://toncenter.ness.su/llms.txt

Use this file to discover all available pages before exploring further.

Query TON blockchain data through the REST API. The SDK exposes two API versions via a single client — V2 for direct liteserver access and V3 for indexed data.
API key is optional — without a key, requests are throttled to ~1 RPS. Get a key from the @toncenter bot.

Quick Example

import asyncio

from toncenter.rest import ToncenterRestClient
from toncenter.types import Network
from toncenter.utils import to_amount


async def main() -> None:
    async with ToncenterRestClient(network=Network.MAINNET) as client:
        # V2 — current account state from liteserver
        info = await client.v2.accounts.get_address_information(
            "EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2"
        )
        print(f"Balance: {to_amount(int(info.balance))} TON")

        # V3 — indexed jetton wallets
        jettons = await client.v3.jettons.get_jetton_wallets(
            owner_address=["EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2"]
        )
        for jw in jettons.jetton_wallets or []:
            print(f"Jetton: {jw.jetton}{jw.balance}")


if __name__ == "__main__":
    asyncio.run(main())

Networks

NetworkEnum valueBase URL
MainnetNetwork.MAINNEThttps://toncenter.com
TestnetNetwork.TESTNEThttps://testnet.toncenter.com

V2 or V3

They query the same blockchain but serve different purposes.
API V2API V3
BackendDirect liteserver queries via tonlibIndexed PostgreSQL database
LatencyReal-time (latest block)Near real-time (indexer delay)
Best forCurrent state, sending transactions, get-methodsHistorical data, search, filters, pagination
PaginationNo (fixed result sets)Yes (limit, offset, sort)
Jettons/NFTsSingle item via get-methodFull query API with filters
Traces/ActionsNot availableFull trace trees and parsed actions
MetadataNot availableToken metadata, address book, DNS records
Use V2 when you need the latest account state, want to send a transaction, run a smart contract get-method, or work with blocks and shards. Use V3 when you need historical transactions, Jetton/NFT analytics, address book lookups, action traces, or paginated batch queries.