feat: hbar support (#1199)

Signed-off-by: prajeeta pal <[email protected]>
Signed-off-by: prajeeta  <[email protected]>

Author: prajeeta15

CHANGELOG.md

@@ -6,9 +6,11 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 
 ## [Unreleased]
 
-
-
 ### Added
+
+- Added Hbar object support for TransferTransaction HBAR transfers:
+  - Methods now accept `Union[int, Hbar]` for amount parameters with immediate normalization to tinybars
+  - Includes comprehensive unit tests covering various Hbar units (HBAR, MICROBAR, NANOBAR, TINYBAR) and accumulation behavior with mixed `int` and `Hbar` inputs
 - Added a module-level docstring to the HBAR allowance approval example to clarify
   delegated spending behavior and key concepts. [#1202](https://github.com/hiero-ledger/hiero-sdk-python/issues/1202)
 - Added a GitHub Actions workflow to validate broken Markdown links in pull requests.
@@ -28,7 +30,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Added unit tests for `SubscriptionHandle` class covering cancellation state, thread management, and join operations.
 - Refactored `account_create_transaction_create_with_alias.py` example by splitting monolithic function into modular functions: `generate_main_and_alias_keys()`, `create_account_with_ecdsa_alias()`, `fetch_account_info()`, `print_account_summary()` (#1016)
 - Added `.github/workflows/bot-pr-auto-draft-on-changes.yml` to automatically convert PRs to draft and notify authors when reviewers request changes.
-- 
+-
 - Modularized `transfer_transaction_fungible` example by introducing `account_balance_query()` & `transfer_transaction()`.Renamed `transfer_tokens()` → `main()`
 - Phase 2 of the inactivity-unassign bot: Automatically detects stale open pull requests (no commit activity for 21+ days), comments with a helpful InactivityBot message, closes the stale PR, and unassigns the contributor from the linked issue.
 - Added `__str__()` to CustomFixedFee and updated examples and tests accordingly.
@@ -48,7 +50,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Support selecting specific node account ID(s) for queries and transactions and added `Network._get_node()` with updated execution flow (#362)
 - Add TLS support with two-stage control (`set_transport_security()` and `set_verify_certificates()`) for encrypted connections to Hedera networks. TLS is enabled by default for hosted networks (mainnet, testnet, previewnet) and disabled for local networks (solo, localhost) (#855)
 - Add PR inactivity reminder bot for stale pull requests `.github/workflows/pr-inactivity-reminder-bot.yml`
-- Add comprehensive training documentation for _Executable class `docs/sdk_developers/training/executable.md`
+- Add comprehensive training documentation for \_Executable class `docs/sdk_developers/training/executable.md`
 - Added empty `docs/maintainers/good_first_issues.md` file for maintainers to write Good First Issue guidelines (#1034)
 - Added new `.github/ISSUE_TEMPLATE/04_good_first_issue_candidate.yml` file (1068)(https://github.com/hiero-ledger/hiero-sdk-python/issues/1068)
 - Enhanced `.github/ISSUE_TEMPLATE/01_good_first_issue.yml` with welcoming message and acceptance criteria sections to guide contributors in creating quality GFIs (#1052)
@@ -57,12 +59,12 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Add support for include_children in TransactionGetReceiptQuery (#1100)(https://github.com/hiero-ledger/hiero-sdk-python/issues/1100)
 - Add new `.github/ISSUE_TEMPLATE/05_intermediate_issue.yml` file (1072)(https://github.com/hiero-ledger/hiero-sdk-python/issues/1072)
 - Add a workflow to notify the team when issues are labeled as “good first issues” or identified as candidates for that label: `bot-gfi-notify-team.yml`(#1115)
-- Added __str__ and __repr__ to AccountBalance
+- Added **str** and **repr** to AccountBalance
 - Added GitHub workflow that makes sure newly added test files follow pytest test files naming conventions (#1054)
 - Added advanced issue template for contributors `.github/ISSUE_TEMPLATE/06_advanced_issue.yml`.
 - Add new tests to `tests/unit/topic_info_query_test.py` (#1124)
 - Added `coding_token_transactions.md` for a high level overview training on how token transactions are created in the python sdk.
-- Added prompt for codeRabbit on how to review /examples ([#1180](https://github.com/hiero-ledger/hiero-sdk-python/issues/1180)) 
+- Added prompt for codeRabbit on how to review /examples ([#1180](https://github.com/hiero-ledger/hiero-sdk-python/issues/1180))
 - Add Linked Issue Enforcer to automatically close PRs without linked issues `.github/workflows/bot-linked-issue-enforcer.yml`.
 - Added support for include duplicates in get transaction receipt query (#1166)
 - Added `.github/workflows/cron-check-broken-links.yml` workflow to perform scheduled monthly Markdown link validation across the entire repository with automatic issue creation for broken links ([#1210](https://github.com/hiero-ledger/hiero-sdk-python/issues/1210))
@@ -92,21 +94,20 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Cleaned up `token_airdrop_claim_auto` example for pylint compliance (no functional changes). (#1079)
 - Formatted `examples/query` using black (#1082)(https://github.com/hiero-ledger/hiero-sdk-python/issues/1082)
 - Update team notification script and workflow for P0 issues 'p0_issues_notify_team.js'
-- Rename test files across the repository to ensure they consistently end with _test.py (#1055)
+- Rename test files across the repository to ensure they consistently end with \_test.py (#1055)
 - Cleaned up `token_airdrop_claim_signature_required` example for pylint compliance (no functional changes). (#1080)
-- Rename the file 'test_token_fee_schedule_update_transaction_e2e.py' to make it ends with _test.py as all other test files.(#1117)
+- Rename the file 'test_token_fee_schedule_update_transaction_e2e.py' to make it ends with \_test.py as all other test files.(#1117)
 - Format token examples with Black for consistent code style and improved readability (#1119)
 - Transformed `examples/tokens/custom_fee_fixed.py` to be an end-to-end example, that interacts with the Hedera network, rather than a static object demo.
-- Format token examples with Black for consistent code style and improved readability (#1119) 
-- Replaced `ResponseCode.get_name(receipt.status)` with the  `ResponseCode(receipt.status).name` across examples and integration tests for consistency. (#1136)
+- Format token examples with Black for consistent code style and improved readability (#1119)
+- Replaced `ResponseCode.get_name(receipt.status)` with the `ResponseCode(receipt.status).name` across examples and integration tests for consistency. (#1136)
 - Moved helpful references to Additional Context section and added clickable links.
 - Transformed `examples\tokens\custom_royalty_fee.py` to be an end-to-end example, that interacts with the Hedera network, rather than a static object demo.
 - Refactored `examples/tokens/custom_royalty_fee.py` by splitting monolithic function custom_royalty_fee_example() into modular functions create_royalty_fee_object(), create_token_with_fee(), verify_token_fee(), and main() to improve readability, cleaned up setup_client() (#1169)
 - Added comprehensive unit tests for Timestamp class (#1158)
 - Enhance unit and integration test review instructions for clarity and coverage `.coderabbit.yaml`.
 - Issue reminder bot now explicitly mentions assignees (e.g., `@user`) in comments. ([#1232](https://github.com/hiero-ledger/hiero-sdk-python/issues/1232))
 
-
 ### Fixed
 
 - Fix token association verification in `token_airdrop_transaction.py` to correctly check if tokens are associated by using `token_id in token_balances` instead of incorrectly displaying zero balances which was misleading (#[815])
@@ -120,7 +121,6 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Fixed `cron-check-broken-links.yml` string parsing issue in context input `dry_run` (#1235)
 - Flaky tests by disabling TLS in mock Hedera nodes in `mock_server.py`
 
-
 ### Breaking Change
 
 - Remove deprecated 'in_tinybars' parameter and update related tests `/src/hiero_sdk_python/hbar.py`, `/tests/unit/hbar_test.py` and `/src/hiero_sdk_python/tokens/custom_fixed_fee.py`.
@@ -686,4 +686,3 @@ contract_call_local_pb2.ContractLoginfo -> contract_types_pb2.ContractLoginfo
 ### Removed
 
 - N/A
-

src/hiero_sdk_python/transaction/transfer_transaction.py

@@ -2,11 +2,12 @@
 Defines TransferTransaction for transferring HBAR or tokens between accounts.
 """
 
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, List, Optional, Tuple, Union
 
 from hiero_sdk_python.account.account_id import AccountId
 from hiero_sdk_python.channels import _Channel
 from hiero_sdk_python.executable import _Method
+from hiero_sdk_python.hbar import Hbar
 from hiero_sdk_python.hapi.services import basic_types_pb2, crypto_transfer_pb2, transaction_pb2
 from hiero_sdk_python.hapi.services.schedulable_transaction_body_pb2 import (
     SchedulableTransactionBody,
@@ -29,7 +30,8 @@ def __init__(
         self,
         hbar_transfers: Optional[Dict[AccountId, int]] = None,
         token_transfers: Optional[Dict[TokenId, Dict[AccountId, int]]] = None,
-        nft_transfers: Optional[Dict[TokenId, List[Tuple[AccountId, AccountId, int, bool]]]] = None,
+        nft_transfers: Optional[Dict[TokenId,
+                                     List[Tuple[AccountId, AccountId, int, bool]]]] = None,
     ) -> None:
         """
         Initializes a new TransferTransaction instance.
@@ -59,14 +61,14 @@ def _init_hbar_transfers(self, hbar_transfers: Dict[AccountId, int]) -> None:
             self.add_hbar_transfer(account_id, amount)
 
     def _add_hbar_transfer(
-        self, account_id: AccountId, amount: int, is_approved: bool = False
+        self, account_id: AccountId, amount: Union[int, Hbar], is_approved: bool = False
     ) -> "TransferTransaction":
         """
         Internal method to add a HBAR transfer to the transaction.
 
         Args:
             account_id (AccountId): The account ID of the sender or receiver.
-            amount (int): The amount of the HBAR to transfer.
+            amount (Union[int, Hbar]): The amount of the HBAR to transfer.
             is_approved (bool, optional): Whether the transfer is approved. Defaults to False.
 
         Returns:
@@ -75,8 +77,12 @@ def _add_hbar_transfer(
         self._require_not_frozen()
         if not isinstance(account_id, AccountId):
             raise TypeError("account_id must be an AccountId instance.")
-        if not isinstance(amount, int) or amount == 0:
-            raise ValueError("Amount must be a non-zero integer.")
+        if isinstance(amount, Hbar):
+            amount = amount.to_tinybars()
+        elif not isinstance(amount, int):
+            raise TypeError("amount must be an int or Hbar instance.")
+        if amount == 0:
+            raise ValueError("Amount must be a non-zero value.")
         if not isinstance(is_approved, bool):
             raise TypeError("is_approved must be a boolean.")
 
@@ -85,16 +91,17 @@ def _add_hbar_transfer(
                 transfer.amount += amount
                 return self
 
-        self.hbar_transfers.append(HbarTransfer(account_id, amount, is_approved))
+        self.hbar_transfers.append(
+            HbarTransfer(account_id, amount, is_approved))
         return self
 
-    def add_hbar_transfer(self, account_id: AccountId, amount: int) -> "TransferTransaction":
+    def add_hbar_transfer(self, account_id: AccountId, amount: Union[int, Hbar]) -> "TransferTransaction":
         """
         Adds a HBAR transfer to the transaction.
 
         Args:
             account_id (AccountId): The account ID of the sender or receiver.
-            amount (int): The amount of the HBAR to transfer.
+            amount (Union[int, Hbar]): The amount of the HBAR to transfer.
 
         Returns:
             TransferTransaction: The current instance of the transaction for chaining.
@@ -103,14 +110,14 @@ def add_hbar_transfer(self, account_id: AccountId, amount: int) -> "TransferTran
         return self
 
     def add_approved_hbar_transfer(
-        self, account_id: AccountId, amount: int
+        self, account_id: AccountId, amount: Union[int, Hbar]
     ) -> "TransferTransaction":
         """
         Adds a HBAR transfer with approval to the transaction.
 
         Args:
             account_id (AccountId): The account ID of the sender or receiver.
-            amount (int): The amount of the HBAR to transfer.
+            amount (Union[int, Hbar]): The amount of the HBAR to transfer.
 
         Returns:
             TransferTransaction: The current instance of the transaction for chaining.
@@ -190,7 +197,8 @@ def _from_protobuf(cls, transaction_body, body_bytes: bytes, sig_map):
 
             if crypto_transfer.HasField("transfers"):
                 for account_amount in crypto_transfer.transfers.accountAmounts:
-                    account_id = AccountId._from_proto(account_amount.accountID)
+                    account_id = AccountId._from_proto(
+                        account_amount.accountID)
                     amount = account_amount.amount
                     is_approved = account_amount.is_approval
                     transaction.hbar_transfers.append(
@@ -210,17 +218,21 @@ def _from_protobuf(cls, transaction_body, body_bytes: bytes, sig_map):
                         expected_decimals = token_transfer_list.expected_decimals.value
 
                     transaction.token_transfers[token_id].append(
-                        TokenTransfer(token_id, account_id, amount, expected_decimals, is_approved)
+                        TokenTransfer(token_id, account_id, amount,
+                                      expected_decimals, is_approved)
                     )
 
                 for nft_transfer in token_transfer_list.nftTransfers:
-                    sender_id = AccountId._from_proto(nft_transfer.senderAccountID)
-                    receiver_id = AccountId._from_proto(nft_transfer.receiverAccountID)
+                    sender_id = AccountId._from_proto(
+                        nft_transfer.senderAccountID)
+                    receiver_id = AccountId._from_proto(
+                        nft_transfer.receiverAccountID)
                     serial_number = nft_transfer.serialNumber
                     is_approved = nft_transfer.is_approval
 
                     transaction.nft_transfers[token_id].append(
-                        TokenNftTransfer(token_id, sender_id, receiver_id, serial_number, is_approved)
+                        TokenNftTransfer(
+                            token_id, sender_id, receiver_id, serial_number, is_approved)
                     )
 
         return transaction

tests/integration/transfer_transaction_e2e_test.py

@@ -183,9 +183,11 @@ def test_integration_token_transfer_transaction_can_transfer_nft():
         query_transaction = CryptoGetAccountBalanceQuery(account_id)
         balance = query_transaction.execute(env.client)
 
-        # We check if the nft has transfered to the new account
-        # For now, token_balances is a map so we check it this way
-        assert balance and balance.token_balances == {token_id: serial_number}
+        assert balance is not None, "Balance query returned None"
+        assert balance.token_balances == {token_id: serial_number}, (
+            f"Expected token_balances {{{token_id}: {serial_number}}}, "
+            f"got {balance.token_balances}"
+        )
     finally:
         env.close()
 
@@ -448,3 +450,90 @@ def test_integration_transfer_transaction_approved_token_transfer():
 
     finally:
         env.close()
+
+
+@pytest.mark.integration
+def test_integration_transfer_transaction_approved_nft_transfer():
+    """Test NFT transfer with approval flag set to True."""
+    env = IntegrationTestEnv()
+
+    try:
+        new_account_private_key = PrivateKey.generate()
+        new_account_public_key = new_account_private_key.public_key()
+
+        initial_balance = Hbar(10)
+
+        account_transaction = AccountCreateTransaction(
+            key=new_account_public_key, initial_balance=initial_balance, memo="Recipient Account"
+        )
+
+        receipt = account_transaction.execute(env.client)
+
+        assert (
+            receipt.status == ResponseCode.SUCCESS
+        ), f"Account creation failed with status: {ResponseCode(receipt.status).name}"
+
+        account_id = receipt.account_id
+        assert account_id is not None
+
+        token_id = create_nft_token(env)
+        assert token_id is not None
+
+        mint_transaction = TokenMintTransaction(token_id=token_id, metadata=[b"test"])
+
+        receipt = mint_transaction.execute(env.client)
+
+        assert (
+            receipt.status == ResponseCode.SUCCESS
+        ), f"NFT mint failed with status: {ResponseCode(receipt.status).name}"
+
+        serial_number = receipt.serial_numbers[0]
+
+        nft_id = NftId(token_id, serial_number)
+
+        associate_transaction = TokenAssociateTransaction(
+            account_id=account_id, token_ids=[token_id]
+        )
+
+        associate_transaction.freeze_with(env.client)
+        associate_transaction.sign(new_account_private_key)
+        receipt = associate_transaction.execute(env.client)
+
+        assert (
+            receipt.status == ResponseCode.SUCCESS
+        ), f"NFT association failed with status: {ResponseCode(receipt.status).name}"
+
+        allowance_receipt = (
+            AccountAllowanceApproveTransaction()
+            .approve_token_nft_allowance(nft_id, env.operator_id, account_id)
+            .execute(env.client)
+        )
+
+        assert (
+            allowance_receipt.status == ResponseCode.SUCCESS
+        ), f"Allowance approval failed with status: {ResponseCode(allowance_receipt.status).name}"
+
+        env.client.set_operator(account_id, new_account_private_key)
+
+        transfer_transaction = TransferTransaction()
+        transfer_transaction.set_transaction_id(TransactionId.generate(account_id))
+        transfer_transaction.add_approved_nft_transfer(nft_id, env.operator_id, account_id)
+        transfer_transaction.freeze_with(env.client)
+        transfer_transaction.sign(new_account_private_key)
+
+        receipt = transfer_transaction.execute(env.client)
+
+        assert (
+            receipt.status == ResponseCode.SUCCESS
+        ), f"NFT transfer failed with status: {ResponseCode(receipt.status).name}"
+
+        query_transaction = CryptoGetAccountBalanceQuery(account_id)
+        balance = query_transaction.execute(env.client)
+
+        assert balance is not None, "Balance query returned None"
+        assert balance.token_balances == {token_id: serial_number}, (
+            f"Expected token_balances {{{token_id}: {serial_number}}}, "
+            f"got {balance.token_balances}"
+        )
+    finally:
+        env.close()