# TON Center Python SDK > Python SDK for the TON Center API — read blockchain data, query smart contracts, send transactions, and subscribe to real-time events over SSE and WebSocket. Python 3.10+, runtime deps: aiohttp 3.9+, pydantic 2.4+. Install: `pip install toncenter`. API key is optional for REST (~1 RPS without key), required for streaming. Get a key from the [@toncenter](https://t.me/toncenter) Telegram bot. Networks: `Network.MAINNET` (toncenter.com), `Network.TESTNET` (testnet.toncenter.com). The SDK has three transports: - **REST V2** — direct liteserver queries via tonlib. Exact, real-time data. No pagination. Best for: current account state, sending transactions, running smart contract get-methods. - **REST V3** — indexed PostgreSQL database. Pagination, filters, time ranges. Best for: historical queries, actions/traces, Jetton/NFT analytics, batch lookups. - **Streaming** — real-time subscriptions via SSE (simpler, single POST) or WebSocket (bidirectional, dynamic subscribe/unsubscribe). Both transports multiplex all subscriptions over a single connection. Client: `ToncenterRestClient` (async context manager) exposes `client.v2` and `client.v3` resource groups. Streaming: `ToncenterSSE` and `ToncenterWebSocket` with decorator-based handler registration (`@client.on_transactions()`, `@client.on_actions()`, etc.) and finality filtering. Automatic retries with exponential backoff for 429/5xx. Client-side rate limiter via `rps_limit`. Import paths: ```python from toncenter.rest import ToncenterRestClient from toncenter.types import Network, Workchain, RetryPolicy, RetryRule, ReconnectPolicy from toncenter.streaming import ToncenterSSE, ToncenterWebSocket, Finality, ActionType, EventType from toncenter.utils import raw_to_userfriendly, userfriendly_to_raw, to_nano, to_amount from toncenter.exceptions import ToncenterError ``` ## Docs - [Overview](https://toncenter.ness.su/index): Installation, quick start, networks, API key plans. - [Reference](https://toncenter.ness.su/reference): Client configuration, sessions, retries, utilities, error handling. ## API V2 Direct liteserver queries — real-time account state, blocks, transactions, contract execution. - [API V2 Overview](https://toncenter.ness.su/api_v2/overview): Resource groups, SDK usage, endpoints. - [Get Address Information](https://toncenter.ness.su/api_v2/get_address_information_get): Full account state including balance, code, and data. - [Get Extended Address Information](https://toncenter.ness.su/api_v2/get_extended_address_information_get): Extended account state with last transaction info. - [Get Wallet Information](https://toncenter.ness.su/api_v2/get_wallet_information_get): Wallet-specific state — type, seqno, balance. - [Get Address Balance](https://toncenter.ness.su/api_v2/get_address_balance_get): Account balance in nanotons. - [Get Address State](https://toncenter.ness.su/api_v2/get_address_state_get): Account status — active, uninitialized, or frozen. - [Get Token Data](https://toncenter.ness.su/api_v2/get_token_data_get): Jetton/NFT token metadata from on-chain. - [Get Masterchain Info](https://toncenter.ness.su/api_v2/get_masterchain_info_get): Current masterchain block and state. - [Get Masterchain Block Signatures](https://toncenter.ness.su/api_v2/get_masterchain_block_signatures_get): Validator signatures for a masterchain block. - [Get Shard Block Proof](https://toncenter.ness.su/api_v2/get_shard_block_proof_get): Merkle proof for a shard block. - [Get Consensus Block](https://toncenter.ness.su/api_v2/get_consensus_block_get): Latest consensus block info. - [Lookup Block](https://toncenter.ness.su/api_v2/lookup_block_get): Find a block by workchain, shard, and seqno or time. - [Get Shards](https://toncenter.ness.su/api_v2/get_shards_get): Shard configuration at a given masterchain block. - [Get Block Header](https://toncenter.ness.su/api_v2/get_block_header_get): Block header with metadata. - [Get Out Msg Queue Size](https://toncenter.ness.su/api_v2/get_out_msg_queue_size_get): Outbound message queue size. - [Get Block Transactions](https://toncenter.ness.su/api_v2/get_block_transactions_get): Transaction IDs in a block. - [Get Block Transactions Ext](https://toncenter.ness.su/api_v2/get_block_transactions_ext_get): Full transaction data in a block. - [Get Transactions](https://toncenter.ness.su/api_v2/get_transactions_get): Transaction history for an address. - [Get Transactions Std](https://toncenter.ness.su/api_v2/get_transactions_std_get): Transaction history with standardized addresses. - [Try Locate Tx](https://toncenter.ness.su/api_v2/try_locate_tx_get): Locate a transaction by address and logical time. - [Try Locate Result Tx](https://toncenter.ness.su/api_v2/try_locate_result_tx_get): Locate the result transaction of an outbound message. - [Try Locate Source Tx](https://toncenter.ness.su/api_v2/try_locate_source_tx_get): Locate the source transaction of an inbound message. - [Get Config Param](https://toncenter.ness.su/api_v2/get_config_param_get): Single network configuration parameter. - [Get Config All](https://toncenter.ness.su/api_v2/get_config_all_get): Full network configuration. - [Get Libraries](https://toncenter.ness.su/api_v2/get_libraries_get): TVM library cells by hash. - [Run Get Method](https://toncenter.ness.su/api_v2/run_get_method_post): Execute a smart contract get-method. - [Run Get Method Std](https://toncenter.ness.su/api_v2/run_get_method_std_post): Execute a get-method with standardized address output. - [Send Boc](https://toncenter.ness.su/api_v2/send_boc_post): Send a signed serialized BOC to the network. - [Send Boc Return Hash](https://toncenter.ness.su/api_v2/send_boc_return_hash_post): Send a signed BOC and return its hash. - [Estimate Fee](https://toncenter.ness.su/api_v2/estimate_fee_post): Estimate transaction fees before sending. - [Detect Address](https://toncenter.ness.su/api_v2/detect_address_get): Detect address format and return all forms. - [Detect Hash](https://toncenter.ness.su/api_v2/detect_hash_get): Detect encoding of a hash string. - [Pack Address](https://toncenter.ness.su/api_v2/pack_address_get): Convert raw address to user-friendly format. - [Unpack Address](https://toncenter.ness.su/api_v2/unpack_address_get): Convert user-friendly address to raw format. - [Json Rpc](https://toncenter.ness.su/api_v2/json_rpc_post): JSON-RPC interface for all V2 methods. ## API V3 Indexed database queries — historical data, traces, Jettons, NFTs, batch lookups. - [API V3 Overview](https://toncenter.ness.su/api_v3/overview): Resource groups, SDK usage, endpoints. - [Get Account States](https://toncenter.ness.su/api_v3/account_states_get): Historical account states with filters. - [Get Address Book](https://toncenter.ness.su/api_v3/address_book_get): Address book entries for known contracts. - [Get Metadata](https://toncenter.ness.su/api_v3/metadata_get): On-chain metadata for accounts. - [Get Wallet States](https://toncenter.ness.su/api_v3/wallet_states_get): Wallet states with seqno and balance history. - [Get Actions](https://toncenter.ness.su/api_v3/actions_get): Parsed high-level actions (transfers, swaps, etc.). - [Get Pending Actions](https://toncenter.ness.su/api_v3/pending_actions_get): Actions not yet finalized. - [Get Pending Traces](https://toncenter.ness.su/api_v3/pending_traces_get): Traces not yet finalized. - [Get Traces](https://toncenter.ness.su/api_v3/traces_get): Full execution traces with transaction trees. - [Get Masterchain Info](https://toncenter.ness.su/api_v3/masterchain_info_get): Current masterchain state from indexed database. - [Get Blocks](https://toncenter.ness.su/api_v3/blocks_get): Block data with filters and pagination. - [Get Masterchain Block Shards](https://toncenter.ness.su/api_v3/masterchain_block_shards_get): Shards at a given masterchain block. - [Get Masterchain Block Shard State](https://toncenter.ness.su/api_v3/masterchain_block_shard_state_get): Shard state at a given masterchain block. - [Get Transactions](https://toncenter.ness.su/api_v3/transactions_get): Transactions with filters, pagination, and sorting. - [Get Transactions By Masterchain Block](https://toncenter.ness.su/api_v3/transactions_by_masterchain_block_get): All transactions in a masterchain block. - [Get Transactions By Message](https://toncenter.ness.su/api_v3/transactions_by_message_get): Transactions linked to a specific message. - [Get Adjacent Transactions](https://toncenter.ness.su/api_v3/adjacent_transactions_get): Previous and next transactions for an account. - [Get Messages](https://toncenter.ness.su/api_v3/messages_get): Messages with filters and pagination. - [Get Pending Transactions](https://toncenter.ness.su/api_v3/pending_transactions_get): Transactions not yet finalized. - [Get Jetton Masters](https://toncenter.ness.su/api_v3/jetton_masters_get): Jetton master contracts with metadata. - [Get Jetton Wallets](https://toncenter.ness.su/api_v3/jetton_wallets_get): Jetton wallet balances for addresses. - [Get Jetton Transfers](https://toncenter.ness.su/api_v3/jetton_transfers_get): Jetton transfer history with filters. - [Get Jetton Burns](https://toncenter.ness.su/api_v3/jetton_burns_get): Jetton burn events. - [Get NFT Collections](https://toncenter.ness.su/api_v3/nft_collections_get): NFT collection contracts with metadata. - [Get NFT Items](https://toncenter.ness.su/api_v3/nft_items_get): Individual NFT items with ownership and metadata. - [Get NFT Sales](https://toncenter.ness.su/api_v3/nft_sales_get): Active NFT sale contracts. - [Get NFT Transfers](https://toncenter.ness.su/api_v3/nft_transfers_get): NFT transfer history. - [Get DNS Records](https://toncenter.ness.su/api_v3/dns_records_get): TON DNS records for a domain. - [Get Multisig Wallets](https://toncenter.ness.su/api_v3/multisig_wallets_get): Multisig wallet contracts. - [Get Multisig Orders](https://toncenter.ness.su/api_v3/multisig_orders_get): Pending multisig orders. - [Get Vesting Contracts](https://toncenter.ness.su/api_v3/vesting_get): Vesting contract states. - [Get Top Accounts By Balance](https://toncenter.ness.su/api_v3/top_accounts_by_balance_get): Accounts ranked by balance. - [Get Decode](https://toncenter.ness.su/api_v3/decode_get): Decode opcode or message body (GET). - [Post Decode](https://toncenter.ness.su/api_v3/decode_post): Decode opcode or message body (POST). - [Get Address Information](https://toncenter.ness.su/api_v3/address_information_get): V2-style address info via V3 endpoint. - [Get Wallet Information](https://toncenter.ness.su/api_v3/wallet_information_get): V2-style wallet info via V3 endpoint. - [Estimate Fee](https://toncenter.ness.su/api_v3/estimate_fee_post): V2-style fee estimation via V3 endpoint. - [Send Message](https://toncenter.ness.su/api_v3/message_post): Send a signed BOC via V3 endpoint. - [Run Get Method](https://toncenter.ness.su/api_v3/run_get_method_post): Execute a smart contract get-method via V3 endpoint. ## Streaming Real-time blockchain events over SSE and WebSocket. - [Streaming Overview](https://toncenter.ness.su/streaming/overview): SSE and WebSocket transports, endpoints, SDK usage. - [Client](https://toncenter.ness.su/streaming/client): Constructor parameters, start, and stop methods. - [Handlers](https://toncenter.ness.su/streaming/handlers): Decorator API for registering event handlers with finality filtering. - [Events](https://toncenter.ness.su/streaming/events): Finality levels, notification models, and action types. - [Connection](https://toncenter.ness.su/streaming/connection): Connection state, reconnect policy, dynamic subscription management. ## OpenAPI Specifications - [V2 OpenAPI Spec](https://toncenter.ness.su/openapi/v2.yaml): Full OpenAPI 3.1 specification for V2 REST API. - [V3 OpenAPI Spec](https://toncenter.ness.su/openapi/v3.yaml): Full OpenAPI 3.1 specification for V3 REST API. ## AI Plugin - [Claude Code Plugin](https://github.com/nessshon/toncenter/tree/main/skills/toncenter): Install with `/plugin marketplace add nessshon/claude-plugins` then `/plugin install toncenter@nessshon-plugins`. Routing table, CLI runner for executing SDK methods, and per-resource API references for code generation. ## Optional - [Source Code](https://github.com/nessshon/toncenter): GitHub repository. - [PyPI](https://pypi.org/project/toncenter/): Package registry — `pip install toncenter`.