TON Blockchain

Introduction

The TON Library (TonLib) is a powerful addition to TeleBot Creator that enables seamless integration with The Open Network blockchain. With TonLib, you can create wallets, check balances, send TON, work with jettons (TON's tokens), and integrate TON Connect for user wallet connections.

Note: This is a development version of the TON Library introduced in version 4.9.0. Most bugs have been fixed and the library is stable for production use.

Getting Started

Unlike other libraries, TonLib doesn't require an import statement. It's globally available in your bot code.

# ❌ Don't use imports
# import TonLib  # This will cause an error

# ✅ Instead, use the library directly
wallet = libs.TonLib.generateWallet()

Core Functions

Wallet Management

generateWallet()

Creates a new TON wallet and returns its address and mnemonic phrase.

result = libs.TonLib.generateWallet()
address = result["address"]
mnemonics = result["mnemonics"]

setKeys(mnemonics)

Stores a mnemonic phrase for later use.

libs.TonLib.setKeys("word1 word2 ... word24")

getWalletAddress(mnemonics=None)

Retrieves the wallet address from a mnemonic phrase or from stored keys.

# Using stored keys
address = libs.TonLib.getWalletAddress()

# Or with specific mnemonics
address = libs.TonLib.getWalletAddress("word1 word2 ... word24")

TON Operations

getBalance(address, api_key=None, endpoint=None)

Checks the TON balance of an address.

balance = libs.TonLib.getBalance("EQD...")

sendTON(to_address, amount, comment=None, mnemonics=None, api_key=None, endpoint=None, is_testnet=False)

Sends TON to another address.

result = libs.TonLib.sendTON(
    to_address="EQD...",
    amount=0.1,  # In TON
    comment="Payment for service"
)

checkTONTransaction(address, api_key=None, endpoint=None, limit=10)

Gets the recent transactions for an address.

transactions = libs.TonLib.checkTONTransaction("EQD...")
for tx in transactions:
    if tx["type"] == "incoming":
        from_address = tx["from"]
        amount = tx["amount"]
        # Process the incoming transaction...

TON Connect Integration

create_ton_connect_session(user_id, expiry_seconds=86400)

Creates a TON Connect session for wallet connection.

session = libs.TonLib.create_ton_connect_session(user_id="12345")
connect_url = session["connect_url"]
# Send this URL to the user for connection

verify_ton_connect_session(session_id)

Checks if a wallet has connected to the session.

status = libs.TonLib.verify_ton_connect_session(session_id)
if status["status"] == "connected":
    wallet_address = status["wallet_address"]
    # User wallet is connected

register_ton_connect_wallet(session_id, wallet_address)

Marks a session as connected and stores the connected wallet address. Use this in your callback/handler once the user approves the connection on their wallet, so that subsequent verify_ton_connect_session calls report the wallet.

result = libs.TonLib.register_ton_connect_wallet(session_id, "EQD...")
if result["status"] == "success":
    bot.sendMessage("Wallet linked!")

Returns: A dict with status ("success" or "error"), a message, and on success the wallet_address. Errors are returned for unknown or expired sessions.

create_ton_connect_payload(callback_url, items=None, return_url=None)

Builds a raw TON Connect payload and deep link (connect_url) for custom request flows. This is the lower-level primitive used by request_ton_transaction / request_jetton_transfer; call it directly when you need to bundle custom items.

payload = libs.TonLib.create_ton_connect_payload(
    callback_url="https://your-app.com/callback",
    items=[],
    return_url="https://t.me/your_bot"
)
bot.sendMessage(f"Open: {payload['connect_url']}")

Returns: A dict with request_id, connect_url, and the raw payload.

request_ton_transaction(to_address, amount, comment=None, callback_url="", return_url=None)

Requests a TON transfer from a connected wallet.

request = libs.TonLib.request_ton_transaction(
    to_address="EQD...",
    amount=1.5,
    comment="Donation",
    callback_url="https://your-app.com/callback"
)
# Send the request["connect_url"] to the user

Jetton Operations

get_jetton_metadata(jetton_master_address, api_key=None, endpoint=None)

Retrieves information about a Jetton (token).

metadata = libs.TonLib.get_jetton_metadata("EQD...")
name = metadata["name"]
symbol = metadata["symbol"]
total_supply = metadata["total_supply"]

get_jetton_wallet_address(owner_address, jetton_master_address, api_key=None, endpoint=None)

Resolves the address of the Jetton wallet that an owner holds for a given Jetton master contract. (Each owner has a distinct Jetton wallet per token.) get_jetton_balance uses this internally, but you can call it directly when you need the wallet address itself.

jetton_wallet = libs.TonLib.get_jetton_wallet_address(
    owner_address="EQD...",
    jetton_master_address="EQD..."
)

get_jetton_balance(owner_address, jetton_master_address, api_key=None, endpoint=None)

Checks the Jetton balance of an address.

balance = libs.TonLib.get_jetton_balance(
    owner_address="EQD...",
    jetton_master_address="EQD..."
)

request_jetton_transfer(to_address, jetton_master_address, amount, comment=None, callback_url="", return_url=None)

Requests a Jetton transfer from a connected wallet.

request = libs.TonLib.request_jetton_transfer(
    to_address="EQD...",
    jetton_master_address="EQD...",
    amount=10,
    callback_url="https://your-app.com/callback"
)

Examples

Creating a Simple TON Wallet Bot

def handle_start(message):
    # Generate a new wallet
    wallet = libs.TonLib.generateWallet()
    
    # Store the mnemonics
    libs.TonLib.setKeys(wallet["mnemonics"])
    
    # Send information to the user
    bot.send_message(
        chat_id=message.chat.id,
        text=f"Your new TON wallet address:\n`{wallet['address']}`\n\n"
             f"Seed phrase (keep it safe):\n`{wallet['mnemonics']}`",
        parse_mode="Markdown"
    )

def handle_balance(message):
    # Get wallet address
    address = libs.TonLib.getWalletAddress()
    
    # Get balance
    balance = libs.TonLib.getBalance(address)
    
    # Send balance to user
    bot.send_message(
        chat_id=message.chat.id,
        text=f"Your balance: {balance} TON"
    )

TON Connect Integration Example

# Step 1: Initialize wallet connection
def handle_connect_wallet(message):
    user_id = str(message.from_user.id)
    session = libs.TonLib.create_ton_connect_session(user_id)
    
    # Store session_id for later verification
    db.set_user_data(user_id, "ton_session_id", session["session_id"])
    
    # Send connection link to user
    bot.send_message(
        chat_id=message.chat.id,
        text=f"Connect your TON wallet by opening this link:\n{session['connect_url']}"
    )

# Step 2: Check wallet connection status
def handle_check_connection(message):
    user_id = str(message.from_user.id)
    session_id = db.get_user_data(user_id, "ton_session_id")
    
    if not session_id:
        return bot.send_message(message.chat.id, "You haven't started a connection yet")
    
    status = libs.TonLib.verify_ton_connect_session(session_id)
    
    if status["status"] == "connected":
        bot.send_message(
            chat_id=message.chat.id,
            text=f"Wallet connected: {status['wallet_address']}"
        )
    else:
        bot.send_message(
            chat_id=message.chat.id,
            text="Wallet not connected yet. Try again later."
        )

Best Practices

1. Security: Never store sensitive mnemonic phrases in plain text. Consider encrypting them or using a secure key management solution.

2. Error Handling: Always wrap TON operations in try/except blocks to handle potential errors gracefully.

3. Testnet First: When developing, use the testnet (is_testnet=True) before moving to mainnet.

4. Rate Limiting: Be mindful of API request limits when checking balances or transactions frequently.

5. User Experience: Provide clear instructions and feedback to users, especially for wallet connection steps.

Limitations

• Maximum code execution time is 120 seconds

• time.sleep() function is limited to 10 seconds maximum

Further Resources

• The Open Network Documentation

• TON Connect Documentation

• TBC Libraries Documentation