feat: Deprecate AccountBalanceQuery

Signed-off-by: aceppaluni <aceppaluni@gmail.com>

Author: aceppaluni

docs/sdk_users/running_examples.md

@@ -92,14 +92,26 @@ You can choose either syntax or even mix both styles in your projects.
 
 ### Querying Account Balance
 
+> **Deprecated:** `CryptoGetAccountBalanceQuery` is no longer supported.
+> The `CryptoGetBalance` endpoint is scheduled for removal with consensus
+> node release 77 (estimated September 2026). Use the Mirror Node REST API
+> instead, for example `GET /api/v1/accounts/{accountId}`.
+
+The following examples demonstrate the deprecated SDK call path and will
+raise an error when executed.
+
 #### Pythonic Syntax:
-```
-balance = CryptoGetAccountBalanceQuery(account_id=some_account_id).execute(client) print(f"Account balance: {balance.hbars} hbars")
+```python
+balance = CryptoGetAccountBalanceQuery(account_id=some_account_id).execute(client)
 ```
 
 #### Method Chaining:
 ```
-balance = ( CryptoGetAccountBalanceQuery() .set_account_id(some_account_id) .execute(client) ) print(f"Account balance: {balance.hbars} hbars")
+balance = (
+    CryptoGetAccountBalanceQuery()
+    .set_account_id(some_account_id)
+    .execute(client)
+)
 ```
 
 ### Creating an Account

examples/query/account_balance_query.py

@@ -1,18 +1,12 @@
 """
-
-
 Query Balance Example.
 
-This script demonstrates how to:
-1. Set up a client connection to the Hedera network
-2. Create a new account with an initial balance
-3. Query account balance
-4. Transfer HBAR between accounts
-
-Run with:
-  uv run examples/query/account_balance_query.py
-  python examples/query/account_balance_query.py
+.. deprecated::
+   CryptoGetAccountBalanceQuery is no longer supported. Use the Mirror Node
+   REST API, for example GET /api/v1/accounts/{accountId}, to retrieve
+   account balances.
 
+...
 """
 
 import sys
@@ -88,23 +82,16 @@ def create_account(client, operator_key, initial_balance=Hbar(10)):
 
 def get_balance(client, account_id):
     """
-    Query and retrieve the HBAR balance of an account.
-
-    Args:
-        client (Client): The Hiero SDK client.
-        account_id (AccountId): The account ID to query.
+    Demonstrate the deprecated account balance query.
 
-    Returns:
-        Hbar: The account's current balance in HBAR.
+    .. deprecated::
+        CryptoGetAccountBalanceQuery is no longer supported. Use the
+        Mirror Node REST API, for example GET /api/v1/accounts/{accountId}.
     """
     print(f"Querying balance for account {account_id}...")
 
     balance_query = CryptoGetAccountBalanceQuery().set_account_id(account_id)
-    balance = balance_query.execute(client)
-
-    balance_hbar = balance.hbars.to_hbars()
-    print(f"✓ Balance retrieved: {balance_hbar} hbars\n")
-    return balance_hbar
+    return balance_query.execute(client)
 
 
 def transfer_hbars(client, operator_id, operator_key, recipient_id, amount):
@@ -157,6 +144,8 @@ def main():
         print("INITIAL BALANCE CHECK")
         print("=" * 60)
         initial_balance = get_balance(client, new_account_id)
+        if initial_balance is None:
+            print(f"Use the Mirror Node REST API instead, for example GET /api/v1/accounts/{new_account_id}.")
         print(f"Initial balance of new account: {initial_balance} hbars")
         print("=" * 60 + "\n")
 

examples/query/account_balance_query_2.py

@@ -2,10 +2,10 @@
 # python examples/query/account_balance_query_2.py
 
 """
-
-Example: Use CryptoGetAccountBalanceQuery to retrieve an account's.
-
-HBAR and token balances, including minting NFTs to the account.
+.. deprecated::
+   CryptoGetAccountBalanceQuery is no longer supported. Use the Mirror Node
+   REST API, for example GET /api/v1/accounts/{accountId}, to retrieve
+   account balances.
 """
 
 import os

src/hiero_sdk_python/query/account_balance_query.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+import warnings
 from typing import Any
 
 from hiero_sdk_python.account.account_balance import AccountBalance
@@ -18,24 +19,24 @@
 
 class CryptoGetAccountBalanceQuery(Query):
     """
-    A query to retrieve the balance of a specific account from the Hedera network.
+    Query an account's balance.
 
-    This class constructs and executes a query to obtain the balance of an account,
-    including hbars and tokens.
+    .. deprecated::
+        The CryptoGetBalance endpoint is scheduled for removal with the
+        consensus node release 77 (estimated September 2026). Use the Mirror
+        Node REST API to retrieve account balances instead.
     """
 
     def __init__(
         self,
         account_id: AccountId | None = None,
         contract_id: ContractId | None = None,
     ) -> None:
-        """
-        Initializes a new instance of the CryptoGetAccountBalanceQuery class.
-
-        Args:
-            account_id (AccountId, optional): The ID of the account to retrieve the balance for.
-            contract_id (ContractId, optional): The ID of the contract to retrieve the balance for.
-        """
+        warnings.warn(
+            "Deprecated: AccountBalanceQuery will stop working when the Hedera network removes the CryptoGetBalance endpoint (estimated September 2026, consensus node release 77). Use the mirror node REST API to retrieve account balances.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__()
         self.account_id: AccountId | None = None
         self.contract_id: ContractId | None = None
@@ -133,25 +134,20 @@ def _get_method(self, channel: _Channel) -> _Method:
 
     def execute(self, client: Client, timeout: int | float | None = None) -> AccountBalance:
         """
-        Executes the account balance query.
-
-        This function delegates the core logic to `_execute()`, and may propagate exceptions raised by it.
+        Execute the account balance query.
 
-        Sends the query to the Hedera network and processes the response
-        to return an AccountBalance object.
-
-        Args:
-            client (Client): The client instance to use for execution
-            timeout (Optional[Union[int, float]]): The total execution timeout (in seconds) for this execution.
-
-        Returns:
-            AccountBalance: The account balance from the network
+        .. deprecated::
+            The CryptoGetBalance endpoint is scheduled for removal with the
+            consensus node release 77 (estimated September 2026). Use the Mirror
+            Node REST API to retrieve account balances instead.
 
         Raises:
-            PrecheckError: If the query fails with a non-retryable error
-            MaxAttemptsError: If the query fails after the maximum number of attempts
-            ReceiptStatusError: If the query fails with a receipt status error
+            RuntimeError: Always, because the AccountBalanceQuery is no longer
+                supported.
         """
+        raise RuntimeError(
+            "Error: AccountBalanceQuery is no longer supported. Use the mirror node REST API to retrieve account balances."
+        )
         self._before_execute(client)
         response = self._execute(client, timeout)
 

tck/handlers/account.py

@@ -266,7 +266,10 @@ def delete_account(params: DeleteAccountParams) -> DeleteAccountResponse:
 
 @rpc_method("getAccountBalance")
 def get_account_balance(params: GetAccountBalanceParams) -> GetAccountBalanceResponse:
-    """Get account balance for an account."""
+    """Get account balance for an account.
+
+    Deprecated: use the Mirror Node REST API instead.
+    """
     client = get_client(params.sessionId)
 
     query = CryptoGetAccountBalanceQuery().set_grpc_deadline(DEFAULT_GRPC_TIMEOUT)
@@ -276,7 +279,14 @@ def get_account_balance(params: GetAccountBalanceParams) -> GetAccountBalanceRes
     if params.contractId is not None:
         query.set_contract_id(ContractId.from_string(params.contractId))
 
-    account_balance = query.execute(client)
+    try:
+        account_balance = query.execute(client)
+    except RuntimeError as exc:
+        raise RuntimeError(
+            "Error: AccountBalanceQuery is no longer supported. "
+            "Use the mirror node REST API to retrieve account balances."
+        ) from exc
+
     return map_account_balance_response(account_balance)