TON SDK

1.0.15 verified Mon Apr 27 auth: no python

Python SDK for interacting with The Open Network (TON) blockchain. Current version 1.0.15 supports wallet operations, message serialization, and contract interactions. Release cadence is irregular.

pip install tonsdk

Common errors

error AttributeError: module 'tonsdk' has no attribute 'TonClient' ↓

cause Importing from top-level module instead of submodule.

fix

Use 'from tonsdk.client import TonClient'

error requests.exceptions.ConnectionError: HTTPSConnectionPool(host='ton.org', port=443): Max retries exceeded ↓

cause Default endpoint may be unreachable or deprecated.

fix

Specify a custom endpoint when creating TonClient, e.g., config={'endpoints': ['https://toncenter.com/api/v2/jsonRPC']}

error ValueError: Invalid address format ↓

cause Address string does not start with 'EQ' or 'UQ' or missing proper format.

fix

Ensure address is a raw string in base64 format (e.g., 'EQD...'). Use Address(address_string).to_string() to validate.

Warnings

gotcha Wallet.create() prints mnemonic to stdout. In production, never log mnemonic; consider using Wallet.from_mnemonic() with a securely stored phrase. ↓

fix Use Wallet.from_mnemonic(mnemonic=your_list, version='v3r2') to restore wallet.

breaking Version 0.9.x had different import paths; code using `from tonsdk import ...` will fail with 1.0.x. ↓

fix Update imports to use submodule paths: from tonsdk.client import TonClient, etc.

gotcha TonClient.get_balance() returns string (nanoton), not integer. Arithmetic without conversion to int may cause unexpected behavior. ↓

fix Use int(balance) if needed for math.

deprecated TonClient default endpoint 'https://ton.org/...' may be deprecated; use TonCenter endpoint explicitly. ↓

fix Set config={'endpoints': ['https://toncenter.com/api/v2/jsonRPC']} when creating client.

Imports

TonClient

wrong

from tonsdk import TonClient

correct

from tonsdk.client import TonClient

TonClient is in the client submodule

Wallet

wrong

from tonsdk import Wallet

correct

from tonsdk.wallet import Wallet

Wallet class is in the wallet submodule

Address
```
from tonsdk.utils import Address
```
TransferMessage
```
from tonsdk.boc import TransferMessage
```

Quickstart

Initialize client, create wallet, check balance

from tonsdk.client import TonClient
from tonsdk.wallet import Wallet
from tonsdk.utils import to_nano

# Create a custom client (mainnet by default)
client = TonClient(config={'endpoints': ['https://toncenter.com/api/v2/jsonRPC']})

# Generate a new wallet (mnemonic is printed)
wallet, mnemonic, private_key, public_key, wallet_type = Wallet.create(mnemonics=24, randomgen=True)
print('Mnemonic:', mnemonic)
print('Wallet address:', wallet.address.to_string())

# Check balance
balance = client.get_balance(wallet.address.to_string())
print('Balance:', balance)

# Create a transfer message
# message = wallet.create_transfer_message(destination='EQD...', amount=to_nano(0.1))
# result = client.send_boc(message['message'].to_boc())
# print('Transfer sent:', result)