Tonviewer 1.3.0

TON blockchain SDK and CLI for Python

📦 PyPI · 🐛 Report a bug · 💬 Community · 📣 Channel

Tonviewer provides wallet information, parsed TONAPI events, raw TON Center v3 transactions, Jetton balances, NFT metadata, on-chain collectible gifts, Fragment username lookups, TON prices, and a command-line interface.

The SDK has two styles: the synchronous compatibility API (Wallet, HashTx) returns formatted JSON strings, while TonviewerClient exposes asynchronous services and typed Pydantic models. Feature-specific notes, output shapes, and copyable usage examples live in docs/README.md.

Install

python -m pip install --upgrade Tonviewer

Python 3.9 or newer is required. For a source checkout and contributor setup, see Installation.

Quick start

Async client

import asyncio
from tonviewer import TonviewerClient

async def main():
    async with TonviewerClient() as client:
        x = await client.fragment.get_username("yyeeye")
        wallet = await client.wallet.get_info(x.owner_wallet)
        print(wallet.balance.ton, wallet.status.value, wallet.nfts_count)

        txs = await client.wallet.get_transactions(x.owner_wallet, limit=5)
        print(txs["transactions"])

asyncio.run(main())

Synchronous compatibility API

from tonviewer import Wallet, HashTx

wallet = Wallet("UQ...")
print(wallet.info())                         # JSON string
print(wallet.transactions(limit=5))          # JSON string
print(wallet.action("sent ton", limit=5))

print(HashTx("EVENT_OR_TRANSACTION_HASH").get())

The async service methods for NFTs, gifts, Jettons, and Fragment are documented separately. Those services do not all have synchronous counterparts; see Sync and async APIs.

Feature map

Configuration, examples, errors, architecture, and the verified fix history are indexed in the documentation home.

Architecture

The diagram's editable Mermaid source is docs/architecture.mmd. See the architecture guide for provider and data-source notes.

Configure keys

API keys are optional for public endpoints, subject to the providers' limits. Use environment variables for local development rather than committing secrets:

$env:TONCENTER_API_KEY = "your-toncenter-key"
$env:TONCENTER_API_KEY_BACKUP = "your-optional-backup-key"
$env:TONAPI_KEY = "your-optional-tonapi-key"

On Linux/macOS, use export NAME="value". Network, timeout, retry, rate, cache, and proxy settings are described in Configuration.

Project documents

• Documentation home and navigation
• Installation and development setup
• Quick start and end-to-end examples
• Sync vs async API availability
• Typed output models
• Errors and troubleshooting
• Fixes and behavior notes

Scope notes

Fragment is read from its public web pages, not an official Fragment API; parsing can be affected by page changes or access restrictions. Gift discovery covers on-chain NFTs classified as collectibles, not ordinary off-chain Telegram gifts. Username NFT categories and gift classification are metadata heuristics. Review returned data before making financial or security decisions.

License and community

MIT License. See LICENSE. Questions and bug reports: GitHub Issues. Community: Telegram.