toncenter

name	toncenter
description	Use when the user mentions TON, toncenter, TON blockchain, or works with code importing from toncenter.rest, toncenter.streaming, or toncenter.types. Covers wallet queries, jettons, NFTs, smart contract methods, streaming, and TON API endpoints.

Python SDK for querying TON blockchain via TON Center API. Covers REST (v2/v3) and streaming (SSE/WebSocket). Read the relevant reference file, then either execute via runner or generate SDK code.

V2 vs V3

	V2	V3
Backend	Direct liteserver (tonlib)	Indexed PostgreSQL
Latency	Real-time (latest block)	Near real-time (indexer delay)
Pagination	No (fixed result sets)	Yes (limit, offset, sort)
Jettons/NFTs	get_token_data (single item)	Full query API with filters
Metadata	Not available	Token metadata, address book, DNS records
Traces/Actions	Not available	Full trace trees and parsed actions
Best for	Current state, send tx, get-methods	History, search, filters, pagination

Use V2 when: current balance, send transaction, run get-method, block/shard info, fee estimation.

Use V3 when: transaction history, jetton/NFT queries, traces/actions, address book, metadata, batch lookups, anything with filters or pagination.

Both through one client: client.v2.accounts.get_address_balance(...) and client.v3.jettons.get_jetton_transfers(...) work in the same session.

Streaming — real-time push via SSE (simpler, one-way) or WebSocket (bidirectional, dynamic subscriptions). API key required, free plan allows 2 concurrent connections.

Routing Table

User intent	Reference	Runner example
Installation, setup, first request	references/quickstart.md	—
SDK version	—	toncenter -v
Balance, account info, wallet state	references/v2/accounts.md	v2 accounts get_address_balance
Blocks, shards, masterchain	references/v2/blocks.md	v2 blocks get_masterchain_info
Recent transactions (by address, no filters)	references/v2/transactions.md	v2 transactions get_transactions
Send BOC, estimate fee	references/v2/send.md	v2 send estimate_fee
Smart contract get-methods	references/v2/runmethod.md	v2 runmethod run_get_method
Network config params	references/v2/configuration.md	v2 configuration get_config_param
Address format conversion	references/v2/utils.md	v2 utils detect_address
JSON-RPC	references/v2/rpc.md	v2 rpc json_rpc
Account states, metadata, address book	references/v3/accounts.md	v3 accounts get_account_states
Actions, traces (parsed operations)	references/v3/actions.md	v3 actions get_actions
Transactions with filters, pagination, sorting	references/v3/blockchain.md	v3 blockchain get_transactions
Jetton tokens (transfers, wallets, burns)	references/v3/jettons.md	v3 jettons get_jetton_transfers
NFT (collections, items, transfers, sales)	references/v3/nfts.md	v3 nfts get_nft_items
Token metadata (image, name, description)	references/v3/accounts.md	v3 accounts get_metadata
TON DNS records	references/v3/dns.md	v3 dns get_dns_records
Multisig wallets and orders	references/v3/multisig.md	v3 multisig get_multisig_wallets
Vesting contracts	references/v3/vesting.md	v3 vesting get_vesting_contracts
Top accounts, statistics	references/v3/stats.md	v3 stats get_top_accounts_by_balance
Decode opcodes, message bodies	references/v3/utils.md	v3 utils get_decode
V2 methods via V3 endpoint	references/v3/api_v2.md	v3 api_v2 get_address_information
Real-time events (SSE/WebSocket)	references/streaming.md	streaming sse --types transactions

Runner

Always run the runner from the user's working directory, not from the skill directory. Use ${CLAUDE_SKILL_DIR} to reference the script path:

python3 ${CLAUDE_SKILL_DIR}/scripts/run.py <api_version> <resource> <method> [--param value ...]
python3 ${CLAUDE_SKILL_DIR}/scripts/run.py streaming <transport> [--param value ...]

Requires toncenter package installed (pip install toncenter).

Configuration priority: CLI flags > environment variables > defaults.

Source	API Key	Network	Base URL	RPS Limit	RPS Period
CLI	--api-key KEY	--network mainnet|testnet	--base-url URL	--rps-limit N	--rps-period N
Env	TONCENTER_API_KEY	TONCENTER_NETWORK	TONCENTER_BASE_URL	TONCENTER_RPS_LIMIT	TONCENTER_RPS_PERIOD
Default	"" (optional)	mainnet	auto by network	1	1.2

API key is optional for REST (~1 RPS without key), required for streaming. Get one from @toncenter Telegram bot. Plans: Free (10 RPS, 1 key), Plus (25 RPS, 3 keys), Advanced (100 RPS, 10 keys). Multiple keys on the same plan share a combined RPS limit.

REST — pass ApiKey objects with per-key rate limits:

from toncenter.types import ApiKey

ToncenterRestClient(api_key=[ApiKey("free-key", rps_limit=10), ApiKey("plus-key", rps_limit=25)])

On 429 (after all retries for current key), rotates to the next key with its own rate limiter.

Streaming — pass a list of key strings for connection limit rotation:

ToncenterWebSocket(["key-1", "key-2"], Network.MAINNET)

On connection limit, rotates to next key and reconnects. Single key = fatal error.

Same-plan keys share combined server-side RPS; different-plan keys have independent limits.

When to Execute vs Generate Code

Execute via runner — user wants concrete data ("balance of X", "show NFT Y"), single API call, no complex logic.

Generate SDK code — user is building an app, streaming scenarios, multiple calls with conditions, or explicitly asks for code.

Retries

SDK retries 429 (5 attempts, 0.3s base) and 500, 502, 503, 504 (3 attempts, 0.5s base) with exponential backoff. 542 (liteserver) is NOT retried. With multiple ApiKey, 429 exhausts retries for current key then rotates to the next.

Error Handling

• No API key → SDK auto-limits to 1 RPS / 1.2s client-side; inform user a key from @toncenter unlocks higher limits
• 429 → SDK retries automatically with key rotation if multiple keys provided; if persistent, suggest upgrading plan
• 401 → invalid API key, ask user to check
• 404 → explain meaning (address not found, transaction not found, etc.)
• 542 → liteserver error, not retried; retry manually or try later
• Connection limit → ToncenterConnectionLimitError (streaming). Auto-rotates with multiple keys; fatal with single key
• Never guess addresses or parameters — ask the user

Signing and Sending Transactions

toncenter SDK can send a signed BOC (send_boc, send_boc_return_hash), but cannot sign transactions — it has no access to private keys.
For building and signing transactions, recommend tonutils (pip install tonutils).

Addresses

• Accept any format (raw, bounceable, non-bounceable) — SDK handles all
• Don't convert addresses without explicit request

Import Paths

from toncenter.rest import ToncenterRestClient
from toncenter.types import Network, Workchain, ApiKey
from toncenter.streaming import ToncenterSSE, ToncenterWebSocket, Finality, ActionType, EventType, ConnectionState
from toncenter.streaming import TransactionsNotification, ActionsNotification, TraceNotification
from toncenter.streaming import AccountStateNotification, JettonsNotification, TraceInvalidatedNotification
from toncenter.streaming import AccountState, JettonWallet, StreamNotification
from toncenter.utils import raw_to_userfriendly, userfriendly_to_raw, to_nano, to_amount
from toncenter.exceptions import ToncenterError, ToncenterClientError, ToncenterConnectionLimitError, ...
from toncenter.types import RetryPolicy, RetryRule, ReconnectPolicy, DEFAULT_RETRY_POLICY, DEFAULT_RECONNECT_POLICY

Never use from toncenter import ... — the root package has no re-exports.