python-telegram-bot · Bibo-Joshi · May 4, 2025 · May 1, 2025 · May 1, 2025 · May 1, 2025
diff --git a/changes/unreleased/4756.JT5nmUmGRG6qDEh5ScMn5f.toml b/changes/unreleased/4756.JT5nmUmGRG6qDEh5ScMn5f.toml
@@ -1,4 +1,10 @@
 features = "Full Support for Bot API 9.0"
+deprecations = """This release comes with several deprecations, in line with our :ref:`stability policy <stability-policy>`.
+This includes the following:
+
+- Deprecated ``telegram.constants.StarTransactionsLimit.NANOSTAR_MIN_AMOUNT`` and ``telegram.constants.StarTransactionsLimit.NANOSTAR_MAX_AMOUNT``. These members will be replaced by ``telegram.constants.NanostarLimit.MIN_AMOUNT`` and ``telegram.constants.NanostarLimit.MAX_AMOUNT``.
+- Deprecated the class ``telegram.constants.StarTransactions``. Its only member ``telegram.constants.StarTransactions.NANOSTAR_VALUE`` will be replaced by ``telegram.constants.Nanostar.VALUE``.
+"""
 [[pull_requests]]
 uid = "4756"
 author_uid = "Bibo-Joshi"
@@ -22,3 +28,7 @@ author_uid = "Bibo-Joshi"
 uid = "4769"
 author_uid = "aelkheir"
 closes_threads = []
+[[pull_requests]]
+uid = "4773"
+author_uid = "aelkheir"
+closes_threads = []
diff --git a/docs/source/inclusions/bot_methods.rst b/docs/source/inclusions/bot_methods.rst
@@ -413,6 +413,8 @@
       - Used for getting information about the business account.
     * - :meth:`~telegram.Bot.get_business_account_gifts`
       - Used for getting gifts owned by the business account.
+    * - :meth:`~telegram.Bot.get_business_account_star_balance`
+      - Used for getting the amount of Stars owned by the business account.
     * - :meth:`~telegram.Bot.read_business_message`
       - Used for marking a message as read.
     * - :meth:`~telegram.Bot.delete_story`
@@ -441,6 +443,8 @@
       - Used for upgrading owned regular gifts to unique ones.
     * - :meth:`~telegram.Bot.transfer_gift`
       - Used for transferring owned unique gifts to another user.
+    * - :meth:`~telegram.Bot.transfer_business_account_stars`
+      - Used for transfering Stars from the business account balance to the bot's balance.
 
 
 .. raw:: html

diff --git a/docs/source/telegram.payments-tree.rst b/docs/source/telegram.payments-tree.rst
@@ -22,6 +22,7 @@ Your bot can accept payments from Telegram users. Please see the `introduction t
     telegram.shippingaddress
     telegram.shippingoption
     telegram.shippingquery
+    telegram.staramount
     telegram.startransaction
     telegram.startransactions
     telegram.successfulpayment

diff --git a/docs/source/telegram.staramount.rst b/docs/source/telegram.staramount.rst
@@ -0,0 +1,6 @@
+StarAmount
+==========
+
+.. autoclass:: telegram.StarAmount
+    :members:
+    :show-inheritance:
diff --git a/telegram/__init__.py b/telegram/__init__.py
@@ -241,6 +241,7 @@
     "ShippingAddress",
     "ShippingOption",
     "ShippingQuery",
+    "StarAmount",
     "StarTransaction",
     "StarTransactions",
     "Sticker",
@@ -300,6 +301,7 @@
     "warnings",
 )
 
+from telegram._payment.stars.staramount import StarAmount
 from telegram._payment.stars.startransactions import StarTransaction, StarTransactions
 from telegram._payment.stars.transactionpartner import (
     TransactionPartner,

diff --git a/telegram/_bot.py b/telegram/_bot.py
@@ -82,6 +82,7 @@
 from telegram._message import Message
 from telegram._messageid import MessageId
 from telegram._ownedgift import OwnedGifts
+from telegram._payment.stars.staramount import StarAmount
 from telegram._payment.stars.startransactions import StarTransactions
 from telegram._poll import InputPollOption, Poll
 from telegram._reaction import ReactionType, ReactionTypeCustomEmoji, ReactionTypeEmoji
@@ -9480,6 +9481,45 @@ async def get_business_account_gifts(
             )
         )
 
+    async def get_business_account_star_balance(
+        self,
+        business_connection_id: str,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> StarAmount:
+        """
+        Returns the amount of Telegram Stars owned by a managed business account. Requires the
+        :attr:`~telegram.BusinessBotRights.can_view_gifts_and_stars` business bot right.
+
+        .. versionadded:: NEXT.VERSION
+
+        Args:
+            business_connection_id (:obj:`str`): Unique identifier of the business connection.
+
+        Returns:
+            :class:`telegram.StarAmount`
+
+        Raises:
+            :class:`telegram.error.TelegramError`
+        """
+        data: JSONDict = {"business_connection_id": business_connection_id}
+        return StarAmount.de_json(
+            await self._post(
+                "getBusinessAccountStarBalance",
+                data,
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
+                api_kwargs=api_kwargs,
+            ),
+            bot=self,
+        )
+
     async def read_business_message(
         self,
         business_connection_id: str,
@@ -10217,6 +10257,50 @@ async def transfer_gift(
             api_kwargs=api_kwargs,
         )
 
+    async def transfer_business_account_stars(
+        self,
+        business_connection_id: str,
+        star_count: int,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: Optional[JSONDict] = None,
+    ) -> bool:
+        """
+        Transfers Telegram Stars from the business account balance to the bot's balance. Requires
+        the :attr:`~telegram.BusinessBotRights.can_transfer_stars` business bot right.
+
+        .. versionadded:: NEXT.VERSION
+
+        Args:
+            business_connection_id (:obj:`str`): Unique identifier of the business
+                connection
+            star_count (:obj:`int`): Number of Telegram Stars to transfer;
+                :tg-const:`~telegram.constants.BusinessLimit.MIN_STAR_COUNT`\
+-:tg-const:`~telegram.constants.BusinessLimit.MAX_STAR_COUNT`
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        Raises:
+            :class:`telegram.error.TelegramError`
+        """
+        data: JSONDict = {
+            "business_connection_id": business_connection_id,
+            "star_count": star_count,
+        }
+        return await self._post(
+            "transferBusinessAccountStars",
+            data,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
     async def replace_sticker_in_set(
         self,
         user_id: int,
@@ -11154,6 +11238,8 @@ def to_dict(self, recursive: bool = True) -> JSONDict:  # noqa: ARG002
     """Alias for :meth:`set_message_reaction`"""
     getBusinessAccountGifts = get_business_account_gifts
     """Alias for :meth:`get_business_account_gifts`"""
+    getBusinessAccountStarBalance = get_business_account_star_balance
+    """Alias for :meth:`get_business_account_star_balance`"""
     getBusinessConnection = get_business_connection
     """Alias for :meth:`get_business_connection`"""
     readBusinessMessage = read_business_message
@@ -11184,6 +11270,8 @@ def to_dict(self, recursive: bool = True) -> JSONDict:  # noqa: ARG002
     """Alias for :meth:`upgrade_gift`"""
     transferGift = transfer_gift
     """Alias for :meth:`transfer_gift`"""
+    transferBusinessAccountStars = transfer_business_account_stars
+    """Alias for :meth:`transfer_business_account_stars`"""
     replaceStickerInSet = replace_sticker_in_set
     """Alias for :meth:`replace_sticker_in_set`"""
     refundStarPayment = refund_star_payment

diff --git a/telegram/_payment/stars/affiliateinfo.py b/telegram/_payment/stars/affiliateinfo.py
@@ -48,10 +48,10 @@ class AffiliateInfo(TelegramObject):
         amount (:obj:`int`): Integer amount of Telegram Stars received by the affiliate from the
             transaction, rounded to 0; can be negative for refunds
         nanostar_amount (:obj:`int`, optional): The number of
-            :tg-const:`~telegram.constants.StarTransactions.NANOSTAR_VALUE` shares of Telegram
+            :tg-const:`~telegram.constants.Nanostar.VALUE` shares of Telegram
             Stars received by the affiliate; from
-            :tg-const:`~telegram.constants.StarTransactionsLimit.NANOSTAR_MIN_AMOUNT` to
-            :tg-const:`~telegram.constants.StarTransactionsLimit.NANOSTAR_MAX_AMOUNT`;
+            :tg-const:`~telegram.constants.NanostarLimit.MIN_AMOUNT` to
+            :tg-const:`~telegram.constants.NanostarLimit.MAX_AMOUNT`;
             can be negative for refunds
 
     Attributes:
@@ -64,10 +64,10 @@ class AffiliateInfo(TelegramObject):
         amount (:obj:`int`): Integer amount of Telegram Stars received by the affiliate from the
             transaction, rounded to 0; can be negative for refunds
         nanostar_amount (:obj:`int`): Optional. The number of
-            :tg-const:`~telegram.constants.StarTransactions.NANOSTAR_VALUE` shares of Telegram
+            :tg-const:`~telegram.constants.Nanostar.VALUE` shares of Telegram
             Stars received by the affiliate; from
-            :tg-const:`~telegram.constants.StarTransactionsLimit.NANOSTAR_MIN_AMOUNT` to
-            :tg-const:`~telegram.constants.StarTransactionsLimit.NANOSTAR_MAX_AMOUNT`;
+            :tg-const:`~telegram.constants.NanostarLimit.MIN_AMOUNT` to
+            :tg-const:`~telegram.constants.NanostarLimit.MAX_AMOUNT`;
             can be negative for refunds
     """
 

diff --git a/telegram/_payment/stars/staramount.py b/telegram/_payment/stars/staramount.py
@@ -0,0 +1,68 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2025
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program. If not, see [http://www.gnu.org/licenses/].
+# pylint: disable=redefined-builtin
+"""This module contains an object that represents a Telegram StarAmount."""
+
+
+from typing import Optional
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class StarAmount(TelegramObject):
+    """Describes an amount of Telegram Stars.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`amount` and :attr:`nanostar_amount` are equal.
+
+    Args:
+        amount (:obj:`int`): Integer amount of Telegram Stars, rounded to ``0``; can be negative.
+        nanostar_amount (:obj:`int`, optional): The number of
+            :tg-const:`telegram.constants.Nanostar.VALUE` shares of Telegram
+            Stars; from :tg-const:`telegram.constants.NanostarLimit.MIN_AMOUNT`
+            to :tg-const:`telegram.constants.NanostarLimit.MAX_AMOUNT`; can be
+            negative if and only if :attr:`amount` is non-positive.
+
+    Attributes:
+        amount (:obj:`int`): Integer amount of Telegram Stars, rounded to ``0``; can be negative.
+        nanostar_amount (:obj:`int`): Optional. The number of
+            :tg-const:`telegram.constants.Nanostar.VALUE` shares of Telegram
+            Stars; from :tg-const:`telegram.constants.NanostarLimit.MIN_AMOUNT`
+            to :tg-const:`telegram.constants.NanostarLimit.MAX_AMOUNT`; can be
+            negative if and only if :attr:`amount` is non-positive.
+
+    """
+
+    __slots__ = ("amount", "nanostar_amount")
+
+    def __init__(
+        self,
+        amount: int,
+        nanostar_amount: Optional[int] = None,
+        *,
+        api_kwargs: Optional[JSONDict] = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.amount: int = amount
+        self.nanostar_amount: Optional[int] = nanostar_amount
+
+        self._id_attrs = (self.amount, self.nanostar_amount)
+
+        self._freeze()
diff --git a/telegram/_payment/stars/startransactions.py b/telegram/_payment/stars/startransactions.py
@@ -52,9 +52,9 @@ class StarTransaction(TelegramObject):
             successful incoming payments from users.
         amount (:obj:`int`): Integer amount of Telegram Stars transferred by the transaction.
         nanostar_amount (:obj:`int`, optional): The number of
-            :tg-const:`~telegram.constants.StarTransactions.NANOSTAR_VALUE` shares of Telegram
+            :tg-const:`~telegram.constants.Nanostar.VALUE` shares of Telegram
             Stars transferred by the transaction; from 0 to
-            :tg-const:`~telegram.constants.StarTransactionsLimit.NANOSTAR_MAX_AMOUNT`
+            :tg-const:`~telegram.constants.NanostarLimit.MAX_AMOUNT`
 
             .. versionadded:: 21.9
         date (:obj:`datetime.datetime`): Date the transaction was created as a datetime object.
@@ -72,9 +72,9 @@ class StarTransaction(TelegramObject):
             successful incoming payments from users.
         amount (:obj:`int`): Integer amount of Telegram Stars transferred by the transaction.
         nanostar_amount (:obj:`int`): Optional. The number of
-            :tg-const:`~telegram.constants.StarTransactions.NANOSTAR_VALUE` shares of Telegram
+            :tg-const:`~telegram.constants.Nanostar.VALUE` shares of Telegram
             Stars transferred by the transaction; from 0 to
-            :tg-const:`~telegram.constants.StarTransactionsLimit.NANOSTAR_MAX_AMOUNT`
+            :tg-const:`~telegram.constants.NanostarLimit.MAX_AMOUNT`
 
             .. versionadded:: 21.9
         date (:obj:`datetime.datetime`): Date the transaction was created as a datetime object.