Tonviewer — SDK & CLI Reference

📦 PyPI · 🐛 Report Bug · 💬 Community · 📣 Channel

Tonviewer — SDK & CLI Reference

A high-performance Python SDK & CLI for the TON blockchain.

Covers: wallet intelligence, transaction parsing, NFT metadata, Fragment.com resolution, and live price feeds.

🏗️ Architecture

Python SDK

Installation

pip install --upgrade Tonviewer
# or from source:
pip install git+https://github.com/DevZ44d/Tonviewer.git

`Wallet` — Wallet info & transactions

from Tonviewer import Wallet

wallet = Wallet("UQ...")      # any TON wallet address

Method	Returns	Description
`wallet.info()`	`str` (JSON)	Balance in TON + USD, status, last activity, name, icon, NFT count
`wallet.transactions(limit=1)`	`str` (JSON)	Last N transactions with hash, time, from/to, amount, comment
`wallet.action(action, limit=1)`	`str` (JSON)	Transactions filtered to a specific action type

Action type aliases accepted by wallet.action():

Pass this…	Resolves to
`sent` / `send` / `sent ton`	`Sent TON`
`receive` / `received` / `received ton`	`Received TON`
`nft` / `nft transfer`	`NFT Transfer`
`token` / `jetton` / `transfer token`	`Transfer Token`
`gas` / `relay` / `gas relay`	`Gas Relay`

wallet = Wallet("UQ...")

# Full wallet snapshot
print(wallet.info())

# Last 5 transactions
print(wallet.transactions(limit=5))

# Last 10 outgoing TON transfers
print(wallet.action(action="sent ton", limit=10))

`HashTx` — Resolve a transaction hash

from Tonviewer import HashTx

tx = HashTx(hashtx="b4566294bb20e0c22c57109f1128b903d4446d12710b3926b48c42cfc60dd097")
print(tx.get())     # → JSON string with full action breakdown

Method	Returns	Description
`tx.get()`	`str` (JSON)	All actions in the event: type, from, to, price, status, comment

`Dollers` — Live TON price

from Tonviewer.dollers import Dollers

ton_price = Dollers()._TON_USDT()   # → float, e.g. 3.24
print(f"1 TON = ${ton_price}")

Method	Returns	Description
`_TON_USDT()`	`float`	Current TON/USDT price from Binance ticker API

`NFTClient` — Async NFT fetcher

All methods must be called inside async with NFTClient() as client:.

import asyncio
from Tonviewer import NFTClient

async def main():
    async with NFTClient() as client:
        result = await client.get_nfts("@monk", fetch_floors=True)
        print(result.summary())

asyncio.run(main())

`get_nfts`

result = await client.get_nfts(user_or_wallet, *, fetch_floors=True)

Fetch all NFTs (paginated) for a @username or raw wallet address. Returns an empty NFTResult if the user has no wallet — never raises.

Parameter	Type	Default	Description
`user_or_wallet`	`str`	—	`@username` or raw TON wallet address
`fetch_floors`	`bool`	`True`	Fetch collection floor prices in TON

`get_nft_detail`

item = await client.get_nft_detail(nft_address)

Fetch full metadata for a single NFT by contract address.

Returns NFTItem or None on failure.

item = await client.get_nft_detail("EQA...abc")
print(item.name, item.image_url)
print(item.get_attribute("Rarity"))   # → "Legendary"

`get_nfts_bulk`

bulk = await client.get_nfts_bulk("@alice", "@bob", fetch_floors=False)
for user, result in bulk.items():
    print(user, result.summary())

Fetch NFTs for multiple targets concurrently. Failed targets are logged and skipped.

Parameter	Type	Default	Description
`*users_or_wallets`	`str`	—	Any mix of `@usernames` and wallet addresses
`fetch_floors`	`bool`	`False`	Fetch floor prices (off by default to keep bulk calls fast)

`NFTResult` — Portfolio container

Returned by get_nfts() and get_nfts_bulk().

Category access

result["users"]   # → List[NFTItem]  Telegram Usernames
result["gifts"]   # → List[NFTItem]  Telegram Gifts
result["etc"]     # → List[NFTItem]  Other NFTs
result.all        # → List[NFTItem]  Everything

Properties

Property	Type	Description
`result.total` / `len(result)`	`int`	Total NFT count
`result.names`	`List[str]`	Flat list of all NFT names
`result.owner`	`str \| None`	Wallet address the result belongs to
`result.is_empty`	`bool`	True when the wallet holds no NFTs

Methods

Method	Returns	Description
`result.summary()`	`str`	Human-readable portfolio summary
`result.by_collection()`	`Dict[str, List[NFTItem]]`	NFTs grouped by collection (largest first)
`result.search(query)`	`List[NFTItem]`	Case-insensitive search across name / collection / description
`result.filter_by(fn)`	`List[NFTItem]`	Filter with an arbitrary predicate
`result.has(name, exact=True)`	`bool`	Check if a specific NFT name exists
`result.top_collections(n=5)`	`List[tuple[str,int]]`	Top-N collections by count
`result.value_summary()`	`Dict[str, float]`	Estimated floor value by category (TON)

# Search
hits = result.search("chill flame")

# Custom filter
expensive = result.filter_by(lambda n: n.floor_price_ton and n.floor_price_ton > 10)

# Check ownership
if result.has("@monk"):
    print("Found!")

# Estimated portfolio value
vals = result.value_summary()  # {"users": 120.0, "gifts": 45.5, "etc": 0.0, "total": 165.5}

`NFTItem` — Single NFT

Attribute	Type	Description
`address`	`str`	Normalised NFT contract address
`name`	`str`	Display name
`collection`	`str`	Collection name
`collection_address`	`str \| None`	Collection contract address
`image_url`	`str \| None`	Best available image / preview URL
`description`	`str \| None`	Metadata description
`attributes`	`List[NFTAttribute]`	Trait list
`floor_price_ton`	`float \| None`	Collection floor in TON (if fetched)
`category`	`"users" \| "gifts" \| "etc"`	Auto-categorised

item.has_attribute("Rarity")         # → bool
item.get_attribute("Rarity")         # → "Legendary" or None

`FragmentClient` — Advanced async Fragment scraper

import asyncio
from Tonviewer import FragmentClient

async def main():
    async with FragmentClient() as client:
        result = await client.get_username("@monk")
        print(result.status, result.price_ton, result.friendly_wallet)

asyncio.run(main())

Constructor options:

FragmentClient(
    retries=3,       # HTTP retries per request
    timeout=20.0,    # Total request timeout (seconds)
    concurrency=5,   # Max simultaneous requests (semaphore)
    cache_ttl=300,   # Cache results for N seconds (0 = off)
    proxy=None,      # Optional proxy URL: "http://user:pass@host:port"
)

`get_username`

result = await client.get_username(username, *, debug=False, use_cache=True)

Fetch all available info for a username from Fragment.com.

Parameter	Type	Default	Description
`username`	`str`	—	With or without leading `@`
`debug`	`bool`	`False`	Save raw HTML to disk and print candidate elements
`use_cache`	`bool`	`True`	Return cached result if still fresh

Raises: UserNotFoundError, WalletNotFoundError, FragmentBlockedError, FragmentFetchError, FragmentParseError.

`get_usernames`

results = await client.get_usernames("@monk", "@doge", "@ton")

Fetch multiple usernames concurrently (throttled by semaphore). Failed ones are logged and skipped.

`resolve_wallet`

wallet = await client.resolve_wallet("@monk")   # → "UQA...xyz" or None

Safe non-raising variant. Returns None instead of raising when the username is not found or has no wallet.

`search`

hits = await client.search("cool")
for h in hits:
    print(h.username, h.status, h.price_ton)

Search Fragment for usernames matching the query.

`clear_cache`

client.clear_cache()           # Flush entire cache
client.clear_cache("@monk")   # Flush only this entry

`FragmentResult` — Username result

Property	Type	Description
`result.username`	`str`	Clean username without `@`
`result.status`	`str`	`"Sold"` / `"On Auction"` / `"Available"` / `"Not Found"`
`result.price_ton`	`str \| None`	Sale / auction price string
`result.friendly_wallet`	`str \| None`	UQ-prefixed owner wallet
`result.owner`	`str \| None`	Alias for `friendly_wallet`
`result.min_bid`	`str \| None`	Minimum auction bid
`result.auction_end`	`str \| None`	Auction deadline
`result.is_sold`	`bool`	Username has been sold
`result.is_auction`	`bool`	Currently on auction
`result.is_available`	`bool`	Available for purchase
`result.is_not_found`	`bool`	Not on Fragment
`result.has_wallet`	`bool`	A wallet address was resolved

result.to_dict()          # → plain dict (JSON-serialisable)
result.to_json(indent=2)  # → JSON string

`Fragment` — Simple async scraper

Lower-level scraper used internally. Returns a plain dict.

from Tonviewer.INFO.GetWallet import Fragment

async with Fragment(user="monk") as client:
    info = await client.get_info()
    print(info["status"], info["owner"]["ton_wallet"])

get_info() always returns a dict. On error, the dict contains {"error": "..."}.

Exceptions

FragmentError
├── FragmentFetchError       Network/HTTP failure after retries
├── FragmentBlockedError     Cloudflare 403 — never retried
├── FragmentParseError       Unexpected HTML structure
└── FragmentLookupError
    ├── UserNotFoundError    Username not on Fragment
    └── WalletNotFoundError  Username exists, no wallet linked

NFTError
├── NFTFetchError            TonAPI pagination failure
└── AddressResolutionError   @username → wallet resolution failed

CLI Reference

Tonviewer [OPTIONS]

Global flag

Flag	Description
`--json`	Output the raw JSON response on any command

Wallet

Flag	Arg	Description
`-w`, `--wallet`	`ADDR`	Wallet address (combine with `-i` or `-a`)
`-i`, `--info`	—	Get full wallet info
`-t`, `--transactions`	`ADDR`	Fetch latest N transactions
`-l`, `--limit`	`N`	Number of transactions/actions (default: 1)
`-a`, `--action`	`TYPE`	Filter transactions by action type
`-H`, `--hashtx`	`HASH`	Resolve a transaction hash
`-p`, `--price`	—	Print live TON/USDT price

NFT

Flag	Arg	Description
`-n`, `--nfts`	`TARGET`	Fetch all NFTs for `@username` or wallet
`--floors`	—	Also fetch collection floor prices
`--search`	`QUERY`	Search NFTs by name / collection
`--detail`	`NFT_ADDR`	Full metadata for a single NFT contract
`--bulk`	`T1 T2…`	Bulk fetch for multiple targets
`--top`	`N`	Show top-N collections
`--value`	—	Show estimated floor value by category
`--has`	`NAME`	Check if a specific NFT name exists
`-g`, `--gifts`	—	Show Gifts only (mutually exclusive)
`-u`, `--users`	—	Show Usernames only (mutually exclusive)
`-e`, `--etc`	—	Show Other NFTs only (mutually exclusive)

Fragment (simple)

Flag	Arg	Description
`-f`, `--fragment`	`USER`	Lookup single `@username` (simple scraper)
`-fm`, `--fragment-multi`	`U1 U2…`	Concurrent lookup of multiple usernames

FragmentClient (advanced)

Flag	Arg	Description
`--fragment-client`	`USER`	Advanced single lookup with full metadata
`--fragment-bulk`	`U1 U2…`	Advanced concurrent bulk lookup
`--resolve`	`USER`	Resolve `@username` → wallet address only
`--fragment-search`	`QUERY`	Search Fragment for matching usernames

CLI Examples

# Wallet info
Tonviewer -w "UQ..." -i
Tonviewer -w "UQ..." -i --json

# Transactions
Tonviewer -t "UQ..." -l 5
Tonviewer -t "UQ..." -l 5 --json

# Filtered transactions
Tonviewer -w "UQ..." -a "sent ton" -l 10
Tonviewer -w "UQ..." -a nft -l 20 --json

# Transaction hash
Tonviewer -H "b4566294bb20e0c2..."
Tonviewer -H "b4566294bb20e0c2..." --json

# Live TON price
Tonviewer -p
Tonviewer -p --json

# NFT full summary
Tonviewer -n "@monk"
Tonviewer -n "@monk" --floors --json

# NFT category filter
Tonviewer -n "@monk" -g           # gifts only
Tonviewer -n "@monk" -u --json    # usernames only, JSON

# NFT search
Tonviewer -n "@monk" --search "chill flame"

# NFT check
Tonviewer -n "@monk" --has "Chill Flame #117665" --json

# Top collections
Tonviewer -n "@monk" --top 10

# Estimated value
Tonviewer -n "@monk" --value --json

# Single NFT detail
Tonviewer --detail "EQA...abc"
Tonviewer --detail "EQA...abc" --json

# Bulk NFT
Tonviewer --bulk "@alice" "@bob" "@carol"
Tonviewer --bulk "@alice" "@bob" --json

# Fragment simple lookup
Tonviewer -f "@monk"
Tonviewer -f "@monk" --json

# Fragment multi lookup
Tonviewer -fm "@monk" "@doge" "@ton"
Tonviewer -fm "@monk" "@doge" --json

# Advanced FragmentClient
Tonviewer --fragment-client "@monk"
Tonviewer --fragment-client "@monk" --json

# Advanced bulk
Tonviewer --fragment-bulk "@monk" "@doge" "@ton"
Tonviewer --fragment-bulk "@monk" "@doge" --json

# Resolve wallet
Tonviewer --resolve "@monk"
Tonviewer --resolve "@monk" --json

# Search Fragment
Tonviewer --fragment-search "cool"
Tonviewer --fragment-search "cool" --json

Python quick-start examples

Full wallet snapshot

from Tonviewer import Wallet

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

All NFTs with floor prices

import asyncio
from Tonviewer import NFTClient

async def main():
    async with NFTClient() as client:
        result = await client.get_nfts("@monk", fetch_floors=True)
        print(result.summary())
        for name, count in result.top_collections(5):
            print(f"  {name}: {count}")
        vals = result.value_summary()
        print(f"\nEstimated total: {vals['total']} TON")

asyncio.run(main())

Fragment ownership check

import asyncio
from Tonviewer import FragmentClient

async def main():
    async with FragmentClient() as client:
        result = await client.get_username("@monk")
        if result.is_sold:
            print("Owner:", result.owner)
            print("Price:", result.price_ton)
        
        wallet = await client.resolve_wallet("@monk")   # → str or None
        results = await client.get_usernames("@a", "@b", "@c")
        
        hits = await client.search("cool")
        for h in hits:
            print(h.username, h.status, h.price_ton)

asyncio.run(main())

Auction monitor

import asyncio
from Tonviewer import FragmentClient
from Tonviewer.INFO.fragment import monitor_auction

async def on_change(result):
    print(f"Price changed → {result.price_ton}")

async def main():
    async with FragmentClient() as client:
        await monitor_auction(client, "@cool", interval=60, on_change=on_change)

asyncio.run(main())

Bulk comparison

import asyncio
from Tonviewer import NFTClient

async def main():
    async with NFTClient() as client:
        bulk = await client.get_nfts_bulk("@alice", "@bob", fetch_floors=True)
        for user, res in bulk.items():
            vals = res.value_summary()
            print(f"{user}: {len(res)} NFTs, ~{vals['total']} TON floor value")

asyncio.run(main())

Logging

import logging
logging.basicConfig(level=logging.DEBUG)
# Loggers: "nft"  "fragment"

Notes

Fragment.com may rate-limit or block IPs. Use FragmentClient(proxy="http://...") to rotate.
Use debug=True on get_username() to save raw HTML when prices parse as None.
All TON addresses are normalised to UQ-prefixed user-friendly format via tonsdk.
TonAPI floor prices are fetched concurrently and may be None for collections with no active listings.
Wallet, HashTx, and Dollers are synchronous. NFTClient, FragmentClient, and Fragment are async and must be used with async with.

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.github		.github
assets		assets
docs		docs
src/Tonviewer		src/Tonviewer
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
python-version		python-version
requirements.txt		requirements.txt

Flag	Description
`-h`, `--help`	Show help
`-v`, `--version`	Show version and links

Folders and files

Latest commit

History

Repository files navigation

Tonviewer — SDK & CLI Reference

🏗️ Architecture

Python SDK

Installation

Wallet — Wallet info & transactions

HashTx — Resolve a transaction hash

Dollers — Live TON price

NFTClient — Async NFT fetcher

get_nfts

get_nft_detail

get_nfts_bulk

NFTResult — Portfolio container

Category access

Properties

Methods

NFTItem — Single NFT

FragmentClient — Advanced async Fragment scraper

get_username

get_usernames

resolve_wallet

search

clear_cache

FragmentResult — Username result

Fragment — Simple async scraper

Exceptions

CLI Reference

Global flag

Meta

Wallet

NFT

Fragment (simple)

FragmentClient (advanced)

CLI Examples

Python quick-start examples

Full wallet snapshot

All NFTs with floor prices

Fragment ownership check

Auction monitor

Bulk comparison

Logging

Notes

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`Wallet` — Wallet info & transactions

`HashTx` — Resolve a transaction hash

`Dollers` — Live TON price

`NFTClient` — Async NFT fetcher

`get_nfts`

`get_nft_detail`

`get_nfts_bulk`

`NFTResult` — Portfolio container

`NFTItem` — Single NFT

`FragmentClient` — Advanced async Fragment scraper

`get_username`

`get_usernames`

`resolve_wallet`

`search`

`clear_cache`

`FragmentResult` — Username result

`Fragment` — Simple async scraper

Packages