[TEP-137] Enhancing Jetton Wallets: Introducing Onchain Balance Queries


The Jetton Wallet Balance Query proposal, identified as TEP-137, is a significant stride toward enhancing the functionality of Jetton wallets within the TON ecosystem. Spearheaded by Ken of Microcosm Labs, this proposal, currently in draft status, aims to introduce a mandatory onchain get_balance handler to standard Jetton wallets. This document outlines the motivation, specifications, and implications of adopting such a feature.


The primary incentive behind this proposal is to enable smart contracts to query the balance of a Jetton wallet directly on the blockchain. This capability is particularly useful in scenarios where a smart contract needs to ascertain the minimum amount of Jetton tokens it holds, under the assurance that no outbound transfers will occur in the interim between the balance query and the response. This addition promises to streamline interactions and increase efficiency in smart contract operations.

Implementation Guide

Specification Overview

Jetton wallets will need to accommodate a new message type, get_balance#312493a5, which requests the current balance. This message should carry a TON amount sufficient to cover the gas fees associated with processing and replying to the query, specifically more than 0.0061 TON under current basechain settings.

Response Handling

Upon receipt of a get_balance message that meets the gas fee requirement, the Jetton wallet is expected to reply with a get_balance_response#41cb4e49, detailing the wallet’s current balance. This response is critical for enabling smart contracts and other entities to make informed decisions based on the wallet’s token holdings.

Existing Contracts Compatibility

It’s noteworthy that existing Jetton contracts, developed prior to the introduction of this standard, will not support this new functionality. As such, new applications leveraging this feature must incorporate logic to handle both compliant and non-compliant Jetton contracts.

Technical Details

The proposal specifies the TL-B Schema for the new messages, ensuring clarity and consistency in implementation. The precise formatting and tagging of these messages are delineated in the proposal document, providing a straightforward path for developers to integrate this functionality into new Jetton wallets.

Drawbacks and Considerations

Implementing this standard will necessitate adjustments in new applications to accommodate existing Jetton contracts that do not support onchain balance queries. Moreover, the introduction of this feature adds complexity to the Jetton wallet contract’s operation, a factor that developers must consider.


TEP-137 proposes a valuable enhancement to the Jetton wallet interface by enabling onchain balance queries. This feature aligns with token standards from other blockchain ecosystems and fills a functional gap in the TON ecosystem. While its adoption requires careful implementation to address compatibility with existing contracts, the benefits of increased operational clarity and efficiency are substantial. As the TON community continues to evolve, proposals like TEP-137 play a crucial role in expanding the blockchain’s capabilities and usability.