v2.0.0

pytonapi 2.0 Release Notes

Major release with full architectural refactoring, new modular client infrastructure, streaming and webhook support.

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

pip install "pytonapi<2.0"

Examples

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

Breaking Changes

Module structure — full reorganization

• pytonapi/methods/ and pytonapi/schema/ have been removed
• REST resources moved to pytonapi/rest/resources/, models to pytonapi/rest/models/
• Entry point changed: Tonapi → TonapiRestClient

Client lifecycle — explicit session management

• create_session() / close_session() instead of implicit lazy initialization
• Context manager supported: async with TonapiRestClient(...) as tonapi:
• External session can be passed via session= parameter

Models — auto-generated from OpenAPI

• All Pydantic models regenerated from the official TON API spec
• Method .to_raw(), .to_amount() removed from models — use utility functions instead
• Address fields use plain str, not custom types

Utility functions

• raw_to_userfriendly(), userfriendly_to_raw() — address conversion
• to_nano(), to_amount() — amount conversion with Decimal precision

Changes

TonapiRestClient — async REST client

• Built on aiohttp with configurable timeout, headers, and cookies
• Rate limiting via rps_limit / rps_period (sliding-window algorithm)
• 18 resource groups: accounts, blockchain, jettons, nft, dns, staking, and more

RetryPolicy — retry policies

• Configurable per HTTP status code (429, 5xx)
• Exponential backoff with base_delay, max_delay, backoff_factor
• Built-in defaults: DEFAULT_RETRY_POLICY

Streaming — SSE and WebSocket transports

• TonapiStreaming client with .sse and .ws properties
• Subscribe to transactions, blocks, traces, and mempool
• Automatic reconnection with configurable ReconnectPolicy
• Graceful shutdown via asyncio.Event

Webhooks — push notifications

• TonapiWebhookClient — HTTP CRUD for webhook management
• TonapiWebhookDispatcher — event routing with decorator-based handler registration
• Four event types: account_tx, mempool_msg, opcode_msg, new_contracts
• Per-path token verification, dependency injection, sync/async handlers
• Ready-made examples for FastAPI and aiohttp

Codegen — code generation from OpenAPI spec

• python -m codegen generates models, resources, mixin, and test scaffolds
• Jinja2 templates, configurable method name overrides
• Fixtures file for manual test data — not overwritten by codegen

Before using in production

• Carefully review your code against the new API
• Test your logic on testnet before switching to mainnet

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

v0.5.0

What's Changed

• Added new methods and create test for them by @domikedos in #44

New Contributors

• @domikedos made their first contribution in #44

Full Changelog: v0.4.9...v0.5.0

v0.4.9

What's Changed

• Added methods:

  • /v2/wallet/{account_id} — retrieving wallet information.
  • /v2/accounts/{account_id}/extra-currency/{currency_id}/history — fetch history for extra currencies.
  • /v2/nfts/collections/_bulk — bulk retrieval of NFT collections.
  • /v2/jettons/_bulk — bulk retrieval of Jetton data.
  • /v2/extra-currency/{currency_id} — get extra currency info by id.

• Removed methods:

  • /v2/wallet/backup — removed.
  • All inscriptions methods — removed as part of API simplification.

• Refactored code:

  • Enhanced schema with additional field annotations and improved models. #43.
  • Updated dependencies: aiohttp, pydantic.

Full Changelog: v0.4.8...v0.4.9

v0.4.8

What's Changed

• Schema Update: Added missing fields to traces models.

Full Changelog: v0.4.7...v0.4.8

v0.4.7

What's Changed

• Dependency Update: Changed aiohttp requirement to >=3.9.0,<3.12 and pydantic to >=2.4.1,<2.11 for improved compatibility.

Full Changelog: v0.4.6...v0.4.7

v0.4.6

What's Changed

• Fix for the bug: AsyncTonapiClientBase initialization parameters were not used in all methods by @Stanislav-Povolotsky in #41
• Add sort_order param to blockchain method: get_account_transactions by @VasyaIT in #42

New Contributors

• @Stanislav-Povolotsky made their first contribution in #41
• @VasyaIT made their first contribution in #42

Full Changelog: v0.4.5...v0.4.6

v0.4.5

What's Changed

• Refactored code: Replaced httpx with aiohttp to enhance performance.
• Breaking change: Removed support for synchronous methods.
• Removed methods:
  • JettonsMethod.get_all_holders
  • AccountsMethod.get_all_nfts
  • NftMethod.get_all_items_by_collection_address
    These methods were removed due to issues arising from inconsistent RPS in looping operations.

Full Changelog: v0.4.4...v0.4.5

v0.4.4

What's Changed

• Add hash field to Message Model by @k0lyaka in #37

New Contributors

• @k0lyaka made their first contribution in #37

Full Changelog: v0.4.2...v0.4.4

v0.4.2

What's Changed

• Added webhook methods to the API (see Webhooks API Documentation).
• Fix currencies in v2/accounts/{account_id}/jettons by @aiexz in #30

New Contributors

• @aiexz made their first contribution in #30

Full Changelog: v0.4.1...v0.4.2

v0.4.1

What's Changed

• Updated v2/accounts/{account_id}/jettons and v2/accounts/{account_id}/jettons/{jetton_id}: added currencies and supported_extensions parameters. Use supported_extensions=["custom_payload"] to display the balance of mintless jettons (e.g., Hamster).