refactor: restructure as installable PyPI package

- Rename app/ → fragmentapi/ for proper package naming
- Add FragmentClient class with gift_premium, gift_stars, topup_ton methods
- Restructure core/ → types/ (exceptions, results, constants)
- Merge utils/hash.py into utils/client.py
- Replace _version.py with importlib.metadata
- Add input validation with min/max bounds
- Add unit tests: decode, client init/cookies
- Rename 002_test_hash → 003_test_hash
- Clean up pyproject.toml: pin deps, production classifiers

fragmentapi/__init__.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2025 bohd4nx
+#
+# This source code is licensed under the MIT License found in the
+# LICENSE file in the root directory of this source tree.
+
+from fragmentapi.client import FragmentClient
+from fragmentapi.types import (
+    AdsTopupResult,
+    ClientError,
+    ConfigError,
+    CookiesError,
+    FragmentAPIError,
+    FragmentError,
+    HashFetchError,
+    OperationError,
+    PremiumResult,
+    RequestError,
+    StarsResult,
+    TransactionError,
+    UnexpectedError,
+    UserNotFoundError,
+    VerificationError,
+    WalletError,
+)
+
+__all__ = [
+    "FragmentClient",
+    "AdsTopupResult",
+    "PremiumResult",
+    "StarsResult",
+    "ClientError",
+    "ConfigError",
+    "CookiesError",
+    "FragmentAPIError",
+    "FragmentError",
+    "HashFetchError",
+    "OperationError",
+    "RequestError",
+    "TransactionError",
+    "UnexpectedError",
+    "UserNotFoundError",
+    "VerificationError",
+    "WalletError",
+]

fragmentapi/client.py

@@ -0,0 +1,112 @@
+import json
+
+from fragmentapi.methods.premium import gift_premium
+from fragmentapi.methods.stars import gift_stars
+from fragmentapi.methods.ton import topup_ton
+from fragmentapi.types import (
+    REQUIRED_COOKIE_KEYS,
+    SUPPORTED_WALLET_VERSIONS,
+    AdsTopupResult,
+    ConfigError,
+    CookiesError,
+    PremiumResult,
+    StarsResult,
+    WalletVersion,
+)
+
+
+class FragmentClient:
+    """
+    Client for the Fragment.com API.
+
+    Args:
+        seed: 24-word mnemonic phrase for the TON wallet.
+        api_key: Tonapi API key — get one at https://tonconsole.com.
+        cookies: Fragment session cookies as a dict or JSON string.
+        wallet_version: Wallet contract version — ``"V4R2"`` or ``"V5R1"`` (default).
+
+    Raises:
+        ConfigError: If ``seed``, ``api_key``, or ``wallet_version`` are missing or invalid.
+        CookiesError: If ``cookies`` cannot be parsed or are missing required keys.
+
+    Example::
+
+        client = FragmentClient(
+            seed="word1 word2 ...",
+            api_key="AAABBB...",
+            cookies={"stel_ssid": "...", "stel_dt": "...", ...},
+        )
+        result = await client.gift_premium("@username", months=6)
+        print(result.transaction_id)
+    """
+
+    def __init__(
+        self,
+        seed: str,
+        api_key: str,
+        cookies: dict | str,
+        wallet_version: str = "V5R1",
+    ) -> None:
+        missing = [name for name, val in (("seed", seed), ("api_key", api_key)) if not val or not str(val).strip()]
+        if missing:
+            raise ConfigError(ConfigError.MISSING_VARS.format(keys=", ".join(missing)))
+
+        if isinstance(cookies, str):
+            try:
+                cookies = json.loads(cookies)
+            except Exception as exc:
+                raise CookiesError(CookiesError.READ_FAILED.format(exc=exc)) from exc
+
+        missing_keys = [k for k in REQUIRED_COOKIE_KEYS if not str(cookies.get(k, "")).strip()]
+        if missing_keys:
+            raise CookiesError(CookiesError.MISSING_KEYS.format(keys=", ".join(missing_keys)))
+
+        version = wallet_version.strip().upper()
+        if version not in SUPPORTED_WALLET_VERSIONS:
+            raise ConfigError(
+                ConfigError.UNSUPPORTED_VERSION.format(version=version, supported=", ".join(sorted(SUPPORTED_WALLET_VERSIONS)))
+            )
+
+        self.seed: str = seed.strip()
+        self.api_key: str = api_key.strip()
+        self.cookies: dict = cookies
+        self.wallet_version: WalletVersion = version  # type: ignore[assignment]
+
+    async def gift_premium(self, username: str, months: int, show_sender: bool = True) -> PremiumResult:
+        """Gift Telegram Premium to a user.
+
+        Args:
+            username: Recipient's Telegram username (with or without ``@``).
+            months: Duration — ``3``, ``6``, or ``12``.
+            show_sender: Show your name as the gift sender. Defaults to ``True``.
+
+        Returns:
+            :class:`PremiumResult` with ``transaction_id``, ``username``, ``months``, ``timestamp``.
+        """
+        return await gift_premium(self, username, months, show_sender)
+
+    async def gift_stars(self, username: str, amount: int, show_sender: bool = True) -> StarsResult:
+        """Gift Telegram Stars to a user.
+
+        Args:
+            username: Recipient's Telegram username (with or without ``@``).
+            amount: Number of stars — integer from ``50`` to ``1 000 000``.
+            show_sender: Show your name as the gift sender. Defaults to ``True``.
+
+        Returns:
+            :class:`StarsResult` with ``transaction_id``, ``username``, ``stars``, ``timestamp``.
+        """
+        return await gift_stars(self, username, amount, show_sender)
+
+    async def topup_ton(self, username: str, amount: int, show_sender: bool = True) -> AdsTopupResult:
+        """Top up Telegram Ads balance with TON.
+
+        Args:
+            username: Ads account username (with or without ``@``).
+            amount: Amount in TON — integer from ``1`` to ``1 000 000 000``.
+            show_sender: Show your name as the sender. Defaults to ``True``.
+
+        Returns:
+            :class:`AdsTopupResult` with ``transaction_id``, ``username``, ``amount``, ``timestamp``.
+        """
+        return await topup_ton(self, username, amount, show_sender)

fragmentapi/methods/__init__.py

@@ -0,0 +1,5 @@
+from fragmentapi.methods.premium import gift_premium
+from fragmentapi.methods.stars import gift_stars
+from fragmentapi.methods.ton import topup_ton
+
+__all__ = ["gift_premium", "gift_stars", "topup_ton"]

fragmentapi/methods/premium.py

@@ -0,0 +1,119 @@
+import json
+import time
+from typing import TYPE_CHECKING
+
+import httpx
+
+from fragmentapi.types import (
+    BASE_HEADERS,
+    DEVICE,
+    PREMIUM_PAGE,
+    ConfigError,
+    FragmentAPIError,
+    FragmentError,
+    PremiumResult,
+    UnexpectedError,
+    UserNotFoundError,
+)
+from fragmentapi.utils import (
+    execute_transaction_request,
+    get_account_info,
+    get_fragment_hash,
+    parse_json_response,
+    process_transaction,
+)
+
+if TYPE_CHECKING:
+    from fragmentapi.client import FragmentClient
+
+# Page-specific headers
+HEADERS: dict[str, str] = {
+    **BASE_HEADERS,
+    "referer": PREMIUM_PAGE,
+    "x-aj-referer": PREMIUM_PAGE,
+}
+
+
+async def _search_recipient(
+    session: httpx.AsyncClient,
+    fragment_hash: str,
+    username: str,
+    months: int,
+) -> str:
+    resp = await session.post(
+        f"https://fragment.com/api?hash={fragment_hash}",
+        headers=HEADERS,
+        data={
+            "query": username,
+            "months": months,
+            "method": "searchPremiumGiftRecipient",
+        },
+    )
+    result = parse_json_response(resp, "searchPremiumGiftRecipient")
+    recipient = result.get("found", {}).get("recipient")
+    if not recipient:
+        raise UserNotFoundError(UserNotFoundError.NOT_FOUND.format(username=username))
+    return recipient
+
+
+async def _init_request(
+    session: httpx.AsyncClient,
+    fragment_hash: str,
+    recipient: str,
+    months: int,
+) -> str:
+    await session.post(
+        f"https://fragment.com/api?hash={fragment_hash}",
+        headers=HEADERS,
+        data={
+            "mode": "new",
+            "lv": "false",
+            "dh": str(int(time.time())),
+            "method": "updatePremiumState",
+        },
+    )
+    resp = await session.post(
+        f"https://fragment.com/api?hash={fragment_hash}",
+        headers=HEADERS,
+        data={
+            "recipient": recipient,
+            "months": months,
+            "method": "initGiftPremiumRequest",
+        },
+    )
+    result = parse_json_response(resp, "initGiftPremiumRequest")
+    req_id = result.get("req_id")
+    if not req_id:
+        raise FragmentAPIError(FragmentAPIError.NO_REQUEST_ID.format(context="Premium purchase"))
+    return req_id
+
+
+async def gift_premium(client: "FragmentClient", username: str, months: int, show_sender: bool = True) -> PremiumResult:
+    if months not in (3, 6, 12):
+        raise ConfigError(ConfigError.INVALID_MONTHS)
+
+    try:
+        fragment_hash = await get_fragment_hash(client.cookies, HEADERS, PREMIUM_PAGE)
+        account = await get_account_info(client)
+
+        async with httpx.AsyncClient(cookies=client.cookies) as session:
+            recipient = await _search_recipient(session, fragment_hash, username, months)
+            req_id = await _init_request(session, fragment_hash, recipient, months)
+
+            tx_data = {
+                "account": json.dumps(account),
+                "device": DEVICE,
+                "transaction": 1,
+                "id": req_id,
+                "show_sender": int(show_sender),
+                "method": "getGiftPremiumLink",
+            }
+            transaction = await execute_transaction_request(session, HEADERS, tx_data, fragment_hash)
+
+        tx_hash = await process_transaction(client, transaction)
+        return PremiumResult(transaction_id=tx_hash, username=username, months=months)
+
+    except FragmentError:
+        raise
+    except Exception as exc:
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc

fragmentapi/methods/stars.py

@@ -0,0 +1,103 @@
+import json
+from typing import TYPE_CHECKING
+
+import httpx
+
+from fragmentapi.types import (
+    BASE_HEADERS,
+    DEVICE,
+    STARS_PAGE,
+    ConfigError,
+    FragmentAPIError,
+    FragmentError,
+    StarsResult,
+    UnexpectedError,
+    UserNotFoundError,
+)
+from fragmentapi.utils import (
+    execute_transaction_request,
+    get_account_info,
+    get_fragment_hash,
+    parse_json_response,
+    process_transaction,
+)
+
+if TYPE_CHECKING:
+    from fragmentapi.client import FragmentClient
+
+# Page-specific headers
+HEADERS: dict[str, str] = {
+    **BASE_HEADERS,
+    "referer": STARS_PAGE,
+    "x-aj-referer": STARS_PAGE,
+}
+
+
+async def _search_recipient(
+    session: httpx.AsyncClient,
+    fragment_hash: str,
+    username: str,
+) -> str:
+    resp = await session.post(
+        f"https://fragment.com/api?hash={fragment_hash}",
+        headers=HEADERS,
+        data={"query": username, "quantity": "", "method": "searchStarsRecipient"},
+    )
+    result = parse_json_response(resp, "searchStarsRecipient")
+    recipient = result.get("found", {}).get("recipient")
+    if not recipient:
+        raise UserNotFoundError(UserNotFoundError.NOT_FOUND.format(username=username))
+    return recipient
+
+
+async def _init_request(
+    session: httpx.AsyncClient,
+    fragment_hash: str,
+    recipient: str,
+    amount: int,
+) -> str:
+    resp = await session.post(
+        f"https://fragment.com/api?hash={fragment_hash}",
+        headers=HEADERS,
+        data={
+            "recipient": recipient,
+            "quantity": amount,
+            "method": "initBuyStarsRequest",
+        },
+    )
+    result = parse_json_response(resp, "initBuyStarsRequest")
+    req_id = result.get("req_id")
+    if not req_id:
+        raise FragmentAPIError(FragmentAPIError.NO_REQUEST_ID.format(context="Stars purchase"))
+    return req_id
+
+
+async def gift_stars(client: "FragmentClient", username: str, amount: int, show_sender: bool = True) -> StarsResult:
+    if not isinstance(amount, int) or not (50 <= amount <= 1_000_000):
+        raise ConfigError(ConfigError.INVALID_STARS_AMOUNT)
+
+    try:
+        fragment_hash = await get_fragment_hash(client.cookies, HEADERS, STARS_PAGE)
+        account = await get_account_info(client)
+
+        async with httpx.AsyncClient(cookies=client.cookies) as session:
+            recipient = await _search_recipient(session, fragment_hash, username)
+            req_id = await _init_request(session, fragment_hash, recipient, amount)
+
+            tx_data = {
+                "account": json.dumps(account),
+                "device": DEVICE,
+                "transaction": 1,
+                "id": req_id,
+                "show_sender": int(show_sender),
+                "method": "getBuyStarsLink",
+            }
+            transaction = await execute_transaction_request(session, HEADERS, tx_data, fragment_hash)
+
+        tx_hash = await process_transaction(client, transaction)
+        return StarsResult(transaction_id=tx_hash, username=username, stars=amount)
+
+    except FragmentError:
+        raise
+    except Exception as exc:
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc

fragmentapi/methods/ton.py

@@ -0,0 +1,108 @@
+import json
+from typing import TYPE_CHECKING
+
+import httpx
+
+from fragmentapi.types import (
+    BASE_HEADERS,
+    DEVICE,
+    TON_PAGE,
+    AdsTopupResult,
+    ConfigError,
+    FragmentAPIError,
+    FragmentError,
+    UnexpectedError,
+    UserNotFoundError,
+)
+from fragmentapi.utils import (
+    execute_transaction_request,
+    get_account_info,
+    get_fragment_hash,
+    parse_json_response,
+    process_transaction,
+)
+
+if TYPE_CHECKING:
+    from fragmentapi.client import FragmentClient
+
+# Page-specific headers
+HEADERS: dict[str, str] = {
+    **BASE_HEADERS,
+    "referer": TON_PAGE,
+    "x-aj-referer": TON_PAGE,
+}
+
+
+async def _search_recipient(
+    session: httpx.AsyncClient,
+    fragment_hash: str,
+    username: str,
+) -> str:
+    await session.post(
+        f"https://fragment.com/api?hash={fragment_hash}",
+        headers=HEADERS,
+        data={"mode": "new", "method": "updateAdsTopupState"},
+    )
+    resp = await session.post(
+        f"https://fragment.com/api?hash={fragment_hash}",
+        headers=HEADERS,
+        data={"query": username, "method": "searchAdsTopupRecipient"},
+    )
+    result = parse_json_response(resp, "searchAdsTopupRecipient")
+    recipient = result.get("found", {}).get("recipient")
+    if not recipient:
+        raise UserNotFoundError(UserNotFoundError.NOT_FOUND.format(username=username))
+    return recipient
+
+
+async def _init_request(
+    session: httpx.AsyncClient,
+    fragment_hash: str,
+    recipient: str,
+    amount: int,
+) -> str:
+    resp = await session.post(
+        f"https://fragment.com/api?hash={fragment_hash}",
+        headers=HEADERS,
+        data={
+            "recipient": recipient,
+            "amount": amount,
+            "method": "initAdsTopupRequest",
+        },
+    )
+    result = parse_json_response(resp, "initAdsTopupRequest")
+    req_id = result.get("req_id")
+    if not req_id:
+        raise FragmentAPIError(FragmentAPIError.NO_REQUEST_ID.format(context="TON topup"))
+    return req_id
+
+
+async def topup_ton(client: "FragmentClient", username: str, amount: int, show_sender: bool = True) -> AdsTopupResult:
+    if not isinstance(amount, int) or not (1 <= amount <= 1_000_000_000):
+        raise ConfigError(ConfigError.INVALID_TON_AMOUNT)
+
+    try:
+        fragment_hash = await get_fragment_hash(client.cookies, HEADERS, TON_PAGE)
+        account = await get_account_info(client)
+
+        async with httpx.AsyncClient(cookies=client.cookies) as session:
+            recipient = await _search_recipient(session, fragment_hash, username)
+            req_id = await _init_request(session, fragment_hash, recipient, amount)
+
+            tx_data = {
+                "account": json.dumps(account),
+                "device": DEVICE,
+                "transaction": 1,
+                "id": req_id,
+                "show_sender": int(show_sender),
+                "method": "getAdsTopupLink",
+            }
+            transaction = await execute_transaction_request(session, HEADERS, tx_data, fragment_hash)
+
+        tx_hash = await process_transaction(client, transaction)
+        return AdsTopupResult(transaction_id=tx_hash, username=username, amount=amount)
+
+    except FragmentError:
+        raise
+    except Exception as exc:
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc

fragmentapi/types/__init__.py

@@ -0,0 +1,59 @@
+from fragmentapi.types.constants import (
+    BASE_HEADERS,
+    DEVICE,
+    PREMIUM_PAGE,
+    REQUIRED_COOKIE_KEYS,
+    STARS_PAGE,
+    SUPPORTED_WALLET_VERSIONS,
+    TON_PAGE,
+    WALLET_CLASSES,
+    WalletVersion,
+)
+from fragmentapi.types.exceptions import (
+    ClientError,
+    ConfigError,
+    CookiesError,
+    FragmentAPIError,
+    FragmentError,
+    HashFetchError,
+    OperationError,
+    RequestError,
+    TransactionError,
+    UnexpectedError,
+    UserNotFoundError,
+    VerificationError,
+    WalletError,
+)
+from fragmentapi.types.results import AdsTopupResult, PremiumResult, StarsResult
+
+__all__ = [
+    # constants
+    "BASE_HEADERS",
+    "DEVICE",
+    "PREMIUM_PAGE",
+    "REQUIRED_COOKIE_KEYS",
+    "STARS_PAGE",
+    "SUPPORTED_WALLET_VERSIONS",
+    "TON_PAGE",
+    "WALLET_CLASSES",
+    "WalletVersion",
+    # client exceptions
+    "ClientError",
+    "ConfigError",
+    "CookiesError",
+    # fragment exceptions
+    "FragmentAPIError",
+    "FragmentError",
+    "HashFetchError",
+    "OperationError",
+    "RequestError",
+    "TransactionError",
+    "UnexpectedError",
+    "UserNotFoundError",
+    "VerificationError",
+    "WalletError",
+    # result types
+    "AdsTopupResult",
+    "PremiumResult",
+    "StarsResult",
+]

fragmentapi/types/constants.py

@@ -0,0 +1,52 @@
+import json
+from typing import Literal, get_args
+
+from tonutils.contracts.wallet import WalletV4R2, WalletV5R1
+
+# Single source of truth for supported wallet versions
+WalletVersion = Literal["V4R2", "V5R1"]
+SUPPORTED_WALLET_VERSIONS: frozenset[str] = frozenset(get_args(WalletVersion))
+
+# Wallet class map — used to resolve the correct contract from WALLET_VERSION
+WALLET_CLASSES: dict[str, type] = {"V4R2": WalletV4R2, "V5R1": WalletV5R1}
+
+# Required Fragment session cookie keys
+REQUIRED_COOKIE_KEYS: tuple[str, ...] = ("stel_ssid", "stel_dt", "stel_token", "stel_ton_token")
+
+# Fragment page URLs
+STARS_PAGE: str = "https://fragment.com/stars/buy"
+PREMIUM_PAGE: str = "https://fragment.com/premium/gift"
+TON_PAGE: str = "https://fragment.com/ads/topup"
+
+# Tonkeeper device fingerprint — serialized once, reused in every tx_data payload.
+DEVICE: str = json.dumps(
+    {
+        "platform": "iphone",
+        "appName": "Tonkeeper",
+        "appVersion": "5.5.2",
+        "maxProtocolVersion": 2,
+        "features": [
+            "SendTransaction",
+            {"name": "SendTransaction", "maxMessages": 255},
+            {"name": "SignData", "types": ["text", "binary", "cell"]},
+        ],
+    }
+)
+
+# Base HTTP headers — shared across all Fragment API requests.
+# Each method merges these with its own "referer" and "x-aj-referer".
+BASE_HEADERS: dict[str, str] = {
+    "accept": "application/json, text/javascript, */*; q=0.01",
+    "accept-language": "en-US,en;q=0.9,uk;q=0.8,ru;q=0.7",
+    "content-type": "application/x-www-form-urlencoded; charset=UTF-8",
+    "origin": "https://fragment.com",
+    "priority": "u=1, i",
+    "sec-fetch-dest": "empty",
+    "sec-fetch-mode": "cors",
+    "sec-fetch-site": "same-origin",
+    "user-agent": (
+        "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) "
+        "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1"
+    ),
+    "x-requested-with": "XMLHttpRequest",
+}

fragmentapi/types/exceptions.py

@@ -0,0 +1,106 @@
+class FragmentError(Exception):
+    """Base exception for all fragmentapi library errors."""
+
+
+class ClientError(FragmentError):
+    """Raised for client configuration and setup issues (bad params, invalid cookies)."""
+
+
+class ConfigError(ClientError):
+    """Raised when required client parameters are missing or invalid."""
+
+    MISSING_VARS = "Missing required parameter(s): {keys}."
+    UNSUPPORTED_VERSION = "Unsupported wallet_version '{version}'. Must be one of: {supported}."
+    INVALID_MONTHS = "Invalid duration. Choose 3, 6, or 12 months."
+    INVALID_STARS_AMOUNT = "Amount must be an integer between 50 and 1 000 000 stars."
+    INVALID_TON_AMOUNT = "Amount must be an integer between 1 and 1 000 000 000 TON."
+
+
+class CookiesError(ClientError):
+    """Raised when cookies are unreadable or missing required fields."""
+
+    READ_FAILED = "Failed to parse cookies: {exc}"
+    MISSING_KEYS = (
+        "Cookies are missing or have empty values for: {keys}. " "Open Fragment.com in your browser and copy fresh cookies."
+    )
+
+
+class FragmentAPIError(FragmentError):
+    """Raised for errors returned by Fragment's API responses."""
+
+    NO_REQUEST_ID = (
+        "Fragment did not return a request ID for '{context}'. " "The session may have expired — refresh your cookies."
+    )
+
+
+class HashFetchError(FragmentAPIError):
+    """Raised when the Fragment API hash cannot be fetched from the page."""
+
+    BAD_STATUS = "Fragment returned HTTP {status} for {url}. " "Check that your cookies are valid and not expired."
+    NOT_FOUND = (
+        "Fragment hash not found in the page source of {url}. " "The page structure may have changed or you are not logged in."
+    )
+
+
+class UserNotFoundError(FragmentAPIError):
+    """Raised when the target Telegram user is not found on Fragment."""
+
+    NOT_FOUND = (
+        "Telegram user '{username}' was not found on Fragment. " "Make sure the username is correct and the account exists."
+    )
+
+
+class TransactionError(FragmentAPIError):
+    """Raised when a TON transaction fails to build or broadcast."""
+
+    INVALID_PAYLOAD = (
+        "Fragment returned an invalid transaction payload. " "The API response is missing expected 'transaction.messages' data."
+    )
+    BROADCAST_FAILED = "Transaction broadcast failed: {exc}"
+
+
+class RequestError(FragmentAPIError):
+    """Raised when a Fragment API response cannot be parsed."""
+
+    UNPARSEABLE = "Fragment API returned an unparseable response for '{context}': {exc}"
+
+
+class VerificationError(FragmentAPIError):
+    """Raised when Fragment requires KYC verification before proceeding."""
+
+    KYC_REQUIRED = "Fragment requires identity (KYC) verification. " "Complete it at https://fragment.com/my/profile and retry."
+
+
+class OperationError(FragmentError):
+    """Raised for runtime operation failures unrelated to Fragment's API."""
+
+
+class WalletError(OperationError):
+    """Raised for TON wallet issues (connection, balance, account info)."""
+
+    LOW_BALANCE = "TON wallet balance is too low: {balance:.2f} TON. Minimum required is 0.056 TON."
+    BALANCE_CHECK_FAILED = "Wallet balance check failed: {exc}"
+    ACCOUNT_INFO_FAILED = "Failed to retrieve wallet account info: {exc}"
+
+
+class UnexpectedError(OperationError):
+    """Raised when an unexpected error occurs during an API call."""
+
+    UNEXPECTED = "An unexpected error occurred: {exc}"
+
+
+__all__ = [
+    "FragmentError",
+    "ClientError",
+    "ConfigError",
+    "CookiesError",
+    "FragmentAPIError",
+    "HashFetchError",
+    "UserNotFoundError",
+    "TransactionError",
+    "RequestError",
+    "VerificationError",
+    "OperationError",
+    "WalletError",
+    "UnexpectedError",
+]

fragmentapi/types/results.py

@@ -0,0 +1,34 @@
+import time
+from dataclasses import dataclass, field
+
+__all__ = ["AdsTopupResult", "PremiumResult", "StarsResult"]
+
+
+@dataclass
+class PremiumResult:
+    """Result of a successful Telegram Premium gift."""
+
+    transaction_id: str
+    username: str
+    months: int
+    timestamp: int = field(default_factory=lambda: int(time.time()))
+
+
+@dataclass
+class StarsResult:
+    """Result of a successful Telegram Stars purchase."""
+
+    transaction_id: str
+    username: str
+    stars: int
+    timestamp: int = field(default_factory=lambda: int(time.time()))
+
+
+@dataclass
+class AdsTopupResult:
+    """Result of a successful Telegram Ads balance top-up."""
+
+    transaction_id: str
+    username: str
+    amount: int
+    timestamp: int = field(default_factory=lambda: int(time.time()))

fragmentapi/utils/__init__.py

@@ -0,0 +1,16 @@
+from fragmentapi.utils.client import (
+    execute_transaction_request,
+    get_fragment_hash,
+    parse_json_response,
+)
+from fragmentapi.utils.decoder import clean_decode
+from fragmentapi.utils.wallet import get_account_info, process_transaction
+
+__all__ = [
+    "clean_decode",
+    "execute_transaction_request",
+    "get_account_info",
+    "get_fragment_hash",
+    "parse_json_response",
+    "process_transaction",
+]

fragmentapi/utils/client.py

@@ -0,0 +1,107 @@
+import re
+from typing import Any
+
+import httpx
+
+from fragmentapi.types import HashFetchError, RequestError, VerificationError
+
+
+async def get_fragment_hash(
+    cookies: dict[str, Any],
+    headers: dict[str, str],
+    page_url: str,
+) -> str:
+    """Fetch the API hash from a Fragment page.
+
+    Fragment embeds a short-lived hash in each page's HTML that must be
+    included in every subsequent API request. This function loads the page
+    as a real browser navigation (not XHR) so Fragment returns full HTML.
+
+    Args:
+        cookies: Active Fragment session cookies.
+        headers: Base headers for the relevant Fragment page.
+        page_url: URL of the Fragment page to fetch the hash from.
+
+    Returns:
+        Lowercase hex hash string.
+
+    Raises:
+        HashFetchError: If the page returns a non-200 status or the hash
+            is not found in the response HTML.
+    """
+    page_headers = {
+        k: v
+        for k, v in headers.items()
+        if k not in ("accept", "accept-encoding", "content-type", "x-requested-with", "x-aj-referer")
+    }
+    page_headers.update(
+        {
+            "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+            "referer": "https://fragment.com/",
+            "sec-fetch-dest": "document",
+            "sec-fetch-mode": "navigate",
+            "upgrade-insecure-requests": "1",
+        }
+    )
+
+    async with httpx.AsyncClient(cookies=cookies) as session:
+        response = await session.get(page_url, headers=page_headers)
+
+    if response.status_code != 200:
+        raise HashFetchError(HashFetchError.BAD_STATUS.format(status=response.status_code, url=page_url))
+
+    match = re.search(r"(?:https://fragment\.com)?/api\?hash=([a-f0-9]+)", response.text)
+    if not match:
+        raise HashFetchError(HashFetchError.NOT_FOUND.format(url=page_url))
+
+    return match.group(1)
+
+
+def parse_json_response(response: httpx.Response, context: str) -> dict[str, Any]:
+    """Parse a Fragment API JSON response.
+
+    Args:
+        response: The HTTP response object.
+        context: Human-readable name of the API method, used in error messages.
+
+    Returns:
+        Parsed response as a dict.
+
+    Raises:
+        RequestError: If the response body cannot be decoded as JSON.
+    """
+    try:
+        return response.json()
+    except Exception as exc:
+        raise RequestError(RequestError.UNPARSEABLE.format(context=context, exc=exc)) from exc
+
+
+async def execute_transaction_request(
+    session: httpx.AsyncClient,
+    headers: dict,
+    tx_data: dict[str, Any],
+    fragment_hash: str,
+) -> dict[str, Any]:
+    """Post a transaction request to the Fragment API.
+
+    Args:
+        session: Active httpx session with Fragment cookies.
+        headers: Page-specific HTTP headers.
+        tx_data: Form data payload for the API method.
+        fragment_hash: Short-lived hash from the Fragment page.
+
+    Returns:
+        Parsed API response dict containing transaction data.
+
+    Raises:
+        VerificationError: If Fragment requires KYC verification.
+        RequestError: If the response cannot be parsed.
+    """
+    url = f"https://fragment.com/api?hash={fragment_hash}"
+    resp = await session.post(url, headers=headers, data=tx_data)
+    transaction = parse_json_response(resp, tx_data.get("method", "transaction"))
+
+    if transaction.get("need_verify"):
+        raise VerificationError(VerificationError.KYC_REQUIRED)
+
+    return transaction

fragmentapi/utils/decoder.py

@@ -0,0 +1,20 @@
+import base64
+
+from pytoniq_core import Cell
+
+from fragmentapi.types import RequestError
+
+
+def clean_decode(payload: str) -> str:
+    s = payload.strip()
+    if not s:
+        return ""
+    s += "=" * (-len(s) % 4)
+    try:
+        boc = base64.b64decode(s)
+        cell = Cell.one_from_boc(boc)
+        sl = cell.begin_parse()
+        sl.load_uint(32)  # op code — always 0 for text comment
+        return sl.load_snake_string().strip()
+    except Exception as exc:
+        raise RequestError(RequestError.UNPARSEABLE.format(context="payload decode", exc=exc)) from exc

fragmentapi/utils/wallet.py

@@ -0,0 +1,69 @@
+import base64
+from typing import TYPE_CHECKING, Any
+
+from tonutils.clients import TonapiClient
+from tonutils.types import NetworkGlobalID
+
+from fragmentapi.types import WALLET_CLASSES, TransactionError, WalletError
+from fragmentapi.utils.decoder import clean_decode
+
+if TYPE_CHECKING:
+    from fragmentapi.client import FragmentClient
+
+
+def _init_ton_client(client: "FragmentClient") -> TonapiClient:
+    return TonapiClient(network=NetworkGlobalID.MAINNET, api_key=client.api_key)
+
+
+async def process_transaction(client: "FragmentClient", transaction_data: dict) -> str:
+    if "transaction" not in transaction_data or "messages" not in transaction_data["transaction"]:
+        raise TransactionError(TransactionError.INVALID_PAYLOAD)
+
+    # TODO: Investigate 406 'inbound external message rejected before smart-contract execution'.
+    # This happens when the previous transaction's seqno hasn't been confirmed on-chain yet,
+    # causing the wallet contract to reject the new message.
+    async with _init_ton_client(client) as ton:
+        wallet_cls = WALLET_CLASSES[client.wallet_version]
+        wallet, _, _, _ = wallet_cls.from_mnemonic(client=ton, mnemonic=client.seed)
+
+        # Check balance before broadcasting
+        try:
+            await wallet.refresh()
+            balance_ton = wallet.balance / 1_000_000_000
+            if balance_ton < 0.056:
+                raise WalletError(WalletError.LOW_BALANCE.format(balance=balance_ton))
+        except WalletError:
+            raise
+        except Exception as exc:
+            raise WalletError(WalletError.BALANCE_CHECK_FAILED.format(exc=exc)) from exc
+
+        try:
+            message = transaction_data["transaction"]["messages"][0]
+            payload = clean_decode(message["payload"])
+
+            result = await wallet.transfer(
+                destination=message["address"],
+                amount=int(message["amount"]),  # nanotons, not TON
+                body=payload,
+            )
+            return result.normalized_hash
+        except (WalletError, TransactionError):
+            raise
+        except Exception as exc:
+            raise TransactionError(TransactionError.BROADCAST_FAILED.format(exc=exc)) from exc
+
+
+async def get_account_info(client: "FragmentClient") -> dict[str, Any]:
+    async with _init_ton_client(client) as ton:
+        try:
+            wallet_cls = WALLET_CLASSES[client.wallet_version]
+            wallet, pub_key, _, _ = wallet_cls.from_mnemonic(client=ton, mnemonic=client.seed)
+            boc = wallet.state_init.serialize().to_boc()
+            return {
+                "address": wallet.address.to_str(False, False),
+                "publicKey": pub_key.as_hex,
+                "chain": "-239",
+                "walletStateInit": base64.b64encode(boc).decode(),
+            }
+        except Exception as exc:
+            raise WalletError(WalletError.ACCOUNT_INFO_FAILED.format(exc=exc)) from exc