v2.1.0

What's Changed

• Move tonconnect to standalone package
• Remove pydantic, use dataclasses for all models
• Switch to ton-core — typed and annotated fork of pytoniq-core
• Remove local contract schemas, use ton-core definitions
• Support keyless API access with default rate limits
• Switch Tonapi run_get_method to POST with typed stack args
• Improve error diagnostics and structured exception hierarchy
• Fix LiteBalancer failover timeout on dead servers
• Enforce ruff and mypy strict across the project
• Add DHT monitor to status tooling, update CLI
• Add integration and unit test suite
• Add Mintlify docs skeleton

Full Changelog: v2.0.5...v2.1.0

v2.0.5

What's Changed

• Add SeqnoGuard to ensure seqno advances between wallet sends
• Add get_transactions and run_get_method to BaseContract
• Resolve jetton wallet address from master in gasless transfer
• Add original error details to BalancerError failover message

Full Changelog: v2.0.4...v2.0.5

v2.0.4

What's Changed

• Fix Address encoding to use tvm.Slice in Toncenter stack codec
• Add resume methods for pending connect and request in TonConnect
• Fix TonConnect compatibility with tonhub

Full Changelog: v2.0.3...v2.0.4

v2.0.3

What's Changed

• Add gasless jetton transfer support for WalletV5 via Tonapi relay
• Add serialization helpers to base MessageAny class
• Add AUTH_SIGNED_INTERNAL op code

Full Changelog: v2.0.1...v2.0.3

v2.0.1

What's Changed

• Add tetra support (TonapiClient only, WalletV5 subwallet ID uses MAINNET on Tetra)
• Add NetworkNotSupportedError for providers without a default for the requested network
• Add SignatureDomain type with L2 domain-prefixed signing
• Remove hardcoded network defaults from client constructors
• Fix incorrect network resolution in WalletV5R1.state_data
• Fix block lookup validation in status monitor
• Add UTF-8 encoding fallback for CLI

Full Changelog: v2.0.0...v2.0.1

v2.0.0

tonutils 2.0 Release Notes

Major release with extensive architectural refactoring, new client infrastructure.

Migration from the previous version is non-trivial. The previous branch remains available:

pip install "tonutils<2.0"

Moderate support for the previous version is planned, but the main focus is v2.0 and above.

Examples

Practical examples for all modules are located in the examples/ folder.

Breaking Changes

Unit of measurement — nanotons

• All amount parameters now accept and return nanotons instead of TON
• to_nano() — convert from TON, to_amount() — convert back

Wallet send methods return ExternalMessage

• An ExternalMessage object is returned instead of a hash string
• Hash — .normalized_hash, BOC — .as_hex and .as_b64

TonConnect is incompatible with the previous version

• The module has been fully rewritten using Pydantic v2
• Constructor signatures, event system, sessions and storage interface have all changed

pytoniq dependency removed

• LiteserverClient has been replaced by native LiteClient and LiteBalancer
• If you were using LiteserverClient — migration is required
• Only aiohttp, pytoniq-core, pydantic remain

Changes

LiteClient — native ADNL/TCP client

• Support for rps_limit, retry_policy
• Instantiation via from_config() and from_network_config()

LiteBalancer — lite-server pool balancer

• Automatic failover between servers
• Picks the best server by masterchain seqno and RTT
• Exponential-backoff cooldown and background health-check

RetryPolicy — retry policies

• Available for both ADNL and HTTP clients
• Flexible configuration for errors, rate limits and timeouts
• Built-in policies: DEFAULT_ADNL_RETRY_POLICY and DEFAULT_HTTP_RETRY_POLICY

BaseContract — extended contract interface

• New construction methods: from_address(), from_state_init(), from_code_and_data(), from_data()
• Added refresh() to reload state from the network
• Property accessors for contract state data in most wrappers

Wallets — new contracts and interface

• Added missing WalletV1R1/R2/R3, WalletV5Beta
• Typed configs for all versions, passed at wallet creation
• Typed params for all versions, passed at send time
• Added build_external_message() — build and sign a message without sending to the network

CLI

• tonutils --version — current library version
• tonutils status [--network] [--config] [--rps] — lite-server availability monitoring

TonConnect

• Added from_connection() to restore a connector from a saved session
• Reuse an active connection across processes without re-authorization

...along with a number of other improvements and fixes across the library.

Before using in production

• Carefully review your code against the new API
• Test your logic on testnet before sending transactions on mainnet
• Do not use real funds until correct operation is confirmed

Found a bug — open an Issue or Pull Request. Let's make the library better together.

v0.5.7

What's Changed

• add tuple support to run_get_method parser #63

New Contributors

• @therenovatio made their first contribution in #63

Full Changelog: v0.5.6...v0.5.7

v2.0.1b2

Release Notes — v2.0.1b2

Beta version 2.0.1b2 of the tonutils library, based on a new architecture.
The project has been fully restructured compared to previous versions.

Installation

This version is published as a pre-release.

pip install --pre tonutils

Key Changes

Core Types and Units

• Switched to nanoton as the base unit of value.

• Introduced standardized core TON entities:

  • network identifiers (mainnet / testnet),
  • workchain identifiers (basechain / masterchain),
  • auxiliary enums and types.

• Improved API type safety and consistency.

ADNL / LiteServer

• Added native AdnlClient and AdnlBalancer.

• Built-in support for:

  • rate limit handling,
  • configurable RPS,
  • automatic retries for common errors (including block not in db).

HTTP Clients and Balancer

• Added ChainstackHttpClient.

• Implemented HttpBalancer:

  • supports multiple providers (Toncenter, TonAPI, etc.),
  • per-client rate limits and RPS configuration,
  • improved fault tolerance.

Contract Wrappers and Utilities

• Refactored contract wrappers and base classes.
• Improved separation of TL-B schemas and get-methods.
• Enhanced type annotations.

Wallet wrappers:

• Added wallet configuration models:

  • initialization configuration,
  • transaction sending parameters.

• All transfer methods now return ExternalMessage instead of a transaction hash:

  • provides helper methods (normalized_hash, as_b64, etc.).

• Added build_external_message:

  • builds and signs an external message without sending,
  • intended for emulation and offline usage.

Additional wrappers and utilities:

• Implemented wrappers for:

  • Vanity (github.com/ton-org/vanity),
  • TON DNS,
  • Telegram usernames and gifts.

• Added and improved utilities:

  • encrypt / decrypt for encrypted comments,
  • hash utilities,
  • TON DNS record parsers and helper methods.

• And much more.

Examples

• Usage examples are available in examples/.

Feedback

This is a beta release. Feedback and testing are welcome.

v0.5.6

What's Changed

• Added one-session support to clients. by @lg1447 in #62

New Contributors

• @lg1447 made their first contribution in #62

Full Changelog: v0.5.5...v0.5.6

v0.5.5

What's Changed

• fix: get router v1 while handling exception by @taiakindaniil in #61

New Contributors

• @taiakindaniil made their first contribution in #61

Full Changelog: v0.5.4...v0.5.5