Merge pull request #35 from bohd4nx/dev

Dev

.env.example

@@ -1,11 +0,0 @@
-# Fragment.com cookies - copy from browser after login (Header String format)
-# Hash is now fetched dynamically
-
-# TON wallet seed phrase - 12 or 24 words separated by spaces
-SEED = "your_ton_wallet_seed_phrase_here"
-
-# TON API key - get from https://tonconsole.com
-API_KEY = "your_ton_api_key_here"
-
-# TON wallet contract version: V4R2 or V5R1 (default: V5R1)
-WALLET_VERSION = "V5R1"

.github/ISSUE_TEMPLATE/bug.yaml

@@ -0,0 +1,101 @@
+name: Bug report
+description: Report an issue or unexpected behavior in pyfragment.
+labels:
+- bug
+body:
+- type: checkboxes
+  attributes:
+    label: Checklist
+    options:
+    - label: I am sure the error is coming from pyfragment code
+      required: true
+    - label: I have searched the issue tracker for similar bug reports, including closed ones
+      required: true
+
+- type: markdown
+  attributes:
+    value: |
+      ## Context
+      Please provide as much detail as possible to help us reproduce and fix the issue.
+
+- type: input
+  attributes:
+    label: Operating system
+    placeholder: e.g. Ubuntu 22.04 / macOS 14 / Windows 11
+  validations:
+    required: true
+
+- type: input
+  attributes:
+    label: Python version
+    description: Run `python --version` inside your virtualenv
+    placeholder: e.g. 3.12.3
+  validations:
+    required: true
+
+- type: input
+  attributes:
+    label: pyfragment version
+    description: Run `pip show pyfragment` inside your virtualenv
+    placeholder: e.g. 2026.1.0
+  validations:
+    required: true
+
+- type: textarea
+  attributes:
+    label: Expected behavior
+    description: Describe what you expected to happen.
+    placeholder: e.g. Stars should be purchased and StarsResult returned.
+  validations:
+    required: true
+
+- type: textarea
+  attributes:
+    label: Current behavior
+    description: Describe what is actually happening.
+    placeholder: e.g. ParseError is raised with status 400.
+  validations:
+    required: true
+
+- type: textarea
+  attributes:
+    label: Steps to reproduce
+    description: Minimal steps that reproduce the issue.
+    placeholder: |
+      1. Create FragmentClient with valid credentials
+      2. Call purchase_stars("@username", amount=100)
+      3. See error
+  validations:
+    required: true
+
+- type: textarea
+  attributes:
+    label: Code example
+    description: Provide a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) if applicable.
+    placeholder: |
+      import asyncio
+      from pyfragment import FragmentClient
+
+      async def main():
+          client = FragmentClient(...)
+          result = await client.purchase_stars("@username", amount=100)
+
+      asyncio.run(main())
+    render: python
+
+- type: textarea
+  attributes:
+    label: Traceback / logs
+    description: Paste the full traceback or relevant logs.
+    placeholder: |
+      Traceback (most recent call last):
+        File "main.py", line 7, in main
+          ...
+      pyfragment.types.ParseError: ...
+    render: sh
+
+- type: textarea
+  attributes:
+    label: Additional information
+    description: Anything else that might help us diagnose the problem.
+    placeholder: e.g. Only happens with V5R1 wallet version.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+- name: Ask a question or start a discussion
+  url: https://github.com/bohd4nx/pyfragment/discussions
+  about: General questions, ideas, and community help go here — not in the issue tracker.

.github/ISSUE_TEMPLATE/feature.yaml

@@ -0,0 +1,51 @@
+name: Feature request
+description: Suggest an improvement or new feature for pyfragment.
+labels:
+- enhancement
+body:
+- type: dropdown
+  attributes:
+    label: pyfragment version
+    description: Which version are you running?
+    options:
+    - latest
+    - older
+    - n/a
+  validations:
+    required: true
+
+- type: textarea
+  attributes:
+    label: Problem
+    description: Is your request related to a specific problem? Describe it.
+    placeholder: e.g. There is no way to check my current TON balance before sending.
+  validations:
+    required: true
+
+- type: textarea
+  attributes:
+    label: Proposed solution
+    description: Describe what you would like to see added or changed.
+    placeholder: e.g. Add a get_balance() method to FragmentClient.
+  validations:
+    required: true
+
+- type: textarea
+  attributes:
+    label: Alternatives considered
+    description: Any workarounds or alternative approaches you have thought of.
+    placeholder: e.g. I manually call the Fragment API, but it's not ergonomic.
+
+- type: textarea
+  attributes:
+    label: Code example
+    description: A short example demonstrating the desired API, if applicable.
+    placeholder: |
+      balance = await client.get_balance()
+      print(balance.ton)
+    render: python
+
+- type: textarea
+  attributes:
+    label: Additional information
+    description: Any other context, screenshots, or references.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+# Description
+
+Please include a summary of the change and which issue is fixed.
+Include relevant motivation and context.
+
+Fixes # (issue)
+
+## Type of change
+
+- [ ] Documentation (typos, examples, or any docs update)
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] This change requires a documentation update
+
+## How has this been tested?
+
+Describe the tests you ran to verify the change and list any relevant details.
+
+- [ ] Existing tests pass (`pytest`)
+- [ ] New tests added for this change
+
+**Test configuration:**
+* OS:
+* Python version:
+* pyfragment version:
+
+## Checklist
+
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have updated documentation where necessary
+- [ ] I have added tests that prove my fix or feature works
+- [ ] All new and existing tests pass locally

.github/dependabot.yml

@@ -1,10 +1,19 @@
 version: 2
 updates:
-  - package-ecosystem: "pip"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-      day: "monday"
-    open-pull-requests-limit: 5
-    labels:
-      - "dependencies"
+- package-ecosystem: "pip"
+  directory: "/"
+  schedule:
+    interval: "weekly"
+    day: "monday"
+  open-pull-requests-limit: 5
+  labels:
+  - "dependencies"
+
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "weekly"
+    day: "monday"
+  open-pull-requests-limit: 5
+  labels:
+  - "dependencies"

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: actions/setup-python@v6
+      with:
+        python-version: "3.11"
+        cache: pip
+
+    - run: pip install ".[dev]"
+
+    - run: ruff check . && ruff format --check . && mypy pyfragment --explicit-package-bases
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: pip
+
+    - name: Install package and dev dependencies
+      run: pip install ".[dev]"
+
+    - name: Run tests
+      run: pytest

.github/workflows/publish.yml

@@ -0,0 +1,97 @@
+name: Publish
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: [master]
+
+jobs:
+  version-check:
+    name: Version Check
+    if: github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.value }}
+      is-new: ${{ steps.tag.outputs.is-new }}
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        fetch-depth: 0
+
+    - name: Read version
+      id: version
+      run: |
+        value=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+        echo "value=$value" >> $GITHUB_OUTPUT
+
+    - name: Check tag
+      id: tag
+      run: |
+        if git ls-remote --tags origin "refs/tags/v${{ steps.version.outputs.value }}" | grep -q .; then
+          echo "is-new=false" >> $GITHUB_OUTPUT
+        else
+          echo "is-new=true" >> $GITHUB_OUTPUT
+        fi
+
+  build:
+    name: Build
+    needs: version-check
+    if: needs.version-check.outputs.is-new == 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+
+    - uses: astral-sh/setup-uv@v8.2.0
+
+    - run: uv build
+
+    - uses: actions/upload-artifact@v7
+      with:
+        name: dist
+        path: dist/*
+
+  publish:
+    name: Publish to PyPI
+    needs: [version-check, build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pyfragment/
+    permissions:
+      id-token: write
+
+    steps:
+    - uses: actions/download-artifact@v8
+      with:
+        name: dist
+        path: dist
+
+    - uses: pypa/gh-action-pypi-publish@release/v1
+
+  release:
+    name: GitHub Release
+    needs: [version-check, build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/download-artifact@v8
+      with:
+        name: dist
+        path: dist
+
+    - uses: softprops/action-gh-release@v3
+      with:
+        tag_name: v${{ needs.version-check.outputs.version }}
+        name: v${{ needs.version-check.outputs.version }}
+        files: dist/*
+        generate_release_notes: true
+        make_latest: true

.github/workflows/tests.yml

@@ -1,31 +0,0 @@
-name: Tests
-
-on:
-  push:
-    branches: ["**"]
-  pull_request:
-    branches: ["**"]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: actions/setup-python@v6
-        with:
-          python-version: "3.12"
-          cache: "pip"
-
-      - name: Install dependencies
-        run: pip install -r requirements.txt pytest pytest-asyncio
-
-      - name: Write cookies.json
-        if: ${{ env.COOKIES_JSON != '' }}
-        run: echo "$COOKIES_JSON" > cookies.json
-        env:
-          COOKIES_JSON: ${{ secrets.COOKIES_JSON }}
-
-      - name: Run tests
-        run: pytest

.gitignore

@@ -23,4 +23,21 @@ logs/
 # System files
 .DS_Store
 Thumbs.db
-cookies.json
+
+# Testing & tooling artifacts
+.hypothesis/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+systests/
+
+# Build & distribution
+dist/
+build/
+*.egg-info/
+uv.lock
+
+#docs
+*-docs/

CHANGELOG.md

@@ -0,0 +1,283 @@
+# Changelog
+
+All notable changes to pyfragment are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Calendar Versioning](https://calver.org/) (`YYYY.MINOR.MICRO`).
+
+---
+
+## [2026.3.2] — 2026-06-16
+
+### Added
+
+- Added `ApiProvider` enum with `TONAPI` (tonconsole.com, default) and `TONCENTER` (t.me/toncenter) values.
+- Added `api_provider` parameter to `FragmentClient` — select the blockchain API provider at init time (`"tonapi"` or `"toncenter"`).
+- Both providers accept `api_key` with the same interface; the correct `tonutils` client is selected automatically.
+
+- New `AlreadySubscribedError` exception for Premium purchase flows when Fragment returns: `This account is already subscribed to Telegram Premium.`
+- New `UserNotFoundError.NOT_A_USER` message for when Fragment returns: `Please enter a username assigned to a user.` (e.g. when the username belongs to a channel or bot).
+- Added `WalletVersion.HighloadV2` and `WalletVersion.HighloadV3R1` to `WalletVersion`
+
+### Changed
+
+- Updated purchase and giveaway flow state nonces (`dh`) to use nonce-like dynamic values with a wider integer range.
+- Stars and Premium giveaway flows now include explicit price update steps before init requests:
+  - `updateStarsGiveawayPrices`
+  - `updatePremiumGiveawayPrices`
+- Updated `DEVICE_INFO` fingerprint: Tonkeeper `appVersion` -> `26.05.0`.
+- Updated client docstrings and purchase examples to document all supported payment methods.
+
+### Renamed — TON -> GRAM (ex TON)
+
+The TON blockchain has been rebranded to **GRAM (ex TON)**. All identifiers, messages, and documentation have been updated accordingly.
+
+**Public API**
+
+- `FragmentClient.topup_ton()` → `topup_gram()`
+- `PaymentMethod.TON` → `PaymentMethod.GRAM`
+- `PaymentMethod.USDT_TON` → `PaymentMethod.USDT_GRAM`
+- `WalletInfo.ton_balance` → `WalletInfo.gram_balance`
+
+**Constants**
+
+- `TON_TOPUP_MIN` / `TON_TOPUP_MAX` → `GRAM_TOPUP_MIN` / `GRAM_TOPUP_MAX`
+- `MIN_TON_BALANCE` → `MIN_GRAM_BALANCE`
+- `USDT_TON_MASTER_ADDRESS` → `USDT_GRAM_MASTER_ADDRESS`
+
+**Exceptions**
+
+- `ConfigurationError.INVALID_TON_AMOUNT` → `INVALID_GRAM_AMOUNT`
+- `WalletError.LOW_TON_BALANCE` → `LOW_GRAM_BALANCE`
+- `WalletError.TON_BALANCE_CHECK_FAILED` → `GRAM_BALANCE_CHECK_FAILED`
+
+**Internals**
+
+- `pyfragment/core/constants/ton.py` → `gram.py`
+- `check_ton_payment_balance()` → `check_gram_payment_balance()`
+
+---
+
+## [2026.3.1] — 2026-05-29
+
+### Added
+
+- Python 3.13 and 3.14 are now officially supported and included in the CI test matrix and PyPI classifiers.
+- `WalletVersion` is now exported from the top-level `pyfragment` package.
+
+### Changed
+
+- `process_transaction` (internal) refactored into focused subfunctions: `_extract_message`, `_check_payment_balances`, `_broadcast_with_retry`.
+- `raw_api_call()` moved from `FragmentClient` into `pyfragment.domains.base` and exposed as a standalone helper.
+- `tonapi` domain internal helpers removed from public `__init__.py` exports; only `TonapiService` is exported.
+- README rewritten with badges, structured sections, and complete usage examples.
+- Added `CONTRIBUTING.md` and `SECURITY.md`.
+
+### Fixed
+
+- CI: `mypy` now runs with `--explicit-package-bases` to avoid false-positive import errors.
+- CI: `pip` dependency cache enabled to speed up workflow runs.
+- CI: `warn_unused_ignores` suppressed for `pyfragment.core.cookies` to handle the optional `rookiepy` dependency correctly across environments where the package may or may not be installed.
+- Publish workflow now uses `generate_release_notes: true` instead of manual changelog extraction.
+
+### Removed
+
+- `tonapi/transfer.py` and associated `TonTransferResult` / `UsdtTransferResult` models (internal, unused).
+
+---
+
+## [2026.3.0] — 2026-05-21
+
+### Changed
+
+- Internal architecture reorganized around explicit domain packages:
+  - TON account and balance helpers are now unified under `pyfragment.domains.tonapi.account`
+  - service wrappers and operation modules are aligned by domain (`ads`, `purchases`, `giveaways`, `anonymous_numbers`, `marketplace`, `tonapi`)
+- Package exports were cleaned up for domain and model packages (`__init__.py`) to provide clearer public symbols.
+- Examples and system tests were updated to follow current public import paths and project structure.
+
+### Fixed
+
+- `get_cookies_from_browser()` is now patch-friendly in tests (`pyfragment.core.cookies.rookiepy` can be mocked reliably).
+- Anonymous number `NOT_OWNED` error message wording was adjusted for test and backward-compatibility with existing matchers.
+
+## [2026.2.3] — 2026-05-12
+
+### Fixed
+
+- Fixed USDT payment flow: the USDT balance check now correctly targets the wallet linked to the Fragment account (`transaction["from"]`), not the signing seed wallet. These are two distinct addresses — the seed wallet only signs the transaction and covers TON gas fees, while USDT is withdrawn from the Fragment-linked wallet.
+- Fixed `clean_decode()` incorrectly treating binary TON cell payloads (e.g. jetton transfer messages with non-zero op codes) as text comments. Only cells with op code `0x00000000` are now decoded as snake-encoded UTF-8 strings; all other op codes return the raw `Cell` as-is.
+- Restored and correctly wired USDT balance validation so `WalletError` is raised before broadcasting when the Fragment-linked wallet has insufficient USDT.
+
+### Note
+
+- USDT (`usdt_ton`) payments require USDT to be held in the TON wallet that is linked to your Fragment account profile. The seed wallet configured in `FragmentClient` is only used to sign transactions and pay TON network fees.
+
+---
+
+## [2026.2.2] — 2026-05-11
+
+### Added
+
+- `payment_method` option (`"ton"` / `"usdt_ton"`) for:
+  - `purchase_stars()`
+  - `purchase_premium()`
+  - `giveaway_stars()`
+  - `giveaway_premium()`
+
+### Changed
+
+- Added runtime validation for `payment_method` via `SUPPORTED_PAYMENT_METHODS` and `ConfigurationError.INVALID_PAYMENT_METHOD`
+- Updated method docstrings to explicitly document recipient/channel formats:
+  - `@username` / `username` / `https://t.me/username`
+- `get_wallet()` now returns balances as separate fields: `ton_balance` and `usdt_balance`
+- Wallet/system test output now prints TON and USDT balances on separate lines
+- Balance checks are now method-aware with explicit thresholds:
+  - `ton`: minimum TON balance threshold via `MIN_TON_BALANCE` (based on current 50 Stars purchase amount)
+  - `usdt_ton`: minimum USDT balance threshold via `MIN_USDT_BALANCE` (based on current 50 Stars purchase amount)
+
+### Tests
+
+- Extended stars and premium test suites to cover:
+  - invalid payment method
+  - payment method propagation to `init*Request` payloads
+  - accepted query formats (`@`, plain username, `t.me` link)
+- Extended wallet tests to verify separate TON/USDT balance values in `WalletInfo`
+
+### Documentation
+
+- Simplified `README` usage example
+
+## [2026.2.1] — 2026-05-03
+
+### Fixed
+
+- Fragment API 429 responses are now retried automatically (up to 3 attempts) with exponential backoff and jitter in `fragment_request`
+- Retry delays in TON transaction broadcasting now include jitter to reduce contention under concurrent calls
+- Improved handling of non-200 HTTP responses in `get_fragment_hash`
+- Removed unnecessary `method` key leaking into certain API request payloads
+
+### Changed
+
+- Type hints refined across the codebase for better clarity and `mypy` strict compliance
+
+---
+
+## [2026.2.0] — 2026-04-14
+
+### Added
+
+- `get_cookies_from_browser(browser)` — extract Fragment session cookies directly from an installed browser (Chrome, Firefox, Edge, Brave, Arc, Opera, Safari, and more); no browser extension or manual copy-paste required
+  ```python
+  from pyfragment import get_cookies_from_browser
+  result = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+  client = FragmentClient(seed="...", api_key="...", cookies=result.cookies)
+  print(result.expires)  # ISO 8601 expiry of stel_ssid, or None for session cookies
+  ```
+- `CookieResult` — return type of `get_cookies_from_browser()`; exposes `.cookies` (`dict[str, str]`) and `.expires` (ISO 8601 string or `None`)
+
+### Changed
+
+- `DEVICE` Tonkeeper fingerprint updated: `appVersion` → `26.04.0`
+- `tonutils` upgraded to **2.1.0**
+- Minimum Python version lowered to **3.10** (previously 3.12)
+
+---
+
+## [2026.1.0] — 2026-03-25
+
+### Added
+
+**Giveaways**
+
+- `giveaway_stars(channel, winners, amount)` — Stars giveaway; 1–5 winners, 500–1 000 000 stars each
+- `giveaway_premium(channel, winners, months)` — Premium giveaway; 1–24 000 winners, 3/6/12 months each
+- `StarsGiveawayResult`, `PremiumGiveawayResult` result types
+
+**Telegram Ads**
+
+- `recharge_ads(account, amount)` — top up a Telegram Ads account; 1–1 000 000 000 TON
+- `AdsRechargeResult` result type
+
+**Marketplace**
+
+- `search_usernames(query?, sort?, filter?, offset_id?)` — search Fragment usernames; `sort`: `price_desc / price_asc / listed / ending`, `filter`: `auction / sale / sold`
+- `search_numbers(query?, sort?, filter?, offset_id?)` — search Fragment anonymous numbers; same `sort` / `filter` / pagination semantics
+- `search_gifts(query?, collection?, sort?, filter?, view?, attr?, offset?)` — search Fragment gifts; `attr` accepts `{"Model": ["Foosball"], "Backdrop": ["Celtic Blue"]}`
+- `UsernamesResult`, `NumbersResult`, `GiftsResult` result types
+
+**Anonymous numbers**
+
+- `get_login_code(number)` — fetch the current pending login code
+- `toggle_login_codes(number, can_receive)` — enable or disable login code delivery
+- `terminate_sessions(number)` — terminate all active Telegram sessions (two-step flow handled internally)
+- `LoginCodeResult`, `TerminateSessionsResult` result types; `AnonymousNumberError` exception
+
+**Raw API**
+
+- `FragmentClient.call(method, data, *, page_url)` — raw request to any Fragment API method
+- `FRAGMENT_BASE_URL` constant — base URL shared across all page constants and headers
+
+**Examples**
+
+- `examples/client/` — `wallet_info.py` (wallet info), `raw_api_call.py` (raw API call)
+- `examples/numbers/` — `manage_number.py` (login code fetch, session termination)
+- `examples/auctions/` — `search_usernames.py`, `search_numbers.py`, `search_gifts.py` (marketplace search with pagination)
+- `examples/purchase/` — `send_stars.py`, `send_premium.py`, `topup_ton_balance.py`, `run_stars_giveaway.py`, `run_premium_giveaway.py`, `recharge_ads_balance.py`
+
+### Changed
+
+- All result types now expose a unified `amount` field (`months` and `stars` removed)
+- `__repr__` includes the unit — `3 months`, `500 stars`, etc.
+- `timestamp` removed from all result dataclasses
+- All page URL constants built from `FRAGMENT_BASE_URL`;
+- `TransactionError` includes an SSL hint; `DUPLICATE_SEQNO` variant auto-retried up to 2 times (2 s apart)
+- Error messages rewritten: "what happened → why → what to do"
+
+---
+
+## [2026.0.2] — 2026-03-20
+
+### Added
+
+- `timeout` parameter on `FragmentClient` (default `30.0` s) — passed through to every HTTP request
+
+### Changed
+
+- Cookie validation: narrowed type internally so no `# type: ignore` is needed in `FragmentClient.__init__`
+- `WALLET_CLASSES` typed as `dict[str, Any]` so mypy resolves `from_mnemonic` correctly
+- All four `examples/` files updated to `async with FragmentClient`, f-strings, and aligned error messages
+- README usage section rewritten with a single comprehensive `async with` example
+
+### Fixed
+
+- mypy: missing return path in `process_transaction` after retry loop
+- mypy: `cookies` union-attr error in `FragmentClient.__init__`
+
+---
+
+## [2026.0.1] — 2026-03-16
+
+### Added
+
+- Initial stable release of `pyfragment`
+- `FragmentClient` — async client for the Fragment.com API with context manager support (`async with`)
+- `purchase_premium(username, months)` — purchase Telegram Premium for any user (3, 6, or 12 months)
+- `purchase_stars(username, amount)` — send Telegram Stars to any user (50–1,000,000)
+- `topup_ton(username, amount)` — top up TON Ads balance (1–1,000,000,000 TON)
+- `get_wallet()` — fetch wallet address and balance
+- Support for TON wallet versions `V4R2` and `V5R1`
+- Structured exception hierarchy (`FragmentError`, `ConfigurationError`, `CookieError`, etc.)
+- `py.typed` marker — full PEP 561 typing support for type-checkers
+- `__repr__` on all result types for readable debug output
+
+[2026.3.2]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.3.2
+[2026.3.1]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.3.1
+[2026.3.0]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.3.0
+[2026.2.3]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.2.3
+[2026.2.2]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.2.2
+[2026.2.1]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.2.1
+[2026.2.0]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.2.0
+[2026.1.0]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.1.0
+[2026.0.2]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.0.2
+[2026.0.1]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.0.1

CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to pyfragment
+
+## Development setup
+
+```bash
+git clone https://github.com/bohd4nx/pyfragment.git
+cd pyfragment
+pip install -e ".[dev]"
+```
+
+## Running checks
+
+```bash
+# Lint and format
+ruff check . --fix && ruff format .
+
+# Type check
+mypy . --explicit-package-bases
+
+# Tests
+pytest
+```
+
+All three must pass before opening a PR.
+
+## Project structure
+
+```
+pyfragment/
+  client.py           — FragmentClient (public entry point)
+  enums.py            — ApiProvider, PaymentMethod, WalletVersion
+  exceptions.py       — exception hierarchy
+  core/               — constants, validation helpers
+  domains/            — one package per feature domain
+    ads/              — recharge_ads, topup_gram
+    anonymous_numbers/— get_login_code, toggle_login_codes, terminate_sessions
+    giveaways/        — giveaway_stars, giveaway_premium
+    marketplace/      — search_usernames, search_numbers, search_gifts
+    purchases/        — purchase_stars, purchase_premium
+  services/           — shared infrastructure services
+    cookies/          — browser cookie extraction (models + service)
+    tonapi/           — wallet info, transaction signing (tonapi/toncenter)
+tests/                — unit tests (pytest)
+examples/             — runnable usage examples (excluded from CI)
+```
+
+## Conventions
+
+- All public async methods live on `FragmentClient` and delegate to a domain service.
+- Domain functions receive a `FragmentClient` instance, never raw HTTP clients.
+- Patch targets in tests use the module where the name is **defined**, e.g. `pyfragment.services.tonapi.transaction._make_ton_client`.
+- Versioning follows [CalVer](https://calver.org/): `YYYY.MINOR.MICRO`. Bump in `pyproject.toml`; tag as `vYYYY.MINOR.MICRO`.
+
+## Pull requests
+
+- Keep PRs focused — one feature or fix per PR.
+- Update `CHANGELOG.md` under `[Unreleased]`.
+- Add or update tests for any changed behaviour.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bohd4nx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,187 +1,65 @@
 <div align="center">
-  <img src="fragment.svg" alt="Fragment Logo" width="120" height="120" style="border-radius: 24px;">
+  <img src="https://www.bohd4n.dev/assets/projects/pyfragment.svg" alt="pyfragment" width="96" height="96" style="border-radius: 20px;"><br><br>
 
-  <h1 style="margin-top: 24px;">💎 Fragment API by @bohd4nx</h1>
+# pyfragment
 
-  <p style="font-size: 18px; margin-bottom: 24px;">
-    <b>Automate TON topups, Telegram Premium purchases, and Stars transactions via Fragment.com</b>
-  </p>
+[![PyPI](https://img.shields.io/pypi/v/pyfragment?style=flat&color=blue&label=PyPI)](https://pypi.org/project/pyfragment/)
+[![Downloads](https://img.shields.io/pepy/dt/pyfragment?style=flat&color=blue&label=Downloads)](https://pepy.tech/projects/pyfragment)
+[![Python](https://img.shields.io/pypi/pyversions/pyfragment?style=flat&color=blue&label=Python)](https://python.org)
+[![Tests](https://img.shields.io/github/actions/workflow/status/bohd4nx/pyfragment/ci.yml?style=flat&label=Tests&logo=github)](https://github.com/bohd4nx/pyfragment/actions)
+[![License](https://img.shields.io/github/license/bohd4nx/pyfragment?style=flat&color=blue&label=License)](LICENSE)
 
-[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white)](https://python.org)
-[![tonutils](https://img.shields.io/badge/tonutils-2.0.0-0098EA?style=flat&logo=ton&logoColor=white)](https://github.com/nessshon/tonutils)
-[![Stars](https://img.shields.io/github/stars/bohd4nx/FragmentAPI?style=flat&color=yellow)](https://github.com/bohd4nx/FragmentAPI/stargazers)
-[![Issues](https://img.shields.io/github/issues/bohd4nx/FragmentAPI?style=flat&color=red)](https://github.com/bohd4nx/FragmentAPI/issues)
-[![CI](https://img.shields.io/github/actions/workflow/status/bohd4nx/FragmentAPI/tests.yml?style=flat&label=tests&logo=github)](https://github.com/bohd4nx/FragmentAPI/actions)
+Async Python client for the **[Fragment.com](https://fragment.com)** marketplace API.
 
-[Report Bug](https://github.com/bohd4nx/fragmentapi/issues) · [Request Feature](https://github.com/bohd4nx/fragmentapi/issues) · [**Donate TON**](https://app.tonkeeper.com/transfer/UQCppfw5DxWgdVHf3zkmZS8k1mt9oAUYxQLwq2fz3nhO8No5)
+**[Documentation](https://bohd4nx.gitbook.io/pyfragment/)** · **[Examples](https://github.com/bohd4nx/pyfragment/tree/master/examples)**
 
 </div>
 
+> **Disclaimer:** This project is not affiliated with [Fragment](https://fragment.com) or [Telegram](https://telegram.org).
+
+## Installation
+
+```bash
+pip install pyfragment
+```
+
+```bash
+# Latest dev build
+pip install git+https://github.com/bohd4nx/pyfragment.git@dev
+```
+
 ---
 
-## ✨ Features
-
-- 💰 **TON Advertisement Topups** — Send TON directly to Fragment ad accounts (1–1,000,000,000 TON)
-- 👑 **Telegram Premium Gifts** — Purchase Premium subscriptions for any user (3, 6, or 12 months)
-- ⭐ **Telegram Stars Purchases** — Buy Stars and send them to any Telegram user (50–1,000,000 Stars)
-- 🔐 **Multi-wallet support** — Configurable wallet contract version (V4R2 / V5R1)
-
-## 🚀 Quick Start
-
-### 1. Installation
-
-```bash
-git clone https://github.com/bohd4nx/FragmentAPI.git
-cd FragmentAPI
-pip install -r requirements.txt
-```
-
-### 2. Configuration
-
-```bash
-cp .env.example .env
-cp cookies.example.json cookies.json
-```
-
-Edit `.env`:
-
-```env
-# 24-word TON wallet seed phrase
-SEED = word1 word2 word3 ... word24
-
-# API key from @tonapibot on Telegram
-API_KEY = your_tonapi_key_here
-
-# Wallet contract version: V4R2 or V5R1 (default: V5R1)
-WALLET_VERSION = V5R1
-```
-
-### 3. Getting Required Data
-
-#### 🍪 Fragment.com Cookies
-
-**Prerequisites**: Log in to Telegram on Fragment and connect the TON wallet you'll use for payments.
-
-1. Install [Cookie Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) extension
-2. Open [fragment.com](https://fragment.com) and make sure you're logged in
-3. Click the Cookie Editor icon → **Export** → **Header String**
-4. Split the result into the four fields in `cookies.json`:
-
-```json
-{
-  "stel_ssid": "...",
-  "stel_dt": "...",
-  "stel_token": "...",
-  "stel_ton_token": "..."
-}
-```
-
-#### 🔐 TON Wallet Seed Phrase
-
-If you don't have a TON wallet, create one in [Tonkeeper](https://tonkeeper.com) (iOS / Android).  
-Go to **Settings → Backup**, copy the 24 words and paste them into `SEED` in `.env`.
-
-> ⚠️ Never share your seed phrase with anyone. Store it offline.
-
-#### 🔑 TON API Key
-
-1. Go to [tonconsole.com](https://tonconsole.com)
-2. Create an account and log in
-3. Generate a new API key
-4. Paste it into `API_KEY` in `.env`
-
-#### 🔐 Wallet Version
-
-| Version | Use when                                                       |
-| ------- | -------------------------------------------------------------- |
-| `V5R1`  | Default — Tonkeeper / MyTonWallet (wallets created after 2024) |
-| `V4R2`  | Older Tonkeeper wallets                                        |
-
-Not sure? Run this to check which address matches your wallet:
-
-```bash
-python3 -c "
-import asyncio
-from tonutils.clients import TonapiClient
-from tonutils.contracts.wallet import WalletV4R2, WalletV5R1
-from tonutils.types import NetworkGlobalID
-from app.core import config
-
-client = TonapiClient(network=NetworkGlobalID.MAINNET, api_key=config.API_KEY)
-w4, _, _, _ = WalletV4R2.from_mnemonic(client=client, mnemonic=config.SEED)
-w5, _, _, _ = WalletV5R1.from_mnemonic(client=client, mnemonic=config.SEED)
-print('V4R2:', w4.address.to_str(True, True))
-print('V5R1:', w5.address.to_str(True, True))
-"
-```
-
-### 4. Usage
-
-#### Run Examples
-
-```bash
-python main.py
-```
-
-#### Programmatic Usage
+## Quick Start
 
 ```python
 import asyncio
-from app.methods import topup_ton, buy_premium, buy_stars
 
-async def main():
-    # Send 10 TON to @username
-    result = await topup_ton("@username", 10)
-    print(result)
+from pyfragment import FragmentClient
+from pyfragment.enums import PaymentMethod
 
-    # Gift 6 months of Telegram Premium (anonymous — recipient won't see sender)
-    result = await buy_premium("@username", 6, show_sender=False)
-    print(result)
 
-    # Buy 500 Stars for @username
-    result = await buy_stars("@username", 500)
-    print(result)
+async def main() -> None:
+    async with FragmentClient(
+        seed="word1 word2 ... word24",
+        api_key="YOUR_API_KEY",
+        cookies={"stel_ssid": "...", "stel_dt": "...", "stel_token": "...", "stel_ton_token": "..."},
+    ) as client:
+        wallet = await client.get_wallet()
+        print("GRAM: %s | USDT: %s" % (wallet.gram_balance, wallet.usdt_balance))
+
+        stars = await client.purchase_stars("@username", amount=500, payment_method=PaymentMethod.USDT_GRAM)
+        print("Sent %s Stars to %s | tx: %s" % (stars.amount, stars.username, stars.transaction_id))
+
+        premium = await client.purchase_premium("@username", months=6, payment_method=PaymentMethod.GRAM)
+        print("Sent Premium %sm to %s | tx: %s" % (premium.amount, premium.username, premium.transaction_id))
+
 
 asyncio.run(main())
 ```
 
-**Return format** (on success):
-
-```python
-{
-    "success": True,
-    "data": {
-        "transaction_id": "<TL-B ExternalMessage ...>",
-        "username": "@username",
-        "amount": 10,          # or "months" for Premium
-        "timestamp": 1741234567
-    }
-}
-```
-
-**Return format** (on failure):
-
-```python
-{
-    "success": False,
-    "error": "Telegram user '@unknown' was not found on Fragment."
-}
-```
-
-### Supported Operations
-
-| Operation          | Function                                              | Parameters                          | Limits              |
-| ------------------ | ----------------------------------------------------- | ----------------------------------- | ------------------- |
-| **TON Topup**      | `topup_ton(username, amount, show_sender=True)`        | Username, TON amount, show sender   | 1–1,000,000,000 TON |
-| **Premium Gift**   | `buy_premium(username, months, show_sender=True)`      | Username, duration, show sender     | 3, 6, or 12 months  |
-| **Stars Purchase** | `buy_stars(username, amount, show_sender=True)`        | Username, Stars amount, show sender | 50–1,000,000 Stars  |
-
-Usernames can be passed with or without `@`.
-
 <div align="center">
 
-### Made with ❤️ by [@bohd4nx](https://t.me/bohd4nx)
-
-**Star ⭐ this repo if you found it useful!**
+[Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
 
 </div>

SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Report them privately via GitHub's [Security Advisory](https://github.com/bohd4nx/pyfragment/security/advisories/new) feature, or contact the maintainer directly at [@bohd4nx](https://t.me/bohd4nx) on Telegram.
+
+Include:
+
+- A description of the vulnerability and its potential impact.
+- Steps to reproduce or a proof-of-concept.
+- Affected versions.
+
+You will receive a response within 72 hours. Once the fix is released, the advisory will be published.
+
+## Scope
+
+This library handles sensitive credentials (GRAM (ex TON) seed phrases, Fragment session cookies, Tonapi keys). Please treat any finding that could expose or misuse these credentials as high severity.

app/core/__init__.py

@@ -1,44 +0,0 @@
-from app.core.config import config
-from app.core.constants import (
-    ADS_PAGE,
-    BASE_HEADERS,
-    DEVICE,
-    PREMIUM_PAGE,
-    STARS_PAGE,
-    WALLET_CLASSES,
-    WalletVersion,
-)
-from app.core.cookies import load_cookies
-from app.core.exceptions import (
-    ConfigError,
-    CookiesError,
-    FragmentError,
-    HashFetchError,
-    RequestError,
-    TransactionError,
-    UserNotFoundError,
-    WalletError,
-)
-from app.core.logging import logger, setup_logging
-
-__all__ = [
-    "ADS_PAGE",
-    "BASE_HEADERS",
-    "DEVICE",
-    "PREMIUM_PAGE",
-    "STARS_PAGE",
-    "WALLET_CLASSES",
-    "WalletVersion",
-    "ConfigError",
-    "CookiesError",
-    "FragmentError",
-    "HashFetchError",
-    "RequestError",
-    "TransactionError",
-    "UserNotFoundError",
-    "WalletError",
-    "config",
-    "load_cookies",
-    "logger",
-    "setup_logging",
-]

app/core/config.py

@@ -1,46 +0,0 @@
-import logging
-import os
-from pathlib import Path
-
-from dotenv import load_dotenv
-
-from app.core.constants import SUPPORTED_WALLET_VERSIONS, WalletVersion
-from app.core.exceptions import ConfigError
-
-logger = logging.getLogger(__name__)
-
-
-class Config:
-    SEED: str
-    API_KEY: str
-    WALLET_VERSION: WalletVersion
-
-    def __init__(self) -> None:
-        # Load .env if present; env vars already in the process take precedence
-        env_path = Path(__file__).resolve().parents[2] / ".env"
-        if env_path.exists():
-            load_dotenv(env_path)
-
-        missing = [k for k in ("SEED", "API_KEY") if not os.getenv(k, "").strip()]
-        if missing:
-            raise ConfigError(
-                f"Missing required environment variables: {', '.join(missing)}. "
-                "Copy .env.example to .env and fill in SEED and API_KEY."
-            )
-
-        self.SEED = os.getenv("SEED", "").strip()
-        self.API_KEY = os.getenv("API_KEY", "").strip()
-
-        version = os.getenv("WALLET_VERSION", "V5R1").strip().upper()
-        if version not in SUPPORTED_WALLET_VERSIONS:
-            raise ConfigError(
-                f"Unsupported WALLET_VERSION '{version}'. " f"Must be one of: {', '.join(sorted(SUPPORTED_WALLET_VERSIONS))}."
-            )
-        self.WALLET_VERSION: WalletVersion = version  # type: ignore[assignment]
-
-
-config: Config | None = None
-try:
-    config = Config()
-except ConfigError as e:
-    logger.warning("Configuration not loaded: %s", e)

app/core/constants.py

@@ -1,49 +0,0 @@
-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}
-
-# Fragment page URLs
-STARS_PAGE: str = "https://fragment.com/stars/buy"
-PREMIUM_PAGE: str = "https://fragment.com/premium/gift"
-ADS_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",
-}

app/core/cookies.py

@@ -1,32 +0,0 @@
-import json
-import logging
-from pathlib import Path
-from typing import Any
-
-from app.core.exceptions import CookiesError
-
-logger = logging.getLogger(__name__)
-
-_REQUIRED_KEYS = ("stel_ssid", "stel_dt", "stel_token", "stel_ton_token")
-
-
-def load_cookies() -> dict[str, Any]:
-    cookies_path = Path(__file__).resolve().parents[2] / "cookies.json"
-
-    if not cookies_path.exists():
-        raise CookiesError("cookies.json not found. Create it in the project root and paste your Fragment cookies.")
-
-    try:
-        with cookies_path.open("r", encoding="utf-8") as f:
-            cookies = json.load(f)
-    except Exception as exc:
-        raise CookiesError(f"Failed to read cookies.json: {exc}") from exc
-
-    missing = [k for k in _REQUIRED_KEYS if not str(cookies.get(k, "")).strip()]
-    if missing:
-        raise CookiesError(
-            f"cookies.json is missing or has empty values for: {', '.join(missing)}. "
-            "Open Fragment.com in your browser, copy fresh cookies, and update the file."
-        )
-
-    return cookies

app/core/exceptions.py

@@ -1,42 +0,0 @@
-__all__ = [
-    "ConfigError",
-    "CookiesError",
-    "FragmentError",
-    "HashFetchError",
-    "RequestError",
-    "TransactionError",
-    "UserNotFoundError",
-    "WalletError",
-]
-
-
-class FragmentError(Exception):
-    """Base exception for all Fragment API errors."""
-
-
-class ConfigError(FragmentError):
-    """Raised when .env is missing or required keys are absent."""
-
-
-class CookiesError(FragmentError):
-    """Raised when cookies.json is missing, unreadable, or has empty required fields."""
-
-
-class HashFetchError(FragmentError):
-    """Raised when the Fragment API hash cannot be fetched from the page."""
-
-
-class UserNotFoundError(FragmentError):
-    """Raised when the target Telegram user is not found on Fragment."""
-
-
-class WalletError(FragmentError):
-    """Raised for TON wallet issues (connection, balance, account info)."""
-
-
-class TransactionError(FragmentError):
-    """Raised when a TON transaction fails to build or broadcast."""
-
-
-class RequestError(FragmentError):
-    """Raised when a Fragment API response cannot be parsed."""

app/core/logging.py

@@ -1,20 +0,0 @@
-import logging
-
-
-def setup_logging() -> None:
-    formatter = logging.Formatter(fmt="[%(asctime)s] - %(levelname)s: %(message)s", datefmt="%d.%m.%y %H:%M:%S")
-
-    console_handler = logging.StreamHandler()
-    console_handler.setLevel(logging.INFO)
-    console_handler.setFormatter(formatter)
-
-    file_handler = logging.FileHandler("FragmentAPI.log", mode="w", encoding="utf-8")
-    file_handler.setLevel(logging.DEBUG)
-    file_handler.setFormatter(formatter)
-    logging.basicConfig(level=logging.DEBUG, handlers=[console_handler, file_handler], force=True)
-
-    logging.getLogger("httpx").setLevel(logging.WARNING)
-    logging.getLogger("httpcore").setLevel(logging.WARNING)
-
-
-logger = logging.getLogger(__name__)

app/methods/__init__.py

@@ -1,5 +0,0 @@
-from app.methods.premium import buy_premium
-from app.methods.stars import buy_stars
-from app.methods.ton import topup_ton
-
-__all__ = ["buy_premium", "buy_stars", "topup_ton"]

app/methods/premium.py

@@ -1,151 +0,0 @@
-import json
-import logging
-import time
-
-import httpx
-
-from app.core import (
-    BASE_HEADERS,
-    DEVICE,
-    PREMIUM_PAGE,
-    FragmentError,
-    UserNotFoundError,
-    load_cookies,
-)
-from app.utils import (
-    execute_transaction_request,
-    get_account_info,
-    get_fragment_hash,
-    parse_json_response,
-    process_transaction,
-)
-
-logger = logging.getLogger(__name__)
-
-# Page-specific headers
-HEADERS: dict[str, str] = {
-    **BASE_HEADERS,
-    "referer": PREMIUM_PAGE,
-    "x-aj-referer": PREMIUM_PAGE,
-}
-
-
-async def search_premium_recipient(
-    client: httpx.AsyncClient,
-    fragment_hash: str,
-    username: str,
-    months: int,
-) -> str:
-    resp = await client.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(
-            f"Telegram user '{username}' was not found on Fragment. "
-            "Make sure the username is correct and the account exists."
-        )
-    return recipient
-
-
-async def init_gift_premium(
-    client: httpx.AsyncClient,
-    fragment_hash: str,
-    recipient: str,
-    months: int,
-) -> str:
-    await client.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 client.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 FragmentError(
-            "Fragment did not return a request ID for this Premium purchase. "
-            "The session may have expired — refresh your cookies."
-        )
-    return req_id
-
-
-async def buy_premium(username: str, months: int, show_sender: bool = True) -> dict:
-    if months not in (3, 6, 12):
-        return {
-            "success": False,
-            "error": "Invalid duration. Choose 3, 6, or 12 months.",
-        }
-
-    try:
-        logger.info("Loading session cookies")
-        cookies = load_cookies()
-
-        logger.info("Fetching Fragment session hash")
-        fragment_hash = await get_fragment_hash(cookies, HEADERS, PREMIUM_PAGE)
-
-        # logger.info("Retrieving TON wallet info")
-        account = await get_account_info()
-
-        async with httpx.AsyncClient(cookies=cookies) as client:
-            logger.info("Searching recipient: %s", username)
-            recipient = await search_premium_recipient(client, fragment_hash, username, months)
-
-            logger.info("Initializing Premium gift request: %s months to %s", months, username)
-            req_id = await init_gift_premium(client, fragment_hash, recipient, months)
-
-            # logger.info("Requesting transaction payload (req_id=%s)", req_id)
-            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(client, HEADERS, account, tx_data, fragment_hash)
-
-        logger.info("Broadcasting transaction to TON blockchain")
-        tx_hash = await process_transaction(transaction)
-        logger.info(
-            "Premium purchase successful: %s months -> %s | tx: %s",
-            months,
-            username,
-            tx_hash,
-        )
-        return {
-            "success": True,
-            "data": {
-                "transaction_id": tx_hash,
-                "username": username,
-                "months": months,
-                "timestamp": int(time.time()),
-            },
-        }
-
-    except FragmentError as exc:
-        logger.error("Premium purchase failed — %s", exc)
-        return {"success": False, "error": str(exc)}
-    except Exception as exc:
-        logger.exception("Unexpected error during Premium purchase")
-        return {"success": False, "error": f"Unexpected error: {exc}"}

app/methods/stars.py

@@ -1,133 +0,0 @@
-import json
-import logging
-import time
-
-import httpx
-
-from app.core import (
-    BASE_HEADERS,
-    DEVICE,
-    STARS_PAGE,
-    FragmentError,
-    UserNotFoundError,
-    load_cookies,
-)
-from app.utils import (
-    execute_transaction_request,
-    get_account_info,
-    get_fragment_hash,
-    parse_json_response,
-    process_transaction,
-)
-
-logger = logging.getLogger(__name__)
-
-# Page-specific headers
-HEADERS: dict[str, str] = {
-    **BASE_HEADERS,
-    "referer": STARS_PAGE,
-    "x-aj-referer": STARS_PAGE,
-}
-
-
-async def search_stars_recipient(
-    client: httpx.AsyncClient,
-    fragment_hash: str,
-    username: str,
-) -> str:
-    resp = await client.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(
-            f"Telegram user '{username}' was not found on Fragment. "
-            "Make sure the username is correct and the account exists."
-        )
-    return recipient
-
-
-async def init_buy_stars(
-    client: httpx.AsyncClient,
-    fragment_hash: str,
-    recipient: str,
-    amount: int,
-) -> str:
-    resp = await client.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 FragmentError(
-            "Fragment did not return a request ID for this Stars purchase. "
-            "The session may have expired — refresh your cookies."
-        )
-    return req_id
-
-
-async def buy_stars(username: str, amount: int, show_sender: bool = True) -> dict:
-    if not isinstance(amount, int) or amount < 50:
-        return {"success": False, "error": "Amount must be an integer >= 50 stars."}
-
-    try:
-        logger.info("Loading session cookies")
-        cookies = load_cookies()
-
-        logger.info("Fetching Fragment session hash")
-        fragment_hash = await get_fragment_hash(cookies, HEADERS, STARS_PAGE)
-
-        # logger.info("Retrieving TON wallet info")
-        account = await get_account_info()
-
-        async with httpx.AsyncClient(cookies=cookies) as client:
-            logger.info("Searching recipient: %s", username)
-            recipient = await search_stars_recipient(client, fragment_hash, username)
-
-            logger.info("Initializing Stars purchase request: %s stars to %s", amount, username)
-            req_id = await init_buy_stars(client, fragment_hash, recipient, amount)
-
-            # logger.info("Requesting transaction payload (req_id=%s)", req_id)
-            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(client, HEADERS, account, tx_data, fragment_hash)
-
-        logger.info("Broadcasting transaction to TON blockchain")
-        tx_hash = await process_transaction(transaction)
-        logger.info(
-            "Stars purchase successful: %s stars -> %s | tx: %s",
-            amount,
-            username,
-            tx_hash,
-        )
-        return {
-            "success": True,
-            "data": {
-                "transaction_id": tx_hash,
-                "username": username,
-                "amount": amount,
-                "timestamp": int(time.time()),
-            },
-        }
-
-    except FragmentError as exc:
-        logger.error("Stars purchase failed — %s", exc)
-        return {"success": False, "error": str(exc)}
-    except Exception as exc:
-        logger.exception("Unexpected error during Stars purchase")
-        return {"success": False, "error": f"Unexpected error: {exc}"}

app/methods/ton.py

@@ -1,132 +0,0 @@
-import json
-import logging
-import time
-
-import httpx
-
-from app.core import (
-    ADS_PAGE,
-    BASE_HEADERS,
-    DEVICE,
-    FragmentError,
-    UserNotFoundError,
-    load_cookies,
-)
-from app.utils import (
-    execute_transaction_request,
-    get_account_info,
-    get_fragment_hash,
-    parse_json_response,
-    process_transaction,
-)
-
-logger = logging.getLogger(__name__)
-
-# Page-specific headers
-HEADERS: dict[str, str] = {
-    **BASE_HEADERS,
-    "referer": ADS_PAGE,
-    "x-aj-referer": ADS_PAGE,
-}
-
-
-async def search_ads_recipient(
-    client: httpx.AsyncClient,
-    fragment_hash: str,
-    username: str,
-) -> str:
-    await client.post(
-        f"https://fragment.com/api?hash={fragment_hash}",
-        headers=HEADERS,
-        data={"mode": "new", "method": "updateAdsTopupState"},
-    )
-    resp = await client.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(
-            f"Telegram user '{username}' was not found on Fragment. "
-            "Make sure the username is correct and the account exists."
-        )
-    return recipient
-
-
-async def init_ads_topup(
-    client: httpx.AsyncClient,
-    fragment_hash: str,
-    recipient: str,
-    amount: int,
-) -> str:
-    resp = await client.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 FragmentError(
-            "Fragment did not return a request ID for this TON topup. " "The session may have expired — refresh your cookies."
-        )
-    return req_id
-
-
-async def topup_ton(username: str, amount: int, show_sender: bool = True) -> dict:
-    if not isinstance(amount, int) or amount < 1:
-        return {"success": False, "error": "Amount must be an integer >= 1 TON."}
-
-    try:
-        logger.info("Loading session cookies")
-        cookies = load_cookies()
-
-        logger.info("Fetching Fragment session hash")
-        fragment_hash = await get_fragment_hash(cookies, HEADERS, ADS_PAGE)
-
-        # logger.info("Retrieving TON wallet info")
-        account = await get_account_info()
-
-        async with httpx.AsyncClient(cookies=cookies) as client:
-            logger.info("Searching recipient: %s", username)
-            recipient = await search_ads_recipient(client, fragment_hash, username)
-
-            logger.info("Initializing topup request: %s TON to %s", amount, username)
-            req_id = await init_ads_topup(client, fragment_hash, recipient, amount)
-
-            # logger.info("Requesting transaction payload (req_id=%s)", req_id)
-            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(client, HEADERS, account, tx_data, fragment_hash)
-
-        logger.info("Broadcasting transaction to TON blockchain")
-        tx_hash = await process_transaction(transaction)
-        logger.info("TON topup successful: %s TON -> %s | tx: %s", amount, username, tx_hash)
-        return {
-            "success": True,
-            "data": {
-                "transaction_id": tx_hash,
-                "username": username,
-                "amount": amount,
-                "timestamp": int(time.time()),
-            },
-        }
-
-    except FragmentError as exc:
-        logger.error("TON topup failed — %s", exc)
-        return {"success": False, "error": str(exc)}
-    except Exception as exc:
-        logger.exception("Unexpected error during TON topup")
-        return {"success": False, "error": f"Unexpected error: {exc}"}

app/utils/__init__.py

@@ -1,14 +0,0 @@
-from app.utils.client import execute_transaction_request, parse_json_response
-from app.utils.decoder import clean_decode
-from app.utils.hash import get_fragment_hash
-from app.utils.wallet import get_account_info, link_wallet, process_transaction
-
-__all__ = [
-    "clean_decode",
-    "execute_transaction_request",
-    "get_account_info",
-    "get_fragment_hash",
-    "link_wallet",
-    "parse_json_response",
-    "process_transaction",
-]

app/utils/client.py

@@ -1,39 +0,0 @@
-import logging
-from typing import Any
-
-import httpx
-
-from app.core import RequestError, WalletError
-from app.utils.wallet import link_wallet
-
-logger = logging.getLogger(__name__)
-
-
-def parse_json_response(response: httpx.Response, context: str) -> dict[str, Any]:
-    try:
-        return response.json()
-    except Exception as exc:
-        raise RequestError(f"Fragment API returned an unparseable response for '{context}': {exc}") from exc
-
-
-async def execute_transaction_request(
-    client: httpx.AsyncClient,
-    headers: dict,
-    account: dict[str, Any],
-    tx_data: dict[str, Any],
-    fragment_hash: str,
-) -> dict[str, Any]:
-    url = f"https://fragment.com/api?hash={fragment_hash}"
-
-    resp = await client.post(url, headers=headers, data=tx_data)
-    transaction = parse_json_response(resp, tx_data.get("method", "transaction"))
-
-    if transaction.get("need_verify"):
-        if not await link_wallet(client, headers, account, fragment_hash):
-            raise WalletError(
-                "Failed to link your TON wallet to Fragment. " "Make sure the wallet matching your cookies is used."
-            )
-        resp = await client.post(url, headers=headers, data=tx_data)
-        transaction = parse_json_response(resp, tx_data.get("method", "transaction"))
-
-    return transaction

app/utils/decoder.py

@@ -1,36 +0,0 @@
-import base64
-import logging
-
-from pytoniq_core import Cell
-
-logger = logging.getLogger(__name__)
-
-
-# OLD decoder (manual base64 + regex, kept for reference):
-#
-# import re, string
-# def clean_decode(payload: str) -> str:
-#     s = re.sub(r'[^A-Za-z0-9+/=]', '', payload.strip())
-#     s += '=' * (-len(s) % 4)
-#     text = base64.b64decode(s).decode('utf-8', errors='ignore')
-#     text = ''.join(c for c in text if c in string.printable or c.isspace())
-#     match = re.search(r'([0-9]*\s*Telegram .*?Ref#[A-Za-z0-9]+)', text, re.S)
-#     return match.group(1).strip() if match else text.strip()
-
-
-def clean_decode(payload: str) -> str:
-    # Pad and decode base64 → BOC bytes
-    s = payload.strip()
-    if not s:
-        return ""
-    s += "=" * (-len(s) % 4)
-    boc = base64.b64decode(s)
-
-    # Parse BOC cell and read snake-encoded text (skipping 32-bit op prefix)
-    cell = Cell.one_from_boc(boc)
-    sl = cell.begin_parse()
-    sl.load_uint(32)  # op code — always 0 for text comment
-    result = sl.load_snake_string().strip()
-
-    logger.debug("Payload: %s -> %s", payload, result.replace("\n", " "))
-    return result

app/utils/hash.py

@@ -1,57 +0,0 @@
-import logging
-import re
-from typing import Any
-
-import httpx
-
-from app.core import HashFetchError
-
-logger = logging.getLogger(__name__)
-
-
-async def get_fragment_hash(
-    cookies: dict[str, Any],
-    headers: dict[str, str],
-    page_url: str,
-) -> str:
-    # Must look like a real browser navigation — not an XHR — otherwise Fragment
-    # returns JSON (no hash in it) instead of full 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 client:
-        response = await client.get(page_url, headers=page_headers)
-
-    if response.status_code != 200:
-        raise HashFetchError(
-            f"Fragment returned HTTP {response.status_code} for {page_url}. "
-            "Check that your cookies are valid and not expired."
-        )
-
-    match = re.search(r"(?:https://fragment\.com)?/api\?hash=([a-f0-9]+)", response.text)
-    if not match:
-        raise HashFetchError(
-            f"Fragment hash not found in the page source of {page_url}. "
-            "The page structure may have changed or you are not logged in."
-        )
-
-    return match.group(1)

app/utils/wallet.py

@@ -1,107 +0,0 @@
-import base64
-import json
-import logging
-from typing import Any
-
-import httpx
-from tonutils.clients import TonapiClient
-from tonutils.types import NetworkGlobalID
-
-from app.core import DEVICE, WALLET_CLASSES, TransactionError, WalletError, config
-from app.utils.decoder import clean_decode
-
-logger = logging.getLogger(__name__)
-
-
-def initialize_ton_client() -> TonapiClient:
-    return TonapiClient(network=NetworkGlobalID.MAINNET, api_key=config.API_KEY)
-
-
-async def process_transaction(transaction_data: dict) -> str:
-    logger.debug("transaction_data: %s", transaction_data)
-
-    if "transaction" not in transaction_data or "messages" not in transaction_data["transaction"]:
-        raise TransactionError(
-            "Fragment returned an invalid transaction payload. "
-            "The API response is missing expected 'transaction.messages' data."
-        )
-
-    # 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 initialize_ton_client() as client:
-        wallet_cls = WALLET_CLASSES[config.WALLET_VERSION]
-        wallet, _, _, _ = wallet_cls.from_mnemonic(client=client, mnemonic=config.SEED)
-
-        # Check balance before broadcasting
-        try:
-            await wallet.refresh()
-            balance_ton = wallet.balance / 1_000_000_000
-            if balance_ton < 0.056:
-                raise WalletError(f"TON wallet balance is too low: {balance_ton:.2f} TON. " "Minimum required is 0.056 TON.")
-        except WalletError:
-            raise
-        except Exception as exc:
-            raise WalletError(f"Wallet balance check failed: {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,
-            )
-            tx_hash = result.normalized_hash
-            return tx_hash
-        except (WalletError, TransactionError):
-            raise
-        except Exception as exc:
-            raise TransactionError(f"Transaction broadcast failed: {exc}") from exc
-
-
-async def get_account_info() -> dict[str, Any]:
-    async with initialize_ton_client() as client:
-        try:
-            wallet_cls = WALLET_CLASSES[config.WALLET_VERSION]
-            wallet, pub_key, _, _ = wallet_cls.from_mnemonic(client=client, mnemonic=config.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(f"Failed to retrieve wallet account info: {exc}") from exc
-
-
-async def link_wallet(
-    client: httpx.AsyncClient,
-    headers: dict,
-    account: dict[str, Any],
-    fragment_hash: str,
-) -> bool:
-    resp = await client.post(
-        f"https://fragment.com/api?hash={fragment_hash}",
-        headers=headers,
-        data={
-            "account": json.dumps(account),
-            "device": DEVICE,
-            "method": "linkWallet",
-        },
-    )
-    result = resp.json()
-
-    if result.get("ok"):
-        return True
-
-    if "transaction" in result:
-        try:
-            await process_transaction(result)
-            return True
-        except (TransactionError, WalletError):
-            return False
-
-    return False

cookies.example.json

@@ -1,6 +0,0 @@
-{
-  "stel_ssid": "",
-  "stel_dt": "",
-  "stel_token": "",
-  "stel_ton_token": ""
-}

examples/auctions/search_gifts.py

@@ -0,0 +1,53 @@
+"""
+Example: search the Fragment gifts marketplace.
+
+collection filters by gift type slug (e.g. "plushpepe", "swisswatch").
+sort can be "price_desc", "price_asc", "listed", or "ending".
+filter can be "", "auction", "sale", or "sold".
+Use next_offset for pagination.
+"""
+
+import asyncio
+import json
+
+from pyfragment import FragmentClient, GiftsResult
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+QUERY = ""  # search text — or omit for all
+COLLECTION = "plushpepe"  # gift collection slug — or omit for all
+SORT = "price_desc"  # "price_desc", "price_asc", "listed", "ending" — or omit
+FILTER = ""  # "", "auction", "sale", "sold" — or omit
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        result: GiftsResult = await client.search_gifts(QUERY, collection=COLLECTION, sort=SORT, filter=FILTER)
+
+        print(f"Found {len(result.items)} result(s):")
+        print(json.dumps(result.items, indent=2))
+
+        if result.next_offset:
+            print(f"\nMore results available — next page offset: {result.next_offset}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/auctions/search_numbers.py

@@ -0,0 +1,51 @@
+"""
+Example: search the Fragment marketplace for anonymous Telegram numbers.
+
+sort can be "price_desc", "price_asc", "listed", or "ending".
+filter can be "", "auction", "sale", or "sold".
+Use next_offset_id for pagination.
+"""
+
+import asyncio
+import json
+
+from pyfragment import FragmentClient, NumbersResult
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+QUERY = "888"  # search term — or omit for all
+SORT = "price_asc"  # "price_desc", "price_asc", "listed", "ending" — or omit
+FILTER = ""  # "", "auction", "sale", "sold" — or omit
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        result: NumbersResult = await client.search_numbers(QUERY, sort=SORT, filter=FILTER)
+
+        print(f"Found {len(result.items)} result(s):")
+        print(json.dumps(result.items, indent=2))
+
+        if result.next_offset_id:
+            print(f"\nMore results available — next page offset: {result.next_offset_id}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/auctions/search_usernames.py

@@ -0,0 +1,51 @@
+"""
+Example: search the Fragment marketplace for Telegram usernames.
+
+sort can be "price_desc", "price_asc", "listed", or "ending".
+filter can be "", "auction", "sale", or "sold".
+Use next_offset_id for pagination.
+"""
+
+import asyncio
+import json
+
+from pyfragment import FragmentClient, UsernamesResult
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+QUERY = "durov"  # search term
+SORT = "price_desc"  # "price_desc", "price_asc", "listed", "ending" — or omit
+FILTER = "auction"  # "", "auction", "sale", "sold" — or omit
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        result: UsernamesResult = await client.search_usernames(QUERY, sort=SORT, filter=FILTER)
+
+        print(f"Found {len(result.items)} result(s):")
+        print(json.dumps(result.items, indent=2))
+
+        if result.next_offset_id:
+            print(f"\nMore results available — next page offset: {result.next_offset_id}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/client/get_cookies.py

@@ -0,0 +1,33 @@
+"""
+Example: extract Fragment cookies directly from your browser.
+
+get_cookies_from_browser() reads the Fragment session cookies from a locally
+installed browser — no manual copy-paste required.
+
+Supported browsers: arc, brave, chrome, chromium, chromium_based, edge,
+                    firefox, firefox_based, librewolf, opera, opera_gx,
+                    safari, vivaldi.
+
+The returned CookieResult.cookies dict can be passed directly to FragmentClient.
+"""
+
+from pyfragment import CookieError, get_cookies_from_browser
+
+
+def main() -> None:
+    try:
+        result = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+    except CookieError as e:
+        print(f"Could not read cookies: {e}")
+        return
+
+    print(f"Cookies expire: {result.expires}")
+    print(f"Keys found: {list(result.cookies.keys())}")
+
+    # Pass the extracted cookies directly to FragmentClient
+    # async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=result.cookies) as client:
+    #     ...
+
+
+if __name__ == "__main__":
+    main()

examples/client/raw_api_call.py

@@ -0,0 +1,48 @@
+"""
+Example: send a raw request to any Fragment API method.
+
+Use client.call() when you need to access a method that is not yet
+wrapped by the library, or to inspect raw API responses directly.
+
+page_url is optional — only set it when the target method belongs to a
+specific Fragment page (Fragment derives the API hash per page).
+Defaults to the Fragment base URL.
+"""
+
+import asyncio
+
+from pyfragment import FragmentClient
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+METHOD = "anyFragmentMethod"  # replace with the actual method name
+DATA = {"key": "value"}  # replace with the actual request payload
+PAGE_URL = "https://fragment.com/stars/buy"  # replace with the matching Fragment page (optional)
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        result = await client.call(METHOD, DATA, page_url=PAGE_URL)
+        print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/client/wallet_info.py

@@ -0,0 +1,44 @@
+"""
+Example: fetch wallet address, state, and separate GRAM (ex TON)/USDT balances.
+
+Cookies can be passed as a dict or as a JSON string.
+wallet_version defaults to "V5R1" — change to "V4R2" for older wallets.
+api_provider defaults to "tonapi" (tonconsole.com) — pass "toncenter" to use t.me/toncenter instead.
+"""
+
+import asyncio
+
+from pyfragment import FragmentClient
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        wallet = await client.get_wallet()
+        print(f"Address: {wallet.address}")
+        print(f"State:   {wallet.state}")
+        print(f"Balance: {wallet.gram_balance} GRAM (ex TON)")
+        print(f"Balance: {wallet.usdt_balance} USDT")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/numbers/manage_number.py

@@ -0,0 +1,54 @@
+"""
+Example: manage an anonymous Telegram number — read login code and terminate sessions.
+
+Use get_login_code() to fetch the current pending login code for your number.
+Use toggle_login_codes() to enable or disable receiving codes.
+Use terminate_sessions() to forcefully end all active Telegram sessions.
+"""
+
+import asyncio
+
+from pyfragment import AnonymousNumberError, FragmentClient
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+NUMBER = "+88888888888"
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        # Fetch the latest login code
+        result = await client.get_login_code(NUMBER)
+        if result.code:
+            print(f"Login code for {result.number}: {result.code} ({result.active_sessions} active session(s))")
+        else:
+            print(f"No pending login code for {result.number} ({result.active_sessions} active session(s))")
+
+        # Terminate all active sessions
+        try:
+            terminated = await client.terminate_sessions(NUMBER)
+            print(f"Sessions terminated for {terminated.number}" + (f": {terminated.message}" if terminated.message else ""))
+        except AnonymousNumberError as e:
+            print(f"Could not terminate sessions: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/purchase/premium_giveaway.py

@@ -0,0 +1,62 @@
+"""
+Example: run a Telegram Premium giveaway for a channel.
+
+winners must be an integer between 1 and 24 000.
+months (Premium duration per winner) must be 3, 6, or 12.
+Channel can be "@channel", "channel", or "https://t.me/channel".
+"""
+
+import asyncio
+
+from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.enums import PaymentMethod
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+CHANNEL = "https://t.me/channel"
+WINNERS = 10  # 1–24 000
+MONTHS = 3  # 3, 6 or 12
+PAYMENT_METHOD = PaymentMethod.GRAM  # GRAM, USDT_GRAM, USDT_ETH, USDT_POL, USDC_ETH, USDC_BASE, USDC_POL
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        try:
+            result = await client.giveaway_premium(
+                CHANNEL,
+                winners=WINNERS,
+                months=MONTHS,
+                payment_method=PAYMENT_METHOD,
+            )
+        except UserNotFoundError:
+            print(f"Channel {CHANNEL} was not found on fragment.com — check the username and try again.")
+            return
+        except ConfigurationError as e:
+            print(f"Invalid argument: {e}")
+            return
+
+    print(
+        f"Premium giveaway created for {result.channel} — {result.winners} winner(s) × {result.amount} months each | tx: {result.transaction_id}"
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/purchase/purchase_premium.py

@@ -0,0 +1,59 @@
+"""
+Example: purchase Telegram Premium for a user.
+
+Supported durations: 3, 6, or 12 months.
+Set show_sender=False to send anonymously.
+Username can be "@username", "username", or "https://t.me/username".
+"""
+
+import asyncio
+
+from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.enums import PaymentMethod
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+USERNAME = "https://t.me/username"
+MONTHS = 3  # 3, 6 or 12
+PAYMENT_METHOD = PaymentMethod.GRAM  # GRAM, USDT_GRAM, USDT_ETH, USDT_POL, USDC_ETH, USDC_BASE, USDC_POL
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        try:
+            result = await client.purchase_premium(
+                USERNAME,
+                months=MONTHS,
+                show_sender=True,
+                payment_method=PAYMENT_METHOD,
+            )
+        except UserNotFoundError:
+            print(f"User {USERNAME} was not found on fragment.com — check the username and try again.")
+            return
+        except ConfigurationError as e:
+            print(f"Invalid argument: {e}")
+            return
+
+    print(f"{result.amount} months of Premium successfully sent to {result.username} | tx: {result.transaction_id}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/purchase/purchase_stars.py

@@ -0,0 +1,59 @@
+"""
+Example: purchase Telegram Stars for a user.
+
+Amount must be an integer between 50 and 10 000 000.
+Set show_sender=False to send anonymously.
+Username can be "@username", "username", or "https://t.me/username".
+"""
+
+import asyncio
+
+from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.enums import PaymentMethod
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+USERNAME = "https://t.me/username"
+AMOUNT = 500  # 50–10 000 000 stars
+PAYMENT_METHOD = PaymentMethod.USDT_GRAM  # GRAM, USDT_GRAM, USDT_ETH, USDT_POL, USDC_ETH, USDC_BASE, USDC_POL
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        try:
+            result = await client.purchase_stars(
+                USERNAME,
+                amount=AMOUNT,
+                show_sender=True,
+                payment_method=PAYMENT_METHOD,
+            )
+        except UserNotFoundError:
+            print(f"User {USERNAME} was not found on fragment.com — check the username and try again.")
+            return
+        except ConfigurationError as e:
+            print(f"Invalid argument: {e}")
+            return
+
+    print(f"{result.amount} Stars successfully sent to {result.username} | tx: {result.transaction_id}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/purchase/recharge_ads_balance.py

@@ -0,0 +1,56 @@
+"""
+Example: recharge your own Telegram Ads account with GRAM (ex TON).
+
+Amount must be an integer between 1 and 1 000 000 000 GRAM (ex TON).
+Your wallet must satisfy the current minimum GRAM (ex TON) threshold and transaction cost.
+"""
+
+import asyncio
+
+from pyfragment import (
+    AdsRechargeResult,
+    ConfigurationError,
+    FragmentClient,
+    WalletError,
+)
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+ACCOUNT = "@mychannel"  # channel or bot username linked to your Telegram Ads account
+AMOUNT = 10  # 1–1 000 000 000 GRAM (ex TON)
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        try:
+            result: AdsRechargeResult = await client.recharge_ads(ACCOUNT, amount=AMOUNT)
+        except WalletError as e:
+            print(f"Wallet error — insufficient balance or misconfiguration: {e}")
+            return
+        except ConfigurationError as e:
+            print(f"Invalid argument: {e}")
+            return
+
+    print(f"{result.amount} GRAM (ex TON) recharged to Ads account {ACCOUNT} | tx: {result.transaction_id}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/purchase/stars_giveaway.py

@@ -0,0 +1,62 @@
+"""
+Example: run a Telegram Stars giveaway for a channel.
+
+winners must be an integer between 1 and 15.
+amount (stars per winner) must be an integer between 500 and 1 000 000.
+Channel can be "@channel", "channel", or "https://t.me/channel".
+"""
+
+import asyncio
+
+from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.enums import PaymentMethod
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+CHANNEL = "https://t.me/channel"
+WINNERS = 3  # 1–15
+AMOUNT = 1000  # 500–1 000 000 stars per winner
+PAYMENT_METHOD = PaymentMethod.USDT_GRAM  # GRAM, USDT_GRAM, USDT_ETH, USDT_POL, USDC_ETH, USDC_BASE, USDC_POL
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        try:
+            result = await client.giveaway_stars(
+                CHANNEL,
+                winners=WINNERS,
+                amount=AMOUNT,
+                payment_method=PAYMENT_METHOD,
+            )
+        except UserNotFoundError:
+            print(f"Channel {CHANNEL} was not found on fragment.com — check the username and try again.")
+            return
+        except ConfigurationError as e:
+            print(f"Invalid argument: {e}")
+            return
+
+    print(
+        f"Stars giveaway created for {result.channel} — {result.winners} winner(s) × {result.amount} stars each | tx: {result.transaction_id}"
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/purchase/topup_gram_balance.py

@@ -0,0 +1,61 @@
+"""
+Example: top up GRAM (ex TON) to a recipient's Telegram balance.
+
+For adding GRAM (ex TON) to a Telegram Ads account, use recharge_ads() instead.
+
+Amount must be an integer between 1 and 1 000 000 000 GRAM (ex TON).
+Your wallet must satisfy the current minimum GRAM (ex TON) threshold and transaction cost.
+"""
+
+import asyncio
+
+from pyfragment import (
+    ConfigurationError,
+    FragmentClient,
+    UserNotFoundError,
+    WalletError,
+)
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_API_KEY"  # tonconsole.com (tonapi, default) or t.me/toncenter
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome").cookies  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+USERNAME = "@username"
+AMOUNT = 10  # 1–1 000 000 000 GRAM (ex TON)
+
+
+async def main() -> None:
+    async with FragmentClient(
+        seed=SEED,
+        api_key=API_KEY,
+        cookies=COOKIES,
+        wallet_version="V5R1",  # or "V4R2", "HighloadV2", "HighloadV3R1"
+        api_provider="tonapi",  # or "toncenter"
+    ) as client:
+        try:
+            result = await client.topup_gram(USERNAME, amount=AMOUNT, show_sender=True)
+        except UserNotFoundError:
+            print(f"User {USERNAME} was not found on fragment.com — check the username and try again.")
+            return
+        except WalletError as e:
+            print(f"Wallet error — insufficient balance or misconfiguration: {e}")
+            return
+        except ConfigurationError as e:
+            print(f"Invalid argument: {e}")
+            return
+
+    print(f"{result.amount} GRAM (ex TON) successfully topped up for {result.username} | tx: {result.transaction_id}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fragment.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 512 512" width="512" height="512" style="width: 100%; height: 100%; transform: translate3d(0,0,0); content-visibility: visible;" preserveAspectRatio="xMidYMid meet"><defs><clipPath id="__lottie_element_2"><rect width="512" height="512" x="0" y="0"></rect></clipPath><clipPath id="__lottie_element_4"><path d="M0,0 L100,0 L100,100 L0,100z"></path></clipPath></defs><g clip-path="url(#__lottie_element_2)"><g clip-path="url(#__lottie_element_4)" style="display: block;" transform="matrix(5.119999885559082,0,0,5.119999885559082,0,0)" opacity="1"><g style="display: block;" transform="matrix(1.333299994468689,0,0,1.333299994468689,0,0)" opacity="1"><g opacity="1" transform="matrix(1,0,0,1,0,0)"><g opacity="1" transform="matrix(1,0,0,1,0,0)"><path fill="rgb(30,40,51)" fill-opacity="1" d=" M47.31999969482422,5.619999885559082 C47.31999969482422,5.619999885559082 27.68000030517578,5.619999885559082 27.68000030517578,5.619999885559082 C15.5,5.619999885559082 5.619999885559082,15.5 5.619999885559082,27.68000030517578 C5.619999885559082,27.68000030517578 5.619999885559082,47.31999969482422 5.619999885559082,47.31999969482422 C5.619999885559082,59.5 15.5,69.37999725341797 27.68000030517578,69.37999725341797 C27.68000030517578,69.37999725341797 47.31999969482422,69.37999725341797 47.31999969482422,69.37999725341797 C59.5,69.37999725341797 69.37999725341797,59.5 69.37999725341797,47.31999969482422 C69.37999725341797,47.31999969482422 69.37999725341797,27.68000030517578 69.37999725341797,27.68000030517578 C69.37999725341797,15.5 59.5,5.619999885559082 47.31999969482422,5.619999885559082 C47.31999969482422,5.619999885559082 47.31999969482422,5.619999885559082 47.31999969482422,5.619999885559082z"></path></g><g opacity="1" transform="matrix(1,0,0,1,0,0)"><path fill="rgb(255,255,255)" fill-opacity="1" d=" M36.349998474121094,32.79999923706055 C36.349998474121094,32.79999923706055 21.1299991607666,25.940000534057617 21.1299991607666,25.940000534057617 C20.020000457763672,25.450000762939453 20.389999389648438,23.790000915527344 21.600000381469727,23.790000915527344 C21.600000381469727,23.790000915527344 53.41999816894531,23.790000915527344 53.41999816894531,23.790000915527344 C54.630001068115234,23.790000915527344 54.9900016784668,25.440000534057617 53.880001068115234,25.940000534057617 C53.880001068115234,25.940000534057617 38.66999816894531,32.79999923706055 38.66999816894531,32.79999923706055 C37.939998626708984,33.130001068115234 37.09000015258789,33.130001068115234 36.36000061035156,32.79999923706055 C36.36000061035156,32.79999923706055 36.349998474121094,32.79999923706055 36.349998474121094,32.79999923706055z M56.81999969482422,30.06999969482422 C57.43000030517578,29.1200008392334 56.43000030517578,27.979999542236328 55.400001525878906,28.440000534057617 C55.400001525878906,28.440000534057617 40.72999954223633,35.13999938964844 40.72999954223633,35.13999938964844 C39.72999954223633,35.599998474121094 39.09000015258789,36.61000061035156 39.09000015258789,37.70000076293945 C39.09000015258789,37.70000076293945 39.09000015258789,53.810001373291016 39.09000015258789,53.810001373291016 C39.09000015258789,54.93000030517578 40.54999923706055,55.36000061035156 41.15999984741211,54.41999816894531 C41.15999984741211,54.41999816894531 56.810001373291016,30.06999969482422 56.810001373291016,30.06999969482422 C56.810001373291016,30.06999969482422 56.81999969482422,30.06999969482422 56.81999969482422,30.06999969482422z M19.600000381469727,28.440000534057617 C18.579999923706055,27.979999542236328 17.56999969482422,29.1200008392334 18.18000030517578,30.06999969482422 C18.18000030517578,30.06999969482422 33.84000015258789,54.43000030517578 33.84000015258789,54.43000030517578 C34.45000076293945,55.380001068115234 35.90999984741211,54.939998626708984 35.90999984741211,53.81999969482422 C35.90999984741211,53.81999969482422 35.90999984741211,37.70000076293945 35.90999984741211,37.70000076293945 C35.90999984741211,36.599998474121094 35.27000045776367,35.599998474121094 34.27000045776367,35.13999938964844 C34.27000045776367,35.13999938964844 19.59000015258789,28.450000762939453 19.59000015258789,28.450000762939453 C19.59000015258789,28.450000762939453 19.600000381469727,28.440000534057617 19.600000381469727,28.440000534057617z"></path></g></g></g></g></g></svg>

main.py

@@ -1,66 +0,0 @@
-import asyncio
-import logging
-
-from app.core import setup_logging
-from app.methods import buy_premium, buy_stars, topup_ton
-
-logger = logging.getLogger(__name__)
-
-
-async def topup_ton_example():
-    logger.info("Starting TON topup example")
-
-    # @bohd4nx - target username, 100 - TON amount (integer 1-1000000000 (one billion))
-    # show_sender=True — recipient sees who sent the topup
-    result = await topup_ton("@bohd4nx", 100, show_sender=True)
-
-    if result["success"]:
-        pass  # Transaction successful, details are logged in the method
-    else:
-        logger.error(f"TON topup failed: {result['error']}")
-
-
-async def buy_premium_example():
-    logger.info("Starting Premium purchase example")
-
-    # @bohd4nx - target username, 12 - months duration (3, 6, or 12 only)
-    # show_sender=True — recipient sees who gifted the Premium
-    result = await buy_premium("@bohd4nx", 12, show_sender=True)
-
-    if result["success"]:
-        pass  # Transaction successful, details are logged in the method
-    else:
-        logger.error(f"Premium purchase failed: {result['error']}")
-
-
-async def buy_stars_example():
-    logger.info("Starting Stars purchase example")
-
-    # @bohd4nx - target username, 1000000 - stars amount (integer 50-1000000 (one million))
-    # show_sender=True — recipient sees who sent the Stars
-    result = await buy_stars("@bohd4nx", 1000000, show_sender=True)
-
-    if result["success"]:
-        pass  # Transaction successful, details are logged in the method
-    else:
-        logger.error(f"Stars purchase failed: {result['error']}")
-
-
-async def main():
-    setup_logging()
-    logger.info("Starting Fragment API by @bohd4nx - examples")
-
-    await topup_ton_example()
-    await buy_premium_example()
-    await buy_stars_example()
-
-    logger.info("All examples completed")
-
-
-if __name__ == "__main__":
-    logger.info("Fragment API by @bohd4nx - Usage Examples")
-    logger.info("Supported username formats: @username, username")
-    logger.info("Limits: TON minimum 1, Premium 3/6/12 months, Stars minimum 50")
-    logger.info("Setup: Copy .env.example to .env and fill all fields")
-
-    asyncio.run(main())

pyfragment/__init__.py

@@ -0,0 +1,73 @@
+import logging
+from importlib.metadata import version
+
+from pyfragment.client import FragmentClient
+from pyfragment.domains.ads.models import AdsRechargeResult, AdsTopupResult
+from pyfragment.domains.anonymous_numbers.models import LoginCodeResult, TerminateSessionsResult
+from pyfragment.domains.giveaways.models import PremiumGiveawayResult, StarsGiveawayResult
+from pyfragment.domains.marketplace.models import GiftsResult, NumbersResult, UsernamesResult
+from pyfragment.domains.purchases.models import PremiumResult, StarsResult
+from pyfragment.enums import ApiProvider, PaymentMethod, WalletVersion
+from pyfragment.exceptions import (
+    AlreadySubscribedError,
+    AnonymousNumberError,
+    ClientError,
+    ConfigurationError,
+    CookieError,
+    FragmentAPIError,
+    FragmentError,
+    FragmentPageError,
+    OperationError,
+    ParseError,
+    TransactionError,
+    UnexpectedError,
+    UserNotFoundError,
+    VerificationError,
+    WalletError,
+)
+from pyfragment.services.cookies import CookieResult, get_cookies_from_browser
+from pyfragment.services.tonapi.models import WalletInfo
+
+logging.getLogger("pyfragment").addHandler(logging.NullHandler())
+
+__version__: str = version("pyfragment")
+
+__all__ = [
+    "__version__",
+    "FragmentClient",
+    # results
+    "StarsResult",
+    "StarsGiveawayResult",
+    "PremiumResult",
+    "PremiumGiveawayResult",
+    "WalletInfo",
+    "AdsTopupResult",
+    "AdsRechargeResult",
+    "CookieResult",
+    "GiftsResult",
+    "LoginCodeResult",
+    "NumbersResult",
+    "TerminateSessionsResult",
+    "UsernamesResult",
+    # exceptions
+    "FragmentError",
+    "FragmentAPIError",
+    "FragmentPageError",
+    "ConfigurationError",
+    "AlreadySubscribedError",
+    "UserNotFoundError",
+    "WalletError",
+    "VerificationError",
+    "TransactionError",
+    "AnonymousNumberError",
+    "ClientError",
+    "CookieError",
+    "OperationError",
+    "ParseError",
+    "UnexpectedError",
+    # literal types
+    "ApiProvider",
+    "PaymentMethod",
+    "WalletVersion",
+    "get_cookies_from_browser",
+]

pyfragment/client.py

@@ -0,0 +1,332 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pyfragment.core.constants import BASE_HEADERS, DEFAULT_TIMEOUT, FRAGMENT_BASE_URL
+from pyfragment.core.validation import (
+    normalize_provider,
+    normalize_wallet_version,
+    parse_cookies,
+    validate_cookie_keys,
+    validate_credentials,
+)
+from pyfragment.domains.ads.models import AdsRechargeResult, AdsTopupResult
+from pyfragment.domains.ads.service import AdsService
+from pyfragment.domains.anonymous_numbers.models import LoginCodeResult, TerminateSessionsResult
+from pyfragment.domains.anonymous_numbers.service import AnonymousNumbersService
+from pyfragment.domains.base import raw_api_call
+from pyfragment.domains.giveaways.models import PremiumGiveawayResult, StarsGiveawayResult
+from pyfragment.domains.giveaways.service import GiveawaysService
+from pyfragment.domains.marketplace.models import GiftsResult, NumbersResult, UsernamesResult
+from pyfragment.domains.marketplace.service import MarketplaceService
+from pyfragment.domains.purchases.models import PremiumResult, StarsResult
+from pyfragment.domains.purchases.service import PurchasesService
+from pyfragment.enums import ApiProvider, PaymentMethod, WalletVersion
+from pyfragment.services.tonapi.models import WalletInfo
+from pyfragment.services.tonapi.service import TonapiService
+
+
+class FragmentClient:
+    """
+    Client for the Fragment.com API.
+
+    .. note::
+        This library is not affiliated with, endorsed by, or in any way officially
+        connected with Fragment or Telegram.
+
+    Args:
+        seed: 12- or 24-word mnemonic phrase for the GRAM (ex TON) wallet.
+        api_key: API key for the chosen provider — tonconsole.com (default) or t.me/toncenter.
+        cookies: Fragment session cookies as a dict or JSON string.
+        wallet_version: Wallet contract version — ``"V4R2"`` or ``"V5R1"`` (default).
+        api_provider: Blockchain API provider — ``"tonapi"`` (tonconsole.com, default)
+            or ``"toncenter"`` (t.me/toncenter).
+        timeout: HTTP request timeout in seconds. Defaults to ``30.0``.
+        headers: Custom HTTP request headers. If omitted, :data:`BASE_HEADERS` is used.
+
+    Raises:
+        ConfigurationError: If ``seed``, ``api_key``, ``wallet_version``, or ``api_provider``
+            are missing or invalid.
+        CookieError: If ``cookies`` cannot be parsed or are missing required keys.
+
+    Example::
+
+        async with FragmentClient(
+            seed="word1 word2 ...",
+            api_key="AAABBB...",
+            cookies={"stel_ssid": "...", "stel_dt": "...", ...},
+        ) as client:
+            print(await client.get_wallet())
+            result = await client.purchase_premium("@username", months=6)
+            print(result.transaction_id)
+    """
+
+    def __init__(
+        self,
+        seed: str,
+        api_key: str,
+        cookies: dict[str, Any] | str,
+        wallet_version: str = "V5R1",
+        api_provider: str = "tonapi",
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        validate_credentials(seed, api_key)
+        provider = normalize_provider(api_provider)
+        parsed_cookies = parse_cookies(cookies)
+        validate_cookie_keys(parsed_cookies)
+        version = normalize_wallet_version(wallet_version)
+
+        self.seed: str = seed.strip()
+        self.api_key: str = api_key.strip()
+        self.api_provider: ApiProvider = provider
+        self.cookies: dict[str, Any] = parsed_cookies
+        self.wallet_version: WalletVersion = version
+        self.timeout: float = timeout
+        self.headers: dict[str, str] = headers if headers is not None else BASE_HEADERS
+        self.marketplace = MarketplaceService(self)
+        self.purchases = PurchasesService(self)
+        self.giveaways = GiveawaysService(self)
+        self.tonapi = TonapiService(self)
+        self.anonymous_numbers = AnonymousNumbersService(self)
+        self.ads = AdsService(self)
+
+    async def __aenter__(self) -> FragmentClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        pass
+
+    def __repr__(self) -> str:
+        return f"FragmentClient(wallet_version='{self.wallet_version}', api_provider='{self.api_provider}', cookies={len(self.cookies)} keys)"
+
+    async def purchase_premium(
+        self,
+        username: str,
+        months: int,
+        show_sender: bool = True,
+        payment_method: PaymentMethod = PaymentMethod.GRAM,
+    ) -> PremiumResult:
+        """Gift Telegram Premium to a user.
+
+        Args:
+            username: Recipient identifier — ``@username``, ``username``, or ``https://t.me/username``.
+            months: Duration — ``3``, ``6``, or ``12``.
+            show_sender: Show your name as the sender. Defaults to ``True``.
+            payment_method: Payment currency — defaults to ``PaymentMethod.GRAM``.
+
+        Returns:
+            :class:`PremiumResult` with ``transaction_id``, ``username``, and ``amount``.
+        """
+        return await self.purchases.purchase_premium(username, months, show_sender=show_sender, payment_method=payment_method)
+
+    async def purchase_stars(
+        self,
+        username: str,
+        amount: int,
+        show_sender: bool = True,
+        payment_method: PaymentMethod = PaymentMethod.GRAM,
+    ) -> StarsResult:
+        """Send Telegram Stars to a user.
+
+        Args:
+            username: Recipient identifier — ``@username``, ``username``, or ``https://t.me/username``.
+            amount: Number of stars — integer from ``50`` to ``10 000 000``.
+            show_sender: Show your name as the gift sender. Defaults to ``True``.
+            payment_method: Payment currency — defaults to ``PaymentMethod.GRAM``.
+
+        Returns:
+            :class:`StarsResult` with ``transaction_id``, ``username``, and ``amount``.
+        """
+        return await self.purchases.purchase_stars(username, amount, show_sender=show_sender, payment_method=payment_method)
+
+    async def topup_gram(self, username: str, amount: int, show_sender: bool = True) -> AdsTopupResult:
+        """Top up GRAM (ex TON) to a recipient's Telegram balance.
+
+        Args:
+            username: Recipient's Telegram username (with or without ``@``).
+            amount: Amount in GRAM (ex 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``, and ``amount``.
+        """
+        return await self.ads.topup_gram(username, amount, show_sender=show_sender)
+
+    async def recharge_ads(self, account: str, amount: int) -> AdsRechargeResult:
+        """Add funds to your own Telegram Ads account.
+
+        Args:
+            account: Channel or bot username the Ads account is linked to (e.g. ``"@mychannel"``).
+            amount: Amount in GRAM (ex TON) — integer from ``1`` to ``1 000 000 000``.
+
+        Returns:
+            :class:`AdsRechargeResult` with ``transaction_id`` and ``amount``.
+        """
+        return await self.ads.recharge_ads(account, amount)
+
+    async def get_wallet(self) -> WalletInfo:
+        """Return the address, state, and balances of the wallet.
+
+        Returns:
+            :class:`WalletInfo` with ``address``, ``state``, ``gram_balance``, and ``usdt_balance``.
+        """
+        return await self.tonapi.get_wallet()
+
+    async def giveaway_stars(
+        self,
+        channel: str,
+        winners: int,
+        amount: int,
+        payment_method: PaymentMethod = PaymentMethod.GRAM,
+    ) -> StarsGiveawayResult:
+        """Run a Telegram Stars giveaway for a channel.
+
+        Args:
+            channel: Channel identifier — ``@channel``, ``channel``, or ``https://t.me/channel``.
+            winners: Number of winners — integer from ``1`` to ``15``.
+            amount: Stars each winner receives — integer from ``500`` to ``1 000 000``.
+            payment_method: Payment currency — defaults to ``PaymentMethod.GRAM``.
+
+        Returns:
+            :class:`StarsGiveawayResult` with ``transaction_id``, ``channel``, ``winners``, and ``amount``.
+        """
+        return await self.giveaways.giveaway_stars(channel, winners, amount, payment_method=payment_method)
+
+    async def giveaway_premium(
+        self,
+        channel: str,
+        winners: int,
+        months: int = 3,
+        payment_method: PaymentMethod = PaymentMethod.GRAM,
+    ) -> PremiumGiveawayResult:
+        """Run a Telegram Premium giveaway for a channel.
+
+        Args:
+            channel: Channel identifier — ``@channel``, ``channel``, or ``https://t.me/channel``.
+            winners: Number of winners — integer from ``1`` to ``24 000``.
+            months: Premium duration per winner — ``3``, ``6``, or ``12``. Defaults to ``3``.
+            payment_method: Payment currency — defaults to ``PaymentMethod.GRAM``.
+
+        Returns:
+            :class:`PremiumGiveawayResult` with ``transaction_id``, ``channel``, ``winners``, and ``amount``.
+        """
+        return await self.giveaways.giveaway_premium(channel, winners, months, payment_method=payment_method)
+
+    async def get_login_code(self, number: str) -> LoginCodeResult:
+        """Fetch the current pending login code for an anonymous number.
+
+        Args:
+            number: Phone number with or without leading ``+``.
+
+        Returns:
+            :class:`LoginCodeResult` with ``number``, ``code`` (``None`` if none pending),
+            and ``active_sessions`` count.
+        """
+        return await self.anonymous_numbers.get_login_code(number)
+
+    async def toggle_login_codes(self, number: str, can_receive: bool) -> None:
+        """Enable or disable login code delivery for an anonymous number.
+
+        Args:
+            number: Phone number with or without leading ``+``.
+            can_receive: ``True`` to allow receiving codes, ``False`` to block them.
+        """
+        return await self.anonymous_numbers.toggle_login_codes(number, can_receive)
+
+    async def terminate_sessions(self, number: str) -> TerminateSessionsResult:
+        """Terminate all active Telegram sessions for an anonymous number.
+
+        Args:
+            number: Phone number with or without leading ``+``.
+
+        Returns:
+            :class:`TerminateSessionsResult` with ``number`` and ``message``.
+
+        Raises:
+            AnonymousNumberError: If the number is not owned or has no active sessions.
+        """
+        return await self.anonymous_numbers.terminate_sessions(number)
+
+    async def search_usernames(
+        self,
+        query: str = "",
+        sort: str | None = None,
+        filter: str | None = None,
+        offset_id: str | None = None,
+    ) -> UsernamesResult:
+        """Search the Fragment marketplace for Telegram usernames.
+
+        Args:
+            query: Search text. Omit or pass ``""`` to browse all.
+            sort: ``"price_desc"``, ``"price_asc"``, ``"listed"``, or ``"ending"``.
+            filter: ``"auction"``, ``"sale"``, ``"sold"``, or ``""`` (available).
+            offset_id: Pass :attr:`UsernamesResult.next_offset_id` to fetch the next page.
+
+        Returns:
+            :class:`UsernamesResult` with ``items`` and ``next_offset_id``.
+        """
+        return await self.marketplace.search_usernames(query, sort=sort, filter=filter, offset_id=offset_id)
+
+    async def search_numbers(
+        self,
+        query: str = "",
+        sort: str | None = None,
+        filter: str | None = None,
+        offset_id: str | None = None,
+    ) -> NumbersResult:
+        """Search the Fragment marketplace for anonymous Telegram numbers.
+
+        Args:
+            query: Search text. Omit or pass ``""`` to browse all.
+            sort: ``"price_desc"``, ``"price_asc"``, ``"listed"``, or ``"ending"``.
+            filter: ``"auction"``, ``"sale"``, ``"sold"``, or ``""`` (available).
+            offset_id: Pass :attr:`NumbersResult.next_offset_id` to fetch the next page.
+
+        Returns:
+            :class:`NumbersResult` with ``items`` and ``next_offset_id``.
+        """
+        return await self.marketplace.search_numbers(query, sort=sort, filter=filter, offset_id=offset_id)
+
+    async def search_gifts(
+        self,
+        query: str = "",
+        collection: str | None = None,
+        sort: str | None = None,
+        filter: str | None = None,
+        view: str | None = None,
+        attr: dict[str, list[str]] | None = None,
+        offset: int | None = None,
+    ) -> GiftsResult:
+        """Search the Fragment gifts marketplace.
+
+        Args:
+            query: Search text. Omit or pass ``""`` to browse all.
+            collection: Gift collection slug (e.g. ``"artisanbrick"``).
+            sort: ``"price_desc"``, ``"price_asc"``, ``"listed"``, or ``"ending"``.
+            filter: ``"auction"``, ``"sale"``, ``"sold"``, or ``""`` (available).
+            view: Active attribute tab name (e.g. ``"Model"``).
+            attr: Attribute filters — e.g. ``{"Model": ["Foosball"], "Backdrop": ["Celtic Blue"]}``.
+            offset: Pass :attr:`GiftsResult.next_offset` to fetch the next page.
+
+        Returns:
+            :class:`GiftsResult` with ``items`` and ``next_offset``.
+        """
+        return await self.marketplace.search_gifts(
+            query, collection=collection, sort=sort, filter=filter, view=view, attr=attr, offset=offset
+        )
+
+    async def call(
+        self, method: str, data: dict[str, Any] | None = None, *, page_url: str = FRAGMENT_BASE_URL
+    ) -> dict[str, Any]:
+        """Send a raw request to the Fragment API.
+
+        Args:
+            method: Fragment API method name, e.g. ``"searchPremiumGiftRecipient"``.
+            data: Additional form-data fields.
+            page_url: Fragment page URL to derive the API hash. Defaults to ``FRAGMENT_BASE_URL``.
+
+        Returns:
+            Raw parsed JSON response as a dict.
+        """
+        return await raw_api_call(self.cookies, self.timeout, method, data, page_url, self.headers)

pyfragment/core/constants.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from typing import Any
+
+FRAGMENT_DOMAIN: str = "fragment.com"
+FRAGMENT_BASE_URL: str = f"https://{FRAGMENT_DOMAIN}"
+
+STARS_PAGE: str = f"{FRAGMENT_BASE_URL}/stars/buy"
+STARS_GIVEAWAY_PAGE: str = f"{FRAGMENT_BASE_URL}/stars/giveaway"
+PREMIUM_PAGE: str = f"{FRAGMENT_BASE_URL}/premium/gift"
+PREMIUM_GIVEAWAY_PAGE: str = f"{FRAGMENT_BASE_URL}/premium/giveaway"
+ADS_TOPUP_PAGE: str = f"{FRAGMENT_BASE_URL}/ads/topup"
+NUMBERS_PAGE: str = f"{FRAGMENT_BASE_URL}/numbers"
+GIFTS_PAGE: str = f"{FRAGMENT_BASE_URL}/gifts"
+
+DEFAULT_TIMEOUT: float = 30.0
+
+# Fragment cookie keys required for authenticated API calls
+REQUIRED_COOKIE_KEYS: tuple[str, ...] = ("stel_ssid", "stel_dt", "stel_token", "stel_ton_token")
+
+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": FRAGMENT_BASE_URL,
+    "priority": "u=1, i",
+    "sec-ch-ua": '"Not;A=Brand";v="8", "Chromium";v="150", "Google Chrome";v="150"',
+    "sec-ch-ua-mobile": "?1",
+    "sec-ch-ua-platform": '"Android"',
+    "sec-fetch-dest": "empty",
+    "sec-fetch-mode": "cors",
+    "sec-fetch-site": "same-origin",
+    "user-agent": (
+        "Mozilla/5.0 (Linux; Android 15; Pixel 9) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Mobile Safari/537.36"
+    ),
+    "x-requested-with": "XMLHttpRequest",
+}
+
+# USDT-TON jetton master contract address on GRAM (ex TON) mainnet
+USDT_GRAM_MASTER_ADDRESS: str = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs"
+
+# TON Connect device info sent during wallet connection handshake
+DEVICE_INFO: dict[str, Any] = {
+    "platform": "iphone",
+    "appName": "Tonkeeper",
+    "appVersion": "26.05.0",
+    "maxProtocolVersion": 2,
+    "features": [
+        "SendTransaction",
+        {"name": "SendTransaction", "maxMessages": 255},
+        {"name": "SignData", "types": ["text", "binary", "cell"]},
+    ],
+}
+
+# Stars: direct purchase per transaction
+STARS_PURCHASE_MIN: int = 50
+STARS_PURCHASE_MAX: int = 10_000_000
+
+# Stars: giveaway amount per winner
+STARS_GIVEAWAY_MIN: int = 500
+STARS_GIVEAWAY_MAX: int = 1_000_000
+
+# Stars giveaway winner count
+STARS_WINNERS_MIN: int = 1
+STARS_WINNERS_MAX: int = 15
+
+# Premium giveaway winner count
+PREMIUM_WINNERS_MIN: int = 1
+PREMIUM_WINNERS_MAX: int = 24_000
+
+# GRAM (ex TON) topup / Ads recharge amount
+GRAM_TOPUP_MIN: int = 1
+GRAM_TOPUP_MAX: int = 1_000_000_000
+
+# Minimum wallet balances required before broadcasting a transaction
+MIN_GRAM_BALANCE: float = 0.33
+MIN_USDT_BALANCE: float = 0.75
+
+# Premium subscription durations (months)
+PREMIUM_MONTHS_VALID: frozenset[int] = frozenset({3, 6, 12})
+
+# Mnemonic phrase valid word counts
+MNEMONIC_WORD_COUNTS_VALID: frozenset[int] = frozenset({12, 24})

pyfragment/core/transport.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import re
+from typing import Any, cast
+
+from curl_cffi.requests import AsyncSession, Response
+
+from pyfragment.core.constants import FRAGMENT_BASE_URL
+from pyfragment.exceptions import FragmentPageError, ParseError
+
+
+async def get_fragment_hash(
+    session: AsyncSession[Any],
+    headers: dict[str, str],
+    page_url: str,
+) -> str:
+    # Derive the natural referer: strip the last path segment (e.g. /stars/buy → /stars)
+    parent_url = page_url.rsplit("/", 1)[0] or FRAGMENT_BASE_URL
+
+    page_headers = {k: v for k, v in headers.items() if k not in ("content-type", "origin")}
+    page_headers["referer"] = parent_url
+    page_headers["x-aj-referer"] = parent_url
+    page_headers.pop("x-aj-referer", None)
+    page_headers.pop("x-requested-with", None)
+
+    response = await session.get(page_url, headers=page_headers)
+
+    if response.status_code != 200:
+        raise FragmentPageError(FragmentPageError.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 FragmentPageError(FragmentPageError.NOT_FOUND.format(url=page_url))
+
+    return match.group(1)
+
+
+def parse_json_response(response: Response, context: str) -> dict[str, Any]:
+    try:
+        return cast(dict[str, Any], response.json())  # type: ignore[no-untyped-call]
+    except Exception as exc:
+        raise ParseError(ParseError.UNPARSEABLE.format(context=context, exc=exc)) from exc
+
+
+async def fragment_request(
+    session: AsyncSession[Any],
+    fragment_hash: str,
+    headers: dict[str, str],
+    data: dict[str, Any],
+) -> dict[str, Any]:
+    for attempt in range(3):
+        resp = await session.post(
+            f"{FRAGMENT_BASE_URL}/api?hash={fragment_hash}",
+            headers=headers,
+            data=data,
+        )
+        if resp.status_code == 429 and attempt < 2:
+            await asyncio.sleep(1 + attempt + random.uniform(0, 0.5))
+            continue
+        if resp.status_code != 200:
+            raise FragmentPageError(
+                FragmentPageError.BAD_STATUS.format(status=resp.status_code, url=f"{FRAGMENT_BASE_URL}/api")
+            )
+        return parse_json_response(resp, data.get("method", "request"))
+    raise FragmentPageError(FragmentPageError.BAD_STATUS.format(status=429, url=f"{FRAGMENT_BASE_URL}/api"))

pyfragment/core/validation.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+from pyfragment.core.constants import MNEMONIC_WORD_COUNTS_VALID, REQUIRED_COOKIE_KEYS
+from pyfragment.enums import ApiProvider, WalletVersion
+from pyfragment.exceptions import ConfigurationError, CookieError
+
+
+def parse_cookies(cookies: dict[str, Any] | str) -> dict[str, Any]:
+    if isinstance(cookies, str):
+        try:
+            cookies = json.loads(cookies)
+        except Exception as exc:
+            raise CookieError(CookieError.READ_FAILED.format(exc=exc)) from exc
+    return cast(dict[str, Any], cookies)
+
+
+def validate_cookie_keys(cookies: dict[str, Any]) -> None:
+    missing = [k for k in REQUIRED_COOKIE_KEYS if not str(cookies.get(k, "")).strip()]
+    if missing:
+        raise CookieError(CookieError.MISSING_KEYS.format(keys=", ".join(missing)))
+
+
+def normalize_provider(api_provider: str) -> ApiProvider:
+    try:
+        return ApiProvider(api_provider.strip().lower())
+    except ValueError:
+        raise ConfigurationError(
+            ConfigurationError.UNSUPPORTED_PROVIDER.format(
+                provider=api_provider,
+                supported=", ".join(sorted(p.value for p in ApiProvider)),
+            )
+        )
+
+
+def normalize_wallet_version(wallet_version: str) -> WalletVersion:
+    version = wallet_version.strip().upper()
+    try:
+        return WalletVersion(version)
+    except ValueError:
+        raise ConfigurationError(
+            ConfigurationError.UNSUPPORTED_VERSION.format(
+                version=version,
+                supported=", ".join(sorted(m.value for m in WalletVersion)),
+            )
+        )
+
+
+def validate_credentials(seed: str, api_key: str) -> None:
+    missing = [name for name, val in (("seed", seed), ("api_key", api_key)) if not val or not str(val).strip()]
+    if missing:
+        raise ConfigurationError(ConfigurationError.MISSING_VARS.format(keys=", ".join(missing)))
+
+    word_count = len(seed.split())
+    if word_count not in MNEMONIC_WORD_COUNTS_VALID:
+        raise ConfigurationError(ConfigurationError.INVALID_MNEMONIC.format(count=word_count))

pyfragment/domains/__init__.py

@@ -0,0 +1 @@
+"""Domain-level helpers for Fragment operations."""

pyfragment/domains/ads/__init__.py

@@ -0,0 +1,5 @@
+from pyfragment.domains.ads.recharge import recharge_ads
+from pyfragment.domains.ads.service import AdsService
+from pyfragment.domains.ads.tonup import topup_gram
+
+__all__ = ["AdsService", "recharge_ads", "topup_gram"]

pyfragment/domains/ads/models.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AdsTopupResult:
+    transaction_id: str
+    username: str
+    amount: int
+
+    def __repr__(self) -> str:
+        return f"AdsTopupResult(username='{self.username}', amount={self.amount} GRAM (ex TON), tx='{self.transaction_id}')"
+
+
+@dataclass
+class AdsRechargeResult:
+    transaction_id: str
+    amount: int
+
+    def __repr__(self) -> str:
+        return f"AdsRechargeResult(amount={self.amount} GRAM (ex TON), tx='{self.transaction_id}')"

pyfragment/domains/ads/recharge.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+from pyfragment.core.constants import ADS_TOPUP_PAGE, DEVICE_INFO, GRAM_TOPUP_MAX, GRAM_TOPUP_MIN
+from pyfragment.domains.ads.models import AdsRechargeResult
+from pyfragment.exceptions import ConfigurationError, FragmentAPIError, FragmentError, UnexpectedError, VerificationError
+from pyfragment.services.tonapi.account import get_account_info
+from pyfragment.services.tonapi.transaction import process_transaction
+
+if TYPE_CHECKING:
+    from pyfragment.client import FragmentClient
+
+
+logger = logging.getLogger(__name__)
+
+
+async def recharge_ads(client: FragmentClient, account: str, amount: int) -> AdsRechargeResult:
+    if not isinstance(amount, int) or not (GRAM_TOPUP_MIN <= amount <= GRAM_TOPUP_MAX):
+        raise ConfigurationError(ConfigurationError.INVALID_GRAM_AMOUNT)
+
+    try:
+        await client.call("updateAdsState", {"mode": "new"}, page_url=ADS_TOPUP_PAGE)
+
+        result = await client.call("initAdsRechargeRequest", {"account": account, "amount": amount}, page_url=ADS_TOPUP_PAGE)
+        req_id = result.get("req_id")
+        if not req_id:
+            raise FragmentAPIError(FragmentAPIError.NO_REQUEST_ID.format(context="Ads recharge"))
+
+        account_info = await get_account_info(client)
+        transaction = await client.call(
+            "getAdsRechargeLink",
+            {
+                "account": json.dumps(account_info),
+                "device": json.dumps(DEVICE_INFO),
+                "transaction": 1,
+                "id": req_id,
+            },
+            page_url=ADS_TOPUP_PAGE,
+        )
+        if transaction.get("need_verify"):
+            raise VerificationError(VerificationError.KYC_REQUIRED)
+
+        tx_hash = await process_transaction(client, transaction)
+        return AdsRechargeResult(transaction_id=tx_hash, amount=amount)
+
+    except FragmentError as exc:
+        logger.error("Failed to recharge Ads account '%s' for %s GRAM (ex TON): %s", account, amount, exc, exc_info=True)
+        raise
+    except Exception as exc:
+        logger.exception("Failed to recharge Ads account '%s' for %s GRAM (ex TON) due to an unexpected error", account, amount)
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc

pyfragment/domains/ads/service.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyfragment.domains.ads.models import AdsRechargeResult, AdsTopupResult
+from pyfragment.domains.ads.recharge import recharge_ads
+from pyfragment.domains.ads.tonup import topup_gram
+from pyfragment.domains.base import BaseService
+
+if TYPE_CHECKING:
+    pass
+
+
+class AdsService(BaseService):
+    async def recharge_ads(self, account: str, amount: int) -> AdsRechargeResult:
+        return await recharge_ads(self._client, account, amount)
+
+    async def topup_gram(self, username: str, amount: int, show_sender: bool = True) -> AdsTopupResult:
+        return await topup_gram(self._client, username, amount, show_sender=show_sender)

pyfragment/domains/ads/tonup.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+from pyfragment.core.constants import ADS_TOPUP_PAGE, DEVICE_INFO, GRAM_TOPUP_MAX, GRAM_TOPUP_MIN
+from pyfragment.domains.ads.models import AdsTopupResult
+from pyfragment.domains.payments import parse_required_payment_amount
+from pyfragment.exceptions import (
+    ConfigurationError,
+    FragmentAPIError,
+    FragmentError,
+    UnexpectedError,
+    UserNotFoundError,
+    VerificationError,
+)
+from pyfragment.services.tonapi.account import get_account_info
+from pyfragment.services.tonapi.transaction import process_transaction
+
+if TYPE_CHECKING:
+    from pyfragment.client import FragmentClient
+
+
+logger = logging.getLogger(__name__)
+
+
+async def topup_gram(client: FragmentClient, username: str, amount: int, show_sender: bool = True) -> AdsTopupResult:
+    if not isinstance(amount, int) or not (GRAM_TOPUP_MIN <= amount <= GRAM_TOPUP_MAX):
+        raise ConfigurationError(ConfigurationError.INVALID_GRAM_AMOUNT)
+
+    try:
+        await client.call("updateAdsTopupState", {"mode": "new"}, page_url=ADS_TOPUP_PAGE)
+
+        result = await client.call("searchAdsTopupRecipient", {"query": username}, page_url=ADS_TOPUP_PAGE)
+        recipient = result.get("found", {}).get("recipient")
+        if not recipient:
+            raise UserNotFoundError(UserNotFoundError.NOT_FOUND.format(username=username))
+
+        result = await client.call("initAdsTopupRequest", {"recipient": recipient, "amount": amount}, page_url=ADS_TOPUP_PAGE)
+        required_payment_amount = parse_required_payment_amount(result)
+        req_id = result.get("req_id")
+        if not req_id:
+            raise FragmentAPIError(FragmentAPIError.NO_REQUEST_ID.format(context="GRAM (ex TON) topup"))
+
+        account = await get_account_info(client)
+        transaction = await client.call(
+            "getAdsTopupLink",
+            {
+                "account": json.dumps(account),
+                "device": json.dumps(DEVICE_INFO),
+                "transaction": 1,
+                "id": req_id,
+                "show_sender": int(show_sender),
+            },
+            page_url=ADS_TOPUP_PAGE,
+        )
+        if transaction.get("need_verify"):
+            raise VerificationError(VerificationError.KYC_REQUIRED)
+
+        tx_hash = await process_transaction(client, transaction, required_payment_amount=required_payment_amount)
+        return AdsTopupResult(transaction_id=tx_hash, username=username, amount=amount)
+
+    except FragmentError as exc:
+        logger.error(
+            "Failed to top up GRAM (ex TON) for user '%s' with %s GRAM (ex TON): %s", username, amount, exc, exc_info=True
+        )
+        raise
+    except Exception as exc:
+        logger.exception(
+            "Failed to top up GRAM (ex TON) for user '%s' with %s GRAM (ex TON) due to an unexpected error", username, amount
+        )
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc

pyfragment/domains/anonymous_numbers/__init__.py

@@ -0,0 +1,12 @@
+from pyfragment.domains.anonymous_numbers.models import LoginCodeResult, TerminateSessionsResult
+from pyfragment.domains.anonymous_numbers.number import get_login_code, terminate_sessions, toggle_login_codes
+from pyfragment.domains.anonymous_numbers.service import AnonymousNumbersService
+
+__all__ = [
+    "AnonymousNumbersService",
+    "LoginCodeResult",
+    "TerminateSessionsResult",
+    "get_login_code",
+    "terminate_sessions",
+    "toggle_login_codes",
+]

pyfragment/domains/anonymous_numbers/models.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class LoginCodeResult:
+    number: str
+    code: str | None
+    active_sessions: int
+
+    def __repr__(self) -> str:
+        code_str = f"'{self.code}'" if self.code else "None"
+        return f"LoginCodeResult(number='{self.number}', code={code_str}, active_sessions={self.active_sessions})"
+
+
+@dataclass
+class TerminateSessionsResult:
+    number: str
+    message: str | None
+
+    def __repr__(self) -> str:
+        return f"TerminateSessionsResult(number='{self.number}', message={self.message!r})"

pyfragment/domains/anonymous_numbers/number.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import html
+import logging
+from typing import TYPE_CHECKING
+
+from pyfragment.core.constants import NUMBERS_PAGE
+from pyfragment.domains.anonymous_numbers.models import LoginCodeResult, TerminateSessionsResult
+from pyfragment.domains.anonymous_numbers.parser import parse_login_code
+from pyfragment.exceptions import AnonymousNumberError, FragmentAPIError, FragmentError, UnexpectedError
+
+if TYPE_CHECKING:
+    from pyfragment.client import FragmentClient
+
+
+logger = logging.getLogger(__name__)
+
+
+def _strip_plus(number: str) -> str:
+    return number.lstrip("+") if isinstance(number, str) else number
+
+
+async def get_login_code(client: FragmentClient, number: str) -> LoginCodeResult:
+    try:
+        clean = _strip_plus(number)
+        result = await client.call(
+            "updateLoginCodes",
+            {"number": clean, "lt": "0", "from_app": "1"},
+            page_url=NUMBERS_PAGE,
+        )
+
+        if result.get("html"):
+            code, active_sessions = parse_login_code(result["html"])
+        else:
+            code, active_sessions = None, 0
+
+        return LoginCodeResult(number=number, code=code, active_sessions=active_sessions)
+
+    except FragmentError as exc:
+        logger.error("Failed to get login code for number '%s': %s", number, exc, exc_info=True)
+        raise
+    except Exception as exc:
+        logger.exception("Failed to get login code for number '%s' due to an unexpected error", number)
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc
+
+
+async def toggle_login_codes(client: FragmentClient, number: str, can_receive: bool) -> None:
+    try:
+        clean = _strip_plus(number)
+        result = await client.call(
+            "toggleLoginCodes",
+            {"number": clean, "can_receive": 1 if can_receive else 0},
+            page_url=NUMBERS_PAGE,
+        )
+
+        if result.get("error"):
+            raise FragmentAPIError(html.unescape(result["error"]))
+
+    except FragmentError as exc:
+        logger.error(
+            "Failed to toggle login code delivery for number '%s' (can_receive=%s): %s",
+            number,
+            can_receive,
+            exc,
+            exc_info=True,
+        )
+        raise
+    except Exception as exc:
+        logger.exception(
+            "Failed to toggle login code delivery for number '%s' (can_receive=%s) due to an unexpected error",
+            number,
+            can_receive,
+        )
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc
+
+
+async def terminate_sessions(client: FragmentClient, number: str) -> TerminateSessionsResult:
+    try:
+        clean = _strip_plus(number)
+
+        confirmation = await client.call(
+            "terminatePhoneSessions",
+            {"number": clean},
+            page_url=NUMBERS_PAGE,
+        )
+
+        if confirmation.get("error"):
+            raise AnonymousNumberError(
+                AnonymousNumberError.TERMINATE_FAILED.format(number=number, error=html.unescape(confirmation["error"]))
+            )
+
+        terminate_hash = confirmation.get("terminate_hash")
+        if not terminate_hash:
+            raise AnonymousNumberError(AnonymousNumberError.NOT_OWNED.format(number=number))
+
+        result = await client.call(
+            "terminatePhoneSessions",
+            {"number": clean, "terminate_hash": terminate_hash},
+            page_url=NUMBERS_PAGE,
+        )
+
+        if result.get("error"):
+            raise AnonymousNumberError(
+                AnonymousNumberError.TERMINATE_FAILED.format(number=number, error=html.unescape(result["error"]))
+            )
+
+        return TerminateSessionsResult(number=number, message=result.get("msg"))
+
+    except FragmentError as exc:
+        logger.error("Failed to terminate sessions for number '%s': %s", number, exc, exc_info=True)
+        raise
+    except Exception as exc:
+        logger.exception("Failed to terminate sessions for number '%s' due to an unexpected error", number)
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc

pyfragment/domains/anonymous_numbers/parser.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import re
+
+CODE_RE = re.compile(r'class="[^"]*table-cell-value[^"]*"[^>]*>([^<]+)<')
+ROW_RE = re.compile(r"<tr[\s>]")
+
+
+def parse_login_code(html: str) -> tuple[str | None, int]:
+    match = CODE_RE.search(html)
+    code = match.group(1).strip() if match else None
+    active_sessions = len(ROW_RE.findall(html))
+    return code, active_sessions

pyfragment/domains/anonymous_numbers/service.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyfragment.domains.anonymous_numbers.models import LoginCodeResult, TerminateSessionsResult
+from pyfragment.domains.anonymous_numbers.number import get_login_code, terminate_sessions, toggle_login_codes
+from pyfragment.domains.base import BaseService
+
+if TYPE_CHECKING:
+    pass
+
+
+class AnonymousNumbersService(BaseService):
+    async def get_login_code(self, number: str) -> LoginCodeResult:
+        return await get_login_code(self._client, number)
+
+    async def toggle_login_codes(self, number: str, can_receive: bool) -> None:
+        return await toggle_login_codes(self._client, number, can_receive)
+
+    async def terminate_sessions(self, number: str) -> TerminateSessionsResult:
+        return await terminate_sessions(self._client, number)

pyfragment/domains/base.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from curl_cffi.requests import AsyncSession
+
+from pyfragment.core.constants import BASE_HEADERS
+from pyfragment.core.transport import fragment_request, get_fragment_hash
+
+if TYPE_CHECKING:
+    from pyfragment.client import FragmentClient
+
+logger = logging.getLogger(__name__)
+
+
+async def raw_api_call(
+    cookies: dict[str, Any],
+    timeout: float,
+    method: str,
+    data: dict[str, Any] | None,
+    page_url: str,
+    headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    base = headers if headers is not None else BASE_HEADERS
+    payload = {"method": method, **(data or {})}
+    call_headers = {**base, "referer": page_url, "x-aj-referer": page_url}
+    logger.debug("Starting Fragment API call '%s' on %s", method, page_url)
+    try:
+        async with AsyncSession(cookies=cookies, timeout=timeout, impersonate="chrome") as session:
+            fragment_hash = await get_fragment_hash(session, call_headers, page_url)
+            response = await fragment_request(session, fragment_hash, call_headers, payload)
+            logger.debug("Completed Fragment API call '%s' with response keys: %s", method, sorted(response.keys()))
+            return response
+    except Exception:
+        logger.exception("Failed to call Fragment API method '%s' on %s", method, page_url)
+        raise
+
+
+class BaseService:
+    def __init__(self, client: FragmentClient) -> None:
+        self._client = client

pyfragment/domains/giveaways/__init__.py

@@ -0,0 +1,11 @@
+from pyfragment.domains.giveaways.giveaway import giveaway_premium, giveaway_stars
+from pyfragment.domains.giveaways.models import PremiumGiveawayResult, StarsGiveawayResult
+from pyfragment.domains.giveaways.service import GiveawaysService
+
+__all__ = [
+    "GiveawaysService",
+    "PremiumGiveawayResult",
+    "StarsGiveawayResult",
+    "giveaway_premium",
+    "giveaway_stars",
+]

pyfragment/domains/giveaways/giveaway.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import json
+import logging
+import random
+from typing import TYPE_CHECKING
+
+from pyfragment.core.constants import (
+    DEVICE_INFO,
+    PREMIUM_GIVEAWAY_PAGE,
+    PREMIUM_MONTHS_VALID,
+    PREMIUM_WINNERS_MAX,
+    PREMIUM_WINNERS_MIN,
+    STARS_GIVEAWAY_MAX,
+    STARS_GIVEAWAY_MIN,
+    STARS_GIVEAWAY_PAGE,
+    STARS_WINNERS_MAX,
+    STARS_WINNERS_MIN,
+)
+from pyfragment.domains.giveaways.models import PremiumGiveawayResult, StarsGiveawayResult
+from pyfragment.domains.payments import parse_required_payment_amount
+from pyfragment.enums import PaymentMethod
+from pyfragment.exceptions import (
+    ConfigurationError,
+    FragmentAPIError,
+    FragmentError,
+    UnexpectedError,
+    UserNotFoundError,
+    VerificationError,
+)
+from pyfragment.services.tonapi.account import get_account_info
+from pyfragment.services.tonapi.transaction import process_transaction
+
+if TYPE_CHECKING:
+    from pyfragment.client import FragmentClient
+
+
+logger = logging.getLogger(__name__)
+
+
+def _state_nonce() -> str:
+    # Fragment expects a pseudo-random nonce-like dh value in giveaway state updates.
+    return str(random.randint(100_000_000, 2_147_483_647))
+
+
+async def giveaway_stars(
+    client: FragmentClient,
+    channel: str,
+    winners: int,
+    amount: int,
+    payment_method: PaymentMethod = PaymentMethod.GRAM,
+) -> StarsGiveawayResult:
+    if not isinstance(winners, int) or not (STARS_WINNERS_MIN <= winners <= STARS_WINNERS_MAX):
+        raise ConfigurationError(ConfigurationError.INVALID_WINNERS_STARS)
+    if not isinstance(amount, int) or not (STARS_GIVEAWAY_MIN <= amount <= STARS_GIVEAWAY_MAX):
+        raise ConfigurationError(ConfigurationError.INVALID_STARS_PER_WINNER)
+    if not any(payment_method == m for m in PaymentMethod):
+        raise ConfigurationError(
+            ConfigurationError.INVALID_PAYMENT_METHOD.format(
+                method=payment_method,
+                supported=", ".join(sorted(m.value for m in PaymentMethod)),
+            )
+        )
+
+    try:
+        result = await client.call("searchStarsGiveawayRecipient", {"query": channel}, page_url=STARS_GIVEAWAY_PAGE)
+        recipient = result.get("found", {}).get("recipient")
+        if not recipient:
+            raise UserNotFoundError(UserNotFoundError.NOT_FOUND.format(username=channel))
+
+        await client.call(
+            "updateStarsGiveawayState",
+            {"mode": "new", "lv": "false", "dh": _state_nonce()},
+            page_url=STARS_GIVEAWAY_PAGE,
+        )
+        await client.call(
+            "updateStarsGiveawayPrices",
+            {"quantity": winners, "stars": amount},
+            page_url=STARS_GIVEAWAY_PAGE,
+        )
+
+        result = await client.call(
+            "initGiveawayStarsRequest",
+            {
+                "recipient": recipient,
+                "quantity": str(winners),
+                "stars": str(amount),
+                "payment_method": payment_method,
+            },
+            page_url=STARS_GIVEAWAY_PAGE,
+        )
+        required_payment_amount = parse_required_payment_amount(result)
+        req_id = result.get("req_id")
+        if not req_id:
+            raise FragmentAPIError(FragmentAPIError.NO_REQUEST_ID.format(context="Stars giveaway"))
+
+        account = await get_account_info(client)
+        transaction = await client.call(
+            "getGiveawayStarsLink",
+            {
+                "account": json.dumps(account),
+                "device": json.dumps(DEVICE_INFO),
+                "transaction": 1,
+                "id": req_id,
+            },
+            page_url=STARS_GIVEAWAY_PAGE,
+        )
+        if transaction.get("need_verify"):
+            raise VerificationError(VerificationError.KYC_REQUIRED)
+
+        tx_hash = await process_transaction(
+            client,
+            transaction,
+            payment_method=payment_method,
+            required_payment_amount=required_payment_amount,
+        )
+        return StarsGiveawayResult(transaction_id=tx_hash, channel=channel, winners=winners, amount=amount)
+
+    except FragmentError as exc:
+        logger.error(
+            "Failed to run Stars giveaway for channel '%s' (winners=%s, amount=%s, payment_method='%s'): %s",
+            channel,
+            winners,
+            amount,
+            payment_method,
+            exc,
+            exc_info=True,
+        )
+        raise
+    except Exception as exc:
+        logger.exception(
+            "Failed to run Stars giveaway for channel '%s' (winners=%s, amount=%s, payment_method='%s') due to an unexpected error",
+            channel,
+            winners,
+            amount,
+            payment_method,
+        )
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc
+
+
+async def giveaway_premium(
+    client: FragmentClient,
+    channel: str,
+    winners: int,
+    months: int = 3,
+    payment_method: PaymentMethod = PaymentMethod.GRAM,
+) -> PremiumGiveawayResult:
+    if not isinstance(winners, int) or not (PREMIUM_WINNERS_MIN <= winners <= PREMIUM_WINNERS_MAX):
+        raise ConfigurationError(ConfigurationError.INVALID_WINNERS_PREMIUM)
+    if months not in PREMIUM_MONTHS_VALID:
+        raise ConfigurationError(ConfigurationError.INVALID_MONTHS)
+    if not any(payment_method == m for m in PaymentMethod):
+        raise ConfigurationError(
+            ConfigurationError.INVALID_PAYMENT_METHOD.format(
+                method=payment_method,
+                supported=", ".join(sorted(m.value for m in PaymentMethod)),
+            )
+        )
+
+    try:
+        result = await client.call(
+            "searchPremiumGiveawayRecipient",
+            {"query": channel, "quantity": winners, "months": months},
+            page_url=PREMIUM_GIVEAWAY_PAGE,
+        )
+        recipient = result.get("found", {}).get("recipient")
+        if not recipient:
+            raise UserNotFoundError(UserNotFoundError.NOT_FOUND.format(username=channel))
+
+        await client.call(
+            "updatePremiumGiveawayState",
+            {
+                "mode": "new",
+                "lv": "false",
+                "dh": _state_nonce(),
+                "quantity": "",
+            },
+            page_url=PREMIUM_GIVEAWAY_PAGE,
+        )
+        await client.call(
+            "updatePremiumGiveawayPrices",
+            {"quantity": winners},
+            page_url=PREMIUM_GIVEAWAY_PAGE,
+        )
+
+        result = await client.call(
+            "initGiveawayPremiumRequest",
+            {
+                "recipient": recipient,
+                "quantity": str(winners),
+                "months": str(months),
+                "payment_method": payment_method,
+            },
+            page_url=PREMIUM_GIVEAWAY_PAGE,
+        )
+        required_payment_amount = parse_required_payment_amount(result)
+        req_id = result.get("req_id")
+        if not req_id:
+            raise FragmentAPIError(FragmentAPIError.NO_REQUEST_ID.format(context="Premium giveaway"))
+
+        account = await get_account_info(client)
+        transaction = await client.call(
+            "getGiveawayPremiumLink",
+            {
+                "account": json.dumps(account),
+                "device": json.dumps(DEVICE_INFO),
+                "transaction": 1,
+                "id": req_id,
+            },
+            page_url=PREMIUM_GIVEAWAY_PAGE,
+        )
+        if transaction.get("need_verify"):
+            raise VerificationError(VerificationError.KYC_REQUIRED)
+
+        tx_hash = await process_transaction(
+            client,
+            transaction,
+            payment_method=payment_method,
+            required_payment_amount=required_payment_amount,
+        )
+        return PremiumGiveawayResult(transaction_id=tx_hash, channel=channel, winners=winners, amount=months)
+
+    except FragmentError as exc:
+        logger.error(
+            "Failed to run Premium giveaway for channel '%s' (winners=%s, months=%s, payment_method='%s'): %s",
+            channel,
+            winners,
+            months,
+            payment_method,
+            exc,
+            exc_info=True,
+        )
+        raise
+    except Exception as exc:
+        logger.exception(
+            "Failed to run Premium giveaway for channel '%s' (winners=%s, months=%s, payment_method='%s') due to an unexpected error",
+            channel,
+            winners,
+            months,
+            payment_method,
+        )
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc

pyfragment/domains/giveaways/models.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class StarsGiveawayResult:
+    transaction_id: str
+    channel: str
+    winners: int
+    amount: int
+
+    def __repr__(self) -> str:
+        return (
+            f"StarsGiveawayResult(channel='{self.channel}', winners={self.winners}, "
+            f"amount={self.amount} stars per winner, tx='{self.transaction_id}')"
+        )
+
+
+@dataclass
+class PremiumGiveawayResult:
+    transaction_id: str
+    channel: str
+    winners: int
+    amount: int
+
+    def __repr__(self) -> str:
+        return (
+            f"PremiumGiveawayResult(channel='{self.channel}', winners={self.winners}, "
+            f"amount={self.amount} months per winner, tx='{self.transaction_id}')"
+        )

pyfragment/domains/giveaways/service.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyfragment.domains.base import BaseService
+from pyfragment.domains.giveaways.giveaway import giveaway_premium, giveaway_stars
+from pyfragment.domains.giveaways.models import PremiumGiveawayResult, StarsGiveawayResult
+from pyfragment.enums import PaymentMethod
+
+if TYPE_CHECKING:
+    pass
+
+
+class GiveawaysService(BaseService):
+    async def giveaway_stars(
+        self,
+        channel: str,
+        winners: int,
+        amount: int,
+        payment_method: PaymentMethod = PaymentMethod.GRAM,
+    ) -> StarsGiveawayResult:
+        return await giveaway_stars(self._client, channel, winners, amount, payment_method=payment_method)
+
+    async def giveaway_premium(
+        self,
+        channel: str,
+        winners: int,
+        months: int = 3,
+        payment_method: PaymentMethod = PaymentMethod.GRAM,
+    ) -> PremiumGiveawayResult:
+        return await giveaway_premium(self._client, channel, winners, months, payment_method=payment_method)

pyfragment/domains/marketplace/__init__.py

@@ -0,0 +1,13 @@
+from pyfragment.domains.marketplace.models import GiftsResult, NumbersResult, UsernamesResult
+from pyfragment.domains.marketplace.search import search_gifts, search_numbers, search_usernames
+from pyfragment.domains.marketplace.service import MarketplaceService
+
+__all__ = [
+    "GiftsResult",
+    "MarketplaceService",
+    "NumbersResult",
+    "UsernamesResult",
+    "search_gifts",
+    "search_numbers",
+    "search_usernames",
+]

pyfragment/domains/marketplace/models.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class UsernamesResult:
+    items: list[dict[str, Any]]
+    next_offset_id: str | None
+
+    def __repr__(self) -> str:
+        return f"UsernamesResult(items={len(self.items)}, next_offset_id={self.next_offset_id!r})"
+
+
+@dataclass
+class NumbersResult:
+    items: list[dict[str, Any]]
+    next_offset_id: str | None
+
+    def __repr__(self) -> str:
+        return f"NumbersResult(items={len(self.items)}, next_offset_id={self.next_offset_id!r})"
+
+
+@dataclass
+class GiftsResult:
+    items: list[dict[str, Any]]
+    next_offset: int | None
+
+    def __repr__(self) -> str:
+        return f"GiftsResult(items={len(self.items)}, next_offset={self.next_offset!r})"

pyfragment/domains/marketplace/parser.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+ROW_BLOCK_RE = re.compile(r'<tr\b[^>]*class="[^"]*tm-row-selectable[^"]*"[^>]*>(.*?)</tr>', re.DOTALL)
+HREF_RE = re.compile(r'href="(/(?:username|number|nft)/([^"]+))"')
+VALUE_RE = re.compile(r'class="[^"]*tm-value[^"]*"[^>]*>\s*([^<]+?)\s*<')
+PRICE_RE = re.compile(r"icon-before\s+icon-ton[^>]*>\s*([0-9][^<]*?)\s*<")
+DATETIME_RE = re.compile(r'<time[^>]+datetime="([^"]+)"[^>]*data-relative="text"[^>]*>')
+DATETIME_SHORT_RE = re.compile(r'<time[^>]+datetime="([^"]+)"[^>]*data-relative="short-text"[^>]*>')
+NUMERIC_RE = re.compile(r"^\+?[\d,. ]+$")
+
+GRID_ITEM_RE = re.compile(r'<a\b[^>]*class="[^"]*tm-grid-item[^"]*"[^>]*>(.*?)</a>', re.DOTALL)
+GRID_HREF_RE = re.compile(r'href="(/gift/([^?"]+))')
+GRID_NAME_RE = re.compile(r'class="item-name">([^<]+)<')
+GRID_NUM_RE = re.compile(r'class="item-num">[^#]*#(\w+)<')
+GRID_PRICE_RE = re.compile(r'class="[^"]*tm-grid-item-value[^"]*icon-ton[^"]*"[^>]*>\s*([0-9][^<]*?)\s*<')
+GRID_STATUS_RE = re.compile(r'class="[^"]*tm-grid-item-status[^"]*"[^>]*>\s*([^<]+?)\s*<')
+GRID_DATETIME_RE = re.compile(r'<time[^>]+datetime="([^"]+)"')
+
+
+def parse_auction_rows(html: str) -> list[dict[str, Any]]:
+    items: list[dict[str, Any]] = []
+    for row_match in ROW_BLOCK_RE.finditer(html):
+        row = row_match.group(1)
+
+        href_m = HREF_RE.search(row)
+        if not href_m:
+            continue
+        slug = href_m.group(1).lstrip("/")
+
+        values = [m.group(1).strip() for m in VALUE_RE.finditer(row)]
+        name = values[0] if values else slug
+
+        status: str | None = None
+        for v in values[1:]:
+            if v and v not in ("Unknown",) and not v.startswith("@") and not NUMERIC_RE.match(v):
+                status = v
+                break
+
+        price_m = PRICE_RE.search(row)
+        price: str | None = None
+        if price_m:
+            raw_price = price_m.group(1).strip().replace(",", "")
+            try:
+                price = f"{float(raw_price):.2f}"
+            except ValueError:
+                price = raw_price
+
+        time_m = DATETIME_RE.search(row) or DATETIME_SHORT_RE.search(row)
+        date: str | None = time_m.group(1) if time_m else None
+
+        items.append({"slug": slug, "name": name, "status": status, "price": price, "date": date})
+
+    return items
+
+
+def parse_gift_items(html: str) -> tuple[list[dict[str, Any]], int | None]:
+    items: list[dict[str, Any]] = []
+    for item_match in GRID_ITEM_RE.finditer(html):
+        block = item_match.group(0)
+
+        href_m = GRID_HREF_RE.search(block)
+        if not href_m:
+            continue
+        slug = href_m.group(1).lstrip("/")
+
+        name_m = GRID_NAME_RE.search(block)
+        num_m = GRID_NUM_RE.search(block)
+        item_name = name_m.group(1).strip() if name_m else slug
+        item_num = f" #{num_m.group(1)}" if num_m else ""
+        name = f"{item_name}{item_num}"
+
+        status_m = GRID_STATUS_RE.search(block)
+        status: str | None = status_m.group(1).strip() if status_m else None
+
+        price_m = GRID_PRICE_RE.search(block)
+        price: str | None = None
+        if price_m:
+            raw_price = price_m.group(1).strip().replace(",", "")
+            try:
+                price = f"{float(raw_price):.2f}"
+            except ValueError:
+                price = raw_price
+
+        time_m = GRID_DATETIME_RE.search(block)
+        date: str | None = time_m.group(1) if time_m else None
+
+        items.append({"slug": slug, "name": name, "status": status, "price": price, "date": date})
+
+    next_offset_m = re.search(r'data-next-offset="(\d+)"', html)
+    next_offset = int(next_offset_m.group(1)) if next_offset_m else None
+
+    return items, next_offset

pyfragment/domains/marketplace/search.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from pyfragment.core.constants import FRAGMENT_BASE_URL, GIFTS_PAGE, NUMBERS_PAGE
+from pyfragment.domains.marketplace.models import GiftsResult, NumbersResult, UsernamesResult
+from pyfragment.domains.marketplace.parser import parse_auction_rows, parse_gift_items
+from pyfragment.exceptions import FragmentAPIError, FragmentError, UnexpectedError
+
+if TYPE_CHECKING:
+    from pyfragment.client import FragmentClient
+
+
+logger = logging.getLogger(__name__)
+
+
+async def search_usernames(
+    client: FragmentClient,
+    query: str = "",
+    sort: str | None = None,
+    filter: str | None = None,
+    offset_id: str | None = None,
+) -> UsernamesResult:
+    data: dict[str, Any] = {"type": "usernames", "query": query}
+    if sort is not None:
+        data["sort"] = sort
+    if filter is not None:
+        data["filter"] = filter
+    if offset_id is not None:
+        data["offset_id"] = offset_id
+
+    try:
+        result = await client.call("searchAuctions", data, page_url=FRAGMENT_BASE_URL)
+        if result.get("error"):
+            raise FragmentAPIError(result["error"])
+
+        items = parse_auction_rows(result.get("html") or "")
+        raw_noi = result.get("next_offset_id")
+        next_offset_id = str(raw_noi) if raw_noi else None
+        return UsernamesResult(items=items, next_offset_id=next_offset_id)
+
+    except FragmentError as exc:
+        logger.error(
+            "Failed to search usernames (query='%s', sort='%s', filter='%s', offset_id='%s'): %s",
+            query,
+            sort,
+            filter,
+            offset_id,
+            exc,
+            exc_info=True,
+        )
+        raise
+    except Exception as exc:
+        logger.exception("Failed to search usernames for query '%s' due to an unexpected error", query)
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc
+
+
+async def search_numbers(
+    client: FragmentClient,
+    query: str = "",
+    sort: str | None = None,
+    filter: str | None = None,
+    offset_id: str | None = None,
+) -> NumbersResult:
+    data: dict[str, Any] = {"type": "numbers", "query": query}
+    if sort is not None:
+        data["sort"] = sort
+    if filter is not None:
+        data["filter"] = filter
+    if offset_id is not None:
+        data["offset_id"] = offset_id
+
+    try:
+        result = await client.call("searchAuctions", data, page_url=NUMBERS_PAGE)
+        if result.get("error"):
+            raise FragmentAPIError(result["error"])
+
+        items = parse_auction_rows(result.get("html") or "")
+        raw_noi = result.get("next_offset_id")
+        next_offset_id = str(raw_noi) if raw_noi else None
+        return NumbersResult(items=items, next_offset_id=next_offset_id)
+
+    except FragmentError as exc:
+        logger.error(
+            "Failed to search numbers (query='%s', sort='%s', filter='%s', offset_id='%s'): %s",
+            query,
+            sort,
+            filter,
+            offset_id,
+            exc,
+            exc_info=True,
+        )
+        raise
+    except Exception as exc:
+        logger.exception("Failed to search numbers for query '%s' due to an unexpected error", query)
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc
+
+
+async def search_gifts(
+    client: FragmentClient,
+    query: str = "",
+    collection: str | None = None,
+    sort: str | None = None,
+    filter: str | None = None,
+    view: str | None = None,
+    attr: dict[str, list[str]] | None = None,
+    offset: int | None = None,
+) -> GiftsResult:
+    data: dict[str, Any] = {"type": "gifts", "query": query}
+    if collection is not None:
+        data["collection"] = collection
+    if sort is not None:
+        data["sort"] = sort
+    if filter is not None:
+        data["filter"] = filter
+    if view is not None:
+        data["view"] = view
+    if attr is not None:
+        for trait, values in attr.items():
+            data[f"attr[{trait}]"] = values
+    if offset is not None:
+        data["offset"] = offset
+
+    try:
+        result = await client.call("searchAuctions", data, page_url=GIFTS_PAGE)
+        if result.get("error"):
+            raise FragmentAPIError(result["error"])
+
+        items, next_offset = parse_gift_items(result.get("html") or "")
+        return GiftsResult(items=items, next_offset=next_offset)
+
+    except FragmentError as exc:
+        logger.error(
+            "Failed to search gifts (query='%s', collection='%s', sort='%s', filter='%s', view='%s', offset='%s'): %s",
+            query,
+            collection,
+            sort,
+            filter,
+            view,
+            offset,
+            exc,
+            exc_info=True,
+        )
+        raise
+    except Exception as exc:
+        logger.exception("Failed to search gifts for query '%s' due to an unexpected error", query)
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc

pyfragment/domains/marketplace/service.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyfragment.domains.base import BaseService
+from pyfragment.domains.marketplace.models import GiftsResult, NumbersResult, UsernamesResult
+from pyfragment.domains.marketplace.search import search_gifts, search_numbers, search_usernames
+
+if TYPE_CHECKING:
+    pass
+
+
+class MarketplaceService(BaseService):
+    async def search_usernames(
+        self,
+        query: str = "",
+        sort: str | None = None,
+        filter: str | None = None,
+        offset_id: str | None = None,
+    ) -> UsernamesResult:
+        return await search_usernames(self._client, query, sort=sort, filter=filter, offset_id=offset_id)
+
+    async def search_numbers(
+        self,
+        query: str = "",
+        sort: str | None = None,
+        filter: str | None = None,
+        offset_id: str | None = None,
+    ) -> NumbersResult:
+        return await search_numbers(self._client, query, sort=sort, filter=filter, offset_id=offset_id)
+
+    async def search_gifts(
+        self,
+        query: str = "",
+        collection: str | None = None,
+        sort: str | None = None,
+        filter: str | None = None,
+        view: str | None = None,
+        attr: dict[str, list[str]] | None = None,
+        offset: int | None = None,
+    ) -> GiftsResult:
+        return await search_gifts(
+            self._client, query, collection=collection, sort=sort, filter=filter, view=view, attr=attr, offset=offset
+        )

pyfragment/domains/payments.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def parse_required_payment_amount(init_response: dict[str, Any]) -> float | None:
+    raw_amount = init_response.get("amount")
+    try:
+        return float(str(raw_amount))
+    except (TypeError, ValueError):
+        return None

pyfragment/domains/purchases/__init__.py

@@ -0,0 +1,5 @@
+from pyfragment.domains.purchases.models import PremiumResult, StarsResult
+from pyfragment.domains.purchases.purchase import purchase_premium, purchase_stars
+from pyfragment.domains.purchases.service import PurchasesService
+
+__all__ = ["PremiumResult", "PurchasesService", "StarsResult", "purchase_premium", "purchase_stars"]

pyfragment/domains/purchases/models.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class PremiumResult:
+    transaction_id: str
+    username: str
+    amount: int
+
+    def __repr__(self) -> str:
+        return f"PremiumResult(username='{self.username}', amount={self.amount} months, tx='{self.transaction_id}')"
+
+
+@dataclass
+class StarsResult:
+    transaction_id: str
+    username: str
+    amount: int
+
+    def __repr__(self) -> str:
+        return f"StarsResult(username='{self.username}', amount={self.amount} stars, tx='{self.transaction_id}')"

pyfragment/domains/purchases/purchase.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import json
+import logging
+import random
+from typing import TYPE_CHECKING
+
+from pyfragment.core.constants import (
+    DEVICE_INFO,
+    PREMIUM_MONTHS_VALID,
+    PREMIUM_PAGE,
+    STARS_PAGE,
+    STARS_PURCHASE_MAX,
+    STARS_PURCHASE_MIN,
+)
+from pyfragment.domains.payments import parse_required_payment_amount
+from pyfragment.domains.purchases.models import PremiumResult, StarsResult
+from pyfragment.enums import PaymentMethod
+from pyfragment.exceptions import (
+    AlreadySubscribedError,
+    ConfigurationError,
+    FragmentAPIError,
+    FragmentError,
+    UnexpectedError,
+    UserNotFoundError,
+    VerificationError,
+)
+from pyfragment.services.tonapi.account import get_account_info
+from pyfragment.services.tonapi.transaction import process_transaction
+
+if TYPE_CHECKING:
+    from pyfragment.client import FragmentClient
+
+
+logger = logging.getLogger(__name__)
+
+
+def _state_nonce() -> str:
+    # Fragment accepts a pseudo-random request nonce in state update methods.
+    return str(random.randint(100_000_000, 2_147_483_647))
+
+
+async def purchase_stars(
+    client: FragmentClient,
+    username: str,
+    amount: int,
+    show_sender: bool = True,
+    payment_method: PaymentMethod = PaymentMethod.GRAM,
+) -> StarsResult:
+    if not isinstance(amount, int) or not (STARS_PURCHASE_MIN <= amount <= STARS_PURCHASE_MAX):
+        raise ConfigurationError(ConfigurationError.INVALID_STARS_AMOUNT)
+    if not any(payment_method == m for m in PaymentMethod):
+        raise ConfigurationError(
+            ConfigurationError.INVALID_PAYMENT_METHOD.format(
+                method=payment_method,
+                supported=", ".join(sorted(m.value for m in PaymentMethod)),
+            )
+        )
+
+    try:
+        result = await client.call("searchStarsRecipient", {"query": username, "quantity": ""}, page_url=STARS_PAGE)
+        if "assigned to a user" in str(result.get("error", "")).lower():
+            raise UserNotFoundError(UserNotFoundError.NOT_A_USER.format(username=username))
+        recipient = result.get("found", {}).get("recipient")
+        if not recipient:
+            raise UserNotFoundError(UserNotFoundError.NOT_FOUND.format(username=username))
+
+        await client.call(
+            "updateStarsBuyState",
+            {"mode": "new", "lv": "false", "dh": _state_nonce()},
+            page_url=STARS_PAGE,
+        )
+        result = await client.call(
+            "initBuyStarsRequest",
+            {"recipient": recipient, "quantity": amount, "payment_method": payment_method},
+            page_url=STARS_PAGE,
+        )
+        required_payment_amount = parse_required_payment_amount(result)
+        req_id = result.get("req_id")
+        if not req_id:
+            raise FragmentAPIError(FragmentAPIError.NO_REQUEST_ID.format(context="Stars purchase"))
+
+        account = await get_account_info(client)
+        transaction = await client.call(
+            "getBuyStarsLink",
+            {
+                "account": json.dumps(account),
+                "device": json.dumps(DEVICE_INFO),
+                "transaction": 1,
+                "id": req_id,
+                "show_sender": int(show_sender),
+            },
+            page_url=STARS_PAGE,
+        )
+        if transaction.get("need_verify"):
+            raise VerificationError(VerificationError.KYC_REQUIRED)
+
+        tx_hash = await process_transaction(
+            client,
+            transaction,
+            payment_method=payment_method,
+            required_payment_amount=required_payment_amount,
+        )
+        return StarsResult(transaction_id=tx_hash, username=username, amount=amount)
+
+    except FragmentError as exc:
+        logger.error(
+            "Failed to purchase %s Stars for user '%s' using '%s': %s",
+            amount,
+            username,
+            payment_method,
+            exc,
+            exc_info=True,
+        )
+        raise
+    except Exception as exc:
+        logger.exception(
+            "Failed to purchase %s Stars for user '%s' using '%s' due to an unexpected error",
+            amount,
+            username,
+            payment_method,
+        )
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc
+
+
+async def purchase_premium(
+    client: FragmentClient,
+    username: str,
+    months: int,
+    show_sender: bool = True,
+    payment_method: PaymentMethod = PaymentMethod.GRAM,
+) -> PremiumResult:
+    if months not in PREMIUM_MONTHS_VALID:
+        raise ConfigurationError(ConfigurationError.INVALID_MONTHS)
+    if not any(payment_method == m for m in PaymentMethod):
+        raise ConfigurationError(
+            ConfigurationError.INVALID_PAYMENT_METHOD.format(
+                method=payment_method,
+                supported=", ".join(sorted(m.value for m in PaymentMethod)),
+            )
+        )
+
+    try:
+        result = await client.call("searchPremiumGiftRecipient", {"query": username, "months": months}, page_url=PREMIUM_PAGE)
+        if "assigned to a user" in str(result.get("error", "")).lower():
+            raise UserNotFoundError(UserNotFoundError.NOT_A_USER.format(username=username))
+        recipient = result.get("found", {}).get("recipient")
+        if not recipient:
+            raise UserNotFoundError(UserNotFoundError.NOT_FOUND.format(username=username))
+
+        await client.call(
+            "updatePremiumState",
+            {"mode": "new", "lv": "false", "dh": _state_nonce()},
+            page_url=PREMIUM_PAGE,
+        )
+        result = await client.call(
+            "initGiftPremiumRequest",
+            {"recipient": recipient, "months": months, "payment_method": payment_method},
+            page_url=PREMIUM_PAGE,
+        )
+        error_text = str(result.get("error", "")).strip().lower()
+        if "already subscribed to telegram premium" in error_text:
+            raise AlreadySubscribedError(AlreadySubscribedError.PREMIUM_ACTIVE)
+        required_payment_amount = parse_required_payment_amount(result)
+        req_id = result.get("req_id")
+        if not req_id:
+            raise FragmentAPIError(FragmentAPIError.NO_REQUEST_ID.format(context="Premium purchase"))
+
+        account = await get_account_info(client)
+        transaction = await client.call(
+            "getGiftPremiumLink",
+            {
+                "account": json.dumps(account),
+                "device": json.dumps(DEVICE_INFO),
+                "transaction": 1,
+                "id": req_id,
+                "show_sender": int(show_sender),
+            },
+            page_url=PREMIUM_PAGE,
+        )
+        if transaction.get("need_verify"):
+            raise VerificationError(VerificationError.KYC_REQUIRED)
+
+        tx_hash = await process_transaction(
+            client,
+            transaction,
+            payment_method=payment_method,
+            required_payment_amount=required_payment_amount,
+        )
+        return PremiumResult(transaction_id=tx_hash, username=username, amount=months)
+
+    except FragmentError as exc:
+        logger.error(
+            "Failed to purchase %s months of Premium for user '%s' using '%s': %s",
+            months,
+            username,
+            payment_method,
+            exc,
+            exc_info=True,
+        )
+        raise
+    except Exception as exc:
+        logger.exception(
+            "Failed to purchase %s months of Premium for user '%s' using '%s' due to an unexpected error",
+            months,
+            username,
+            payment_method,
+        )
+        raise UnexpectedError(UnexpectedError.UNEXPECTED.format(exc=exc)) from exc

pyfragment/domains/purchases/service.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyfragment.domains.base import BaseService
+from pyfragment.domains.purchases.models import PremiumResult, StarsResult
+from pyfragment.domains.purchases.purchase import purchase_premium, purchase_stars
+from pyfragment.enums import PaymentMethod
+
+if TYPE_CHECKING:
+    pass
+
+
+class PurchasesService(BaseService):
+    async def purchase_stars(
+        self,
+        username: str,
+        amount: int,
+        show_sender: bool = True,
+        payment_method: PaymentMethod = PaymentMethod.GRAM,
+    ) -> StarsResult:
+        return await purchase_stars(self._client, username, amount, show_sender=show_sender, payment_method=payment_method)
+
+    async def purchase_premium(
+        self,
+        username: str,
+        months: int,
+        show_sender: bool = True,
+        payment_method: PaymentMethod = PaymentMethod.GRAM,
+    ) -> PremiumResult:
+        return await purchase_premium(self._client, username, months, show_sender=show_sender, payment_method=payment_method)

pyfragment/enums.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from tonutils.contracts.wallet import WalletHighloadV2, WalletHighloadV3R1, WalletV4R2, WalletV5R1
+
+
+class PaymentMethod(StrEnum):
+    GRAM = "ton"
+    USDT_GRAM = "usdt_ton"
+
+    # Not supported yet
+    USDT_ETH = "usdt_eth"
+    USDT_POL = "usdt_pol"
+    USDC_ETH = "usdc_eth"
+    USDC_BASE = "usdc_base"
+    USDC_POL = "usdc_pol"
+
+
+class WalletVersion(StrEnum):
+    V4R2 = "V4R2"
+    V5R1 = "V5R1"
+    HighloadV2 = "HighloadV2"
+    HighloadV3R1 = "HighloadV3R1"
+
+
+WALLET_CLASSES: dict[WalletVersion, Any] = {
+    WalletVersion.V4R2: WalletV4R2,
+    WalletVersion.V5R1: WalletV5R1,
+    WalletVersion.HighloadV2: WalletHighloadV2,
+    WalletVersion.HighloadV3R1: WalletHighloadV3R1,
+}
+
+
+class ApiProvider(StrEnum):
+    TONAPI = "tonapi"  # tonconsole.com — default
+    TONCENTER = "toncenter"  # t.me/toncenter
+
+
+class SupportedBrowser(StrEnum):
+    ARC = "arc"
+    BRAVE = "brave"
+    CHROME = "chrome"
+    CHROMIUM = "chromium"
+    CHROMIUM_BASED = "chromium_based"
+    EDGE = "edge"
+    FIREFOX = "firefox"
+    FIREFOX_BASED = "firefox_based"
+    LIBREWOLF = "librewolf"
+    OPERA = "opera"
+    OPERA_GX = "opera_gx"
+    SAFARI = "safari"
+    VIVALDI = "vivaldi"

pyfragment/exceptions.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from pyfragment.core.constants import (
+    GRAM_TOPUP_MAX,
+    GRAM_TOPUP_MIN,
+    MNEMONIC_WORD_COUNTS_VALID,
+    PREMIUM_MONTHS_VALID,
+    PREMIUM_WINNERS_MAX,
+    PREMIUM_WINNERS_MIN,
+    STARS_GIVEAWAY_MAX,
+    STARS_GIVEAWAY_MIN,
+    STARS_PURCHASE_MAX,
+    STARS_PURCHASE_MIN,
+    STARS_WINNERS_MAX,
+    STARS_WINNERS_MIN,
+)
+
+
+class FragmentError(Exception):
+    """Base exception for all pyfragment errors."""
+
+
+class ClientError(FragmentError):
+    """Raised for client configuration and setup issues."""
+
+
+class ConfigurationError(ClientError):
+    """Raised when required client parameters are missing or invalid."""
+
+    MISSING_VARS = "Missing required parameter(s): {keys}."
+    UNSUPPORTED_VERSION = "Unsupported wallet version '{version}'. Supported values: {supported}."
+    INVALID_MNEMONIC = f"Invalid mnemonic phrase: expected {', '.join(str(n) for n in sorted(MNEMONIC_WORD_COUNTS_VALID))} words, got {{count}}."
+    UNSUPPORTED_PROVIDER = "Unsupported API provider '{provider}'. Supported values: {supported}."
+    INVALID_MONTHS = f"Invalid Premium duration: choose {', '.join(str(m) for m in sorted(PREMIUM_MONTHS_VALID))} months."
+    INVALID_STARS_AMOUNT = (
+        f"Invalid Stars amount: must be an integer between {STARS_PURCHASE_MIN:,} and {STARS_PURCHASE_MAX:,}."
+    )
+    INVALID_GRAM_AMOUNT = f"Invalid GRAM (ex TON) amount: must be an integer between {GRAM_TOPUP_MIN:,} and {GRAM_TOPUP_MAX:,}."
+    INVALID_WINNERS_STARS = (
+        f"Invalid winners count: must be an integer between {STARS_WINNERS_MIN:,} and {STARS_WINNERS_MAX:,}."
+    )
+    INVALID_WINNERS_PREMIUM = (
+        f"Invalid winners count: must be an integer between {PREMIUM_WINNERS_MIN:,} and {PREMIUM_WINNERS_MAX:,}."
+    )
+    INVALID_STARS_PER_WINNER = (
+        f"Invalid Stars per winner: must be an integer between {STARS_GIVEAWAY_MIN:,} and {STARS_GIVEAWAY_MAX:,}."
+    )
+    INVALID_PAYMENT_METHOD = "Invalid payment method '{method}'. Supported values: {supported}."
+
+
+class CookieError(ClientError):
+    """Raised when cookies are unreadable or missing required fields."""
+
+    READ_FAILED = "Failed to parse cookies: expected a JSON string or a dict, got {exc}."
+    MISSING_KEYS = (
+        "Fragment cookies are missing or empty for key(s): {keys}. "
+        "Open fragment.com in your browser, log in, and copy fresh cookies."
+    )
+    UNSUPPORTED_BROWSER = "Unsupported browser '{browser}'. Supported values: {supported}."
+    BROWSER_READ_FAILED = (
+        "Failed to read {browser} cookies: {exc}. Make sure {browser} is installed and you are logged in to {url}."
+    )
+    MISSING_BROWSER_KEYS = (
+        "Fragment cookies not found in {browser}: {keys}. "
+        "Make sure you are logged in to {url} and have connected your GRAM (ex TON) wallet in {browser}."
+    )
+    EXPIRED = "Fragment session cookie expired at {expires}. Log in to fragment.com in your browser and extract 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}'. Your session may have expired. Refresh your cookies and try again."
+
+
+class FragmentPageError(FragmentAPIError):
+    """Raised when the Fragment page cannot be fetched or the API hash is not found."""
+
+    BAD_STATUS = "Fragment returned HTTP {status} when loading {url}. Your cookies may be invalid or expired. Refresh them and try again."
+    NOT_FOUND = "Could not extract the API hash from {url}. The page structure may have changed, or you may not be logged in. Refresh your cookies."
+
+
+class UserNotFoundError(FragmentAPIError):
+    """Raised when the target Telegram user is not found on Fragment."""
+
+    NOT_FOUND = (
+        "Telegram user '{username}' was not found on Fragment. Double-check the username and make sure the account exists."
+    )
+    NOT_A_USER = "'{username}' does not belong to a user account. Make sure the username is assigned to a personal Telegram account, not a channel or bot."
+
+
+class AlreadySubscribedError(FragmentAPIError):
+    """Raised when trying to gift Premium to a user who already has an active subscription."""
+
+    PREMIUM_ACTIVE = "This account is already subscribed to Telegram Premium."
+
+
+class AnonymousNumberError(FragmentAPIError):
+    """Raised for Fragment anonymous number API failures."""
+
+    NOT_OWNED = "Number '{number}' is not associated with your Fragment account or has no active sessions to terminate."
+    TERMINATE_FAILED = "Failed to terminate sessions for '{number}': {error}"
+
+
+class TransactionError(FragmentAPIError):
+    """Raised when a GRAM (ex TON) transaction fails to build or broadcast."""
+
+    INVALID_PAYLOAD = "Fragment returned an invalid transaction payload: 'transaction.messages' is missing or empty."
+    BROADCAST_FAILED = "Transaction broadcast failed: {exc}"
+    BROADCAST_FAILED_SSL = (
+        "Transaction broadcast failed due to an SSL certificate error: {exc}\n"
+        "This usually means your system's CA bundle is missing or outdated.\n"
+        "Fix: run `pip install --upgrade certifi` and retry. "
+        "On macOS you may also need to run the 'Install Certificates.command' "
+        "located in your Python installation folder."
+    )
+    DUPLICATE_SEQNO = (
+        "Transaction broadcast failed: the GRAM (ex TON) wallet rejected the message "
+        "because a previous transaction with the same sequence number (seqno) "
+        "is still pending confirmation on-chain.\n"
+        "Wait a few seconds for the previous transaction to confirm, then retry."
+    )
+
+
+class ParseError(FragmentAPIError):
+    """Raised when a Fragment API response or payload cannot be parsed."""
+
+    UNPARSEABLE = "Failed to parse the Fragment API response for '{context}': {exc}"
+
+
+class VerificationError(FragmentAPIError):
+    """Raised when Fragment requires KYC verification before proceeding."""
+
+    KYC_REQUIRED = (
+        "Fragment requires identity verification (KYC) before this action can be completed. "
+        "Complete verification 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 GRAM (ex TON) wallet issues (connection, balance, account info)."""
+
+    LOW_GRAM_BALANCE = (
+        "Insufficient GRAM (ex TON) balance: {balance:.4f} GRAM (ex TON) available, {required:.4f} GRAM (ex TON) required."
+    )
+    LOW_USDT_BALANCE = "Insufficient USDT balance: {balance:.4f} USDT available, {required:.4f} USDT required."
+    GRAM_BALANCE_CHECK_FAILED = "Failed to fetch GRAM (ex TON) balance: {exc}"
+    USDT_BALANCE_CHECK_FAILED = "Failed to fetch USDT balance: {exc}"
+    ACCOUNT_INFO_FAILED = "Failed to retrieve wallet account info from GRAM (ex TON) network: {exc}"
+    WALLET_INFO_FAILED = "Failed to retrieve wallet info from GRAM (ex TON) network: {exc}"
+
+
+class UnexpectedError(OperationError):
+    """Raised when an unexpected error occurs during an API call."""
+
+    UNEXPECTED = "An unexpected error occurred during the operation: {exc}"
+
+
+__all__ = [
+    "FragmentError",
+    "ClientError",
+    "ConfigurationError",
+    "CookieError",
+    "FragmentAPIError",
+    "FragmentPageError",
+    "AnonymousNumberError",
+    "AlreadySubscribedError",
+    "UserNotFoundError",
+    "TransactionError",
+    "ParseError",
+    "VerificationError",
+    "OperationError",
+    "WalletError",
+    "UnexpectedError",
+]

pyfragment/services/__init__.py

@@ -0,0 +1,3 @@
+from pyfragment.services.cookies import CookieResult, get_cookies_from_browser
+
+__all__ = ["CookieResult", "get_cookies_from_browser"]

pyfragment/services/cookies/__init__.py

@@ -0,0 +1,4 @@
+from pyfragment.services.cookies.models import CookieResult
+from pyfragment.services.cookies.service import get_cookies_from_browser
+
+__all__ = ["CookieResult", "get_cookies_from_browser"]

pyfragment/services/cookies/models.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CookieResult:
+    cookies: dict[str, str]
+    expires: str | None
+
+    def __repr__(self) -> str:
+        return f"CookieResult(cookies={self.cookies!r}, expires={self.expires!r})"

pyfragment/services/cookies/service.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import importlib
+from datetime import UTC, datetime
+from typing import Any
+
+from pyfragment.core.constants import FRAGMENT_BASE_URL, FRAGMENT_DOMAIN, REQUIRED_COOKIE_KEYS
+from pyfragment.enums import SupportedBrowser
+from pyfragment.exceptions import CookieError
+from pyfragment.services.cookies.models import CookieResult
+
+try:
+    import rookiepy
+except Exception:  # noqa: BLE001
+    rookiepy = None  # type: ignore[assignment]
+
+
+def get_cookies_from_browser(browser: str = "chrome") -> CookieResult:
+    global rookiepy
+
+    key = browser.lower()
+    if not any(key == m for m in SupportedBrowser):
+        supported = ", ".join(sorted(b.value for b in SupportedBrowser))
+        raise CookieError(CookieError.UNSUPPORTED_BROWSER.format(browser=browser, supported=supported))
+
+    try:
+        if rookiepy is None:
+            rookiepy = importlib.import_module("rookiepy")
+
+        jar: list[dict[str, Any]] = getattr(rookiepy, key)([FRAGMENT_DOMAIN])
+    except Exception as exc:
+        raise CookieError(CookieError.BROWSER_READ_FAILED.format(browser=browser, exc=exc, url=FRAGMENT_BASE_URL)) from exc
+
+    cookie_map: dict[str, str] = {c["name"]: c["value"] for c in jar if c.get("name") and c.get("value")}
+
+    missing = [k for k in REQUIRED_COOKIE_KEYS if not str(cookie_map.get(k, "")).strip()]
+    if missing:
+        raise CookieError(CookieError.MISSING_BROWSER_KEYS.format(browser=browser, keys=missing, url=FRAGMENT_BASE_URL))
+
+    expires_iso: str | None = None
+    for cookie in jar:
+        if cookie.get("name") == "stel_ssid":
+            raw = cookie.get("expires")
+            if isinstance(raw, (int, float)):
+                expires_iso = datetime.fromtimestamp(raw, tz=UTC).isoformat()
+            elif isinstance(raw, str) and raw:
+                for fmt in ("%Y-%m-%dT%H:%M:%S.%fZ", "%Y-%m-%dT%H:%M:%SZ"):
+                    try:
+                        expires_iso = datetime.strptime(raw, fmt).replace(tzinfo=UTC).isoformat()
+                        break
+                    except ValueError:
+                        continue
+            break
+
+    if expires_iso:
+        expires_dt = datetime.fromisoformat(expires_iso)
+        if expires_dt < datetime.now(UTC):
+            raise CookieError(CookieError.EXPIRED.format(expires=expires_iso))
+
+    return CookieResult(cookies={k: cookie_map[k] for k in REQUIRED_COOKIE_KEYS}, expires=expires_iso)

pyfragment/services/tonapi/__init__.py

@@ -0,0 +1,5 @@
+from pyfragment.services.tonapi.service import TonapiService
+
+__all__ = [
+    "TonapiService",
+]

pyfragment/services/tonapi/account.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import base64
+import logging
+from typing import TYPE_CHECKING, Any
+
+from ton_core import NetworkGlobalID
+from tonutils.clients import TonapiClient, ToncenterClient
+from tonutils.contracts.jetton import get_wallet_address_get_method, get_wallet_data_get_method
+from tonutils.exceptions import ProviderResponseError
+
+from pyfragment.core.constants import MIN_GRAM_BALANCE, MIN_USDT_BALANCE, USDT_GRAM_MASTER_ADDRESS
+from pyfragment.enums import WALLET_CLASSES, ApiProvider
+from pyfragment.exceptions import WalletError
+from pyfragment.services.tonapi.models import WalletInfo
+
+if TYPE_CHECKING:
+    from pyfragment.client import FragmentClient
+
+
+logger = logging.getLogger(__name__)
+
+
+def _make_ton_client(client: FragmentClient) -> Any:
+    """Return the appropriate tonutils client based on the configured api_provider."""
+    if client.api_provider == ApiProvider.TONCENTER:
+        return ToncenterClient(network=NetworkGlobalID.MAINNET, api_key=client.api_key)
+    return TonapiClient(network=NetworkGlobalID.MAINNET, api_key=client.api_key)
+
+
+async def get_usdt_balance(ton: Any, wallet_address: str) -> float:
+    """Return the USDT balance for a Fragment-linked GRAM (ex TON) wallet."""
+    try:
+        jetton_wallet_address = await get_wallet_address_get_method(
+            client=ton,
+            address=USDT_GRAM_MASTER_ADDRESS,
+            owner_address=wallet_address,
+        )
+        wallet_data = await get_wallet_data_get_method(client=ton, address=jetton_wallet_address)
+        raw_balance = int(wallet_data[0]) if wallet_data else 0
+        return float(raw_balance) / 1_000_000.0
+    except ProviderResponseError as exc:
+        if exc.code == 404:
+            logger.debug("No USDT jetton wallet found for '%s'; treating balance as 0", wallet_address)
+            return 0.0
+        logger.error("Failed to load USDT balance for wallet '%s': %s", wallet_address, exc, exc_info=True)
+        raise WalletError(WalletError.USDT_BALANCE_CHECK_FAILED.format(exc=exc)) from exc
+    except Exception as exc:
+        logger.exception("Failed to load USDT balance for wallet '%s' due to an unexpected error", wallet_address)
+        raise WalletError(WalletError.USDT_BALANCE_CHECK_FAILED.format(exc=exc)) from exc
+
+
+async def check_gram_payment_balance(
+    balance_gram: float,
+    amount_gram: float,
+    required_payment_amount: float | None,
+) -> None:
+    """Validate that the GRAM (ex TON) wallet can cover a GRAM (ex TON)-denominated payment."""
+    tx_price_gram = amount_gram
+    if required_payment_amount is not None and required_payment_amount > 0:
+        tx_price_gram = max(tx_price_gram, required_payment_amount)
+
+    required_gram = max(tx_price_gram, MIN_GRAM_BALANCE)
+    if balance_gram < required_gram:
+        logger.error(
+            "Failed GRAM (ex TON) balance check: balance=%s GRAM (ex TON), required=%s GRAM (ex TON)",
+            round(balance_gram, 6),
+            round(required_gram, 6),
+        )
+        raise WalletError(WalletError.LOW_GRAM_BALANCE.format(balance=balance_gram, required=required_gram))
+
+
+async def check_usdt_payment_balance(
+    balance_gram: float,
+    required_payment_amount: float | None,
+    ton: Any,
+    wallet_address: str,
+) -> None:
+    """Validate that the wallet can cover a USDT-denominated payment."""
+    if balance_gram < MIN_GRAM_BALANCE:
+        logger.error(
+            "Failed GRAM (ex TON) gas reserve check for USDT payment: balance=%s GRAM (ex TON), required=%s GRAM (ex TON)",
+            round(balance_gram, 6),
+            MIN_GRAM_BALANCE,
+        )
+        raise WalletError(WalletError.LOW_GRAM_BALANCE.format(balance=balance_gram, required=MIN_GRAM_BALANCE))
+
+    usdt_balance = await get_usdt_balance(ton, wallet_address)
+    required_usdt = required_payment_amount if required_payment_amount is not None else MIN_USDT_BALANCE
+    if usdt_balance < required_usdt:
+        logger.error(
+            "Failed USDT balance check for wallet '%s': balance=%s USDT, required=%s USDT",
+            wallet_address,
+            round(usdt_balance, 6),
+            round(required_usdt, 6),
+        )
+        raise WalletError(WalletError.LOW_USDT_BALANCE.format(balance=usdt_balance, required=required_usdt))
+
+
+async def get_account_info(client: FragmentClient) -> dict[str, Any]:
+    """Build the wallet payload Fragment needs to prepare a transaction."""
+    async with _make_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:
+            logger.exception("Failed to build Fragment account info from the configured wallet")
+            raise WalletError(WalletError.ACCOUNT_INFO_FAILED.format(exc=exc)) from exc
+
+
+async def get_wallet_info(client: FragmentClient) -> WalletInfo:
+    """Fetch the wallet address, chain state, and GRAM (ex TON)/USDT balances."""
+    async with _make_ton_client(client) as ton:
+        try:
+            wallet_cls = WALLET_CLASSES[client.wallet_version]
+            wallet, _, _, _ = wallet_cls.from_mnemonic(client=ton, mnemonic=client.seed)
+            await wallet.refresh()
+            wallet_address = wallet.address.to_str(False, False)
+            usdt_balance = await get_usdt_balance(ton, wallet_address)
+            return WalletInfo(
+                address=wallet.address.to_str(is_user_friendly=True, is_bounceable=False),
+                state=wallet.state.value,
+                gram_balance=round(wallet.balance / 1_000_000_000, 4),
+                usdt_balance=round(usdt_balance, 4),
+            )
+        except Exception as exc:
+            logger.exception("Failed to fetch wallet info from Tonapi")
+            raise WalletError(WalletError.WALLET_INFO_FAILED.format(exc=exc)) from exc

pyfragment/services/tonapi/models.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class WalletInfo:
+    address: str
+    state: str
+    gram_balance: float
+    usdt_balance: float
+
+    def __repr__(self) -> str:
+        return (
+            f"WalletInfo(address='{self.address}', state='{self.state}', "
+            f"gram_balance={self.gram_balance} GRAM (ex TON), usdt_balance={self.usdt_balance} USDT)"
+        )

pyfragment/services/tonapi/service.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyfragment.domains.base import BaseService
+from pyfragment.services.tonapi.account import get_wallet_info
+from pyfragment.services.tonapi.models import WalletInfo
+
+if TYPE_CHECKING:
+    pass
+
+
+class TonapiService(BaseService):
+    async def get_wallet(self) -> WalletInfo:
+        return await get_wallet_info(self._client)

pyfragment/services/tonapi/transaction.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import logging
+import random
+import ssl
+from typing import TYPE_CHECKING, Any
+
+from ton_core import Cell
+from tonutils.exceptions import ProviderResponseError
+
+from pyfragment.enums import WALLET_CLASSES, PaymentMethod
+from pyfragment.exceptions import ParseError, TransactionError, WalletError
+from pyfragment.services.tonapi.account import _make_ton_client, check_gram_payment_balance, check_usdt_payment_balance
+
+if TYPE_CHECKING:
+    from pyfragment.client import FragmentClient
+
+
+logger = logging.getLogger(__name__)
+
+
+def clean_decode(payload: str) -> str | Cell:
+    """Decode a base64 BOC comment from Fragment into text when possible.
+
+    Some Fragment payloads are plain text comments, while others are structured
+    GRAM (ex TON) messages such as jetton transfers. Non-text payloads are returned as a
+    `Cell` so the caller can keep the raw binary structure.
+    """
+    s = payload.strip()
+    if not s:
+        return ""
+    s += "=" * (-len(s) % 4)
+    try:
+        boc = base64.b64decode(s, altchars=b"-_", validate=True)
+        cell = Cell.one_from_boc(boc)
+        sl = cell.begin_parse()
+        op = sl.load_uint(32)
+        if op != 0:
+            # Non-zero op code means this is a structured GRAM (ex TON) message, not a plain text comment.
+            return cell
+        try:
+            return sl.load_snake_string().strip()
+        except UnicodeDecodeError:
+            return cell
+    except Exception as exc:
+        logger.exception("Failed to decode Fragment payload")
+        raise ParseError(ParseError.UNPARSEABLE.format(context="payload decode", exc=exc)) from exc
+
+
+def _extract_message(transaction_data: dict[str, Any]) -> dict[str, Any]:
+    """Validate and extract the first message from a Fragment transaction payload."""
+    if "transaction" not in transaction_data or not transaction_data["transaction"].get("messages"):
+        logger.error("Failed to process transaction: missing transaction payload or messages")
+        raise TransactionError(TransactionError.INVALID_PAYLOAD)
+    result: dict[str, Any] = transaction_data["transaction"]["messages"][0]
+    return result
+
+
+async def _check_payment_balances(
+    wallet: Any,
+    payment_method: PaymentMethod,
+    amount_gram: float,
+    required_payment_amount: float | None,
+    transaction_data: dict[str, Any],
+    ton: Any,
+) -> None:
+    """Refresh wallet and verify sufficient balance before broadcasting."""
+    try:
+        await wallet.refresh()
+        balance_gram = wallet.balance / 1_000_000_000
+        if payment_method == "ton":
+            await check_gram_payment_balance(balance_gram, amount_gram, required_payment_amount)
+        else:
+            # USDT is paid from the Fragment-linked wallet, not the signing wallet.
+            fragment_wallet_address = transaction_data["transaction"].get("from", "")
+            await check_usdt_payment_balance(balance_gram, required_payment_amount, ton, fragment_wallet_address)
+    except WalletError:
+        raise
+    except Exception as exc:
+        logger.exception("Failed to validate balances before broadcasting transaction")
+        raise WalletError(WalletError.GRAM_BALANCE_CHECK_FAILED.format(exc=exc)) from exc
+
+
+async def _broadcast_with_retry(wallet: Any, message: dict[str, Any], payload: str | Cell) -> str:
+    """Attempt to broadcast a transaction up to 3 times, handling rate-limit and seqno errors."""
+    for attempt in range(3):
+        try:
+            result = await wallet.transfer(
+                destination=message["address"],
+                amount=int(message["amount"]),  # nanograms, not GRAM (ex TON)
+                body=payload,
+            )
+            return str(result.normalized_hash)
+        except ProviderResponseError as exc:
+            if exc.code == 429 and attempt == 0:
+                logger.warning(
+                    "Broadcast rate-limited (429), retrying transaction once: %s",
+                    exc,
+                    exc_info=True,
+                )
+                await asyncio.sleep(1 + random.uniform(0, 0.5))
+                continue
+            if exc.code == 406 and "seqno" in str(exc).lower():
+                if attempt < 2:
+                    logger.warning(
+                        "Broadcast seqno conflict (406), retrying attempt %s: %s",
+                        attempt + 2,
+                        exc,
+                        exc_info=True,
+                    )
+                    await asyncio.sleep(2 + random.uniform(0, 1))
+                    continue
+                logger.error("Failed to broadcast transaction after seqno retries")
+                raise TransactionError(TransactionError.DUPLICATE_SEQNO) from exc
+            raise
+
+    logger.error("Failed to broadcast transaction: transfer loop exited without result")
+    raise TransactionError(TransactionError.BROADCAST_FAILED.format(exc="transfer loop exited without result"))
+
+
+async def process_transaction(
+    client: FragmentClient,
+    transaction_data: dict[str, Any],
+    payment_method: PaymentMethod = PaymentMethod.GRAM,
+    required_payment_amount: float | None = None,
+) -> str:
+    """Sign and broadcast a Fragment transaction with the seeded GRAM (ex TON) wallet.
+
+    Args:
+        client: Authenticated `FragmentClient` instance.
+        transaction_data: Raw Fragment transaction payload returned by the API.
+        payment_method: Payment currency to use for the purchase flow.
+        required_payment_amount: Optional amount returned by Fragment's init request.
+
+    Returns:
+        Normalized transaction hash string.
+    """
+    message = _extract_message(transaction_data)
+    amount_gram = int(message["amount"]) / 1_000_000_000
+
+    async with _make_ton_client(client) as ton:
+        wallet_cls = WALLET_CLASSES[client.wallet_version]
+        wallet, _, _, _ = wallet_cls.from_mnemonic(client=ton, mnemonic=client.seed)
+
+        await _check_payment_balances(wallet, payment_method, amount_gram, required_payment_amount, transaction_data, ton)
+
+        payload = clean_decode(str(message.get("payload", "")))
+
+        try:
+            return await _broadcast_with_retry(wallet, message, payload)
+        except (WalletError, TransactionError):
+            raise
+        except Exception as exc:
+            cause: BaseException | None = exc
+            while cause is not None:
+                if isinstance(cause, ssl.SSLError):
+                    logger.exception("Failed to broadcast transaction due to SSL error")
+                    raise TransactionError(TransactionError.BROADCAST_FAILED_SSL.format(exc=exc)) from exc
+                cause = cause.__cause__ or cause.__context__
+            logger.exception(
+                "Failed to broadcast transaction to '%s' for %s nanograms using payment method '%s'",
+                message["address"],
+                message["amount"],
+                payment_method,
+            )
+            raise TransactionError(TransactionError.BROADCAST_FAILED.format(exc=exc)) from exc

pyproject.toml

@@ -1,19 +1,87 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyfragment"
+version = "2026.3.3"
+description = "Async Python client for the Fragment.com marketplace API."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "bohd4nx" }]
+keywords = [
+    "fragment",
+    "telegram",
+    "telegram-stars",
+    "telegram-premium",
+    "ton",
+    "tonapi",
+    "anonymous-numbers",
+    "asyncio",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Framework :: AsyncIO",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["curl-cffi>=0.14.0", "tonutils>=2.0.1"]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "pytest-mock", "mypy", "ruff"]
+browser = ["rookiepy>=0.5.6"]
+
+[project.urls]
+Repository = "https://github.com/bohd4nx/pyfragment"
+Documentation = "https://bohd4nx.gitbook.io/pyfragment/"
+Issues = "https://github.com/bohd4nx/pyfragment/issues"
+Changelog = "https://github.com/bohd4nx/pyfragment/blob/master/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pyfragment"]
+
 [tool.pytest.ini_options]
-testpaths    = ["tests"]
+testpaths = ["tests"]
 python_files = ["[0-9][0-9][0-9]_test_*.py"]
 asyncio_mode = "auto"
-addopts      = "-v --tb=short"
-
-[tool.black]
-line-length = 128
-target-version = ["py312"]
+addopts = "-v --tb=short"
 
 [tool.ruff]
-target-version = "py312"
 line-length = 128
+target-version = "py311"
 
 [tool.ruff.lint]
-# E — pycodestyle errors, F — pyflakes, W — warnings, I — isort
-select = ["E", "F", "W", "I"]
-# E501 — line too long (covered by line-length above)
+select = ["E", "F", "W", "I", "UP"]
 ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E402"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+exclude = ["^examples/", "^logs/", "^tests/"]
+
+[[tool.mypy.overrides]]
+module = [
+    "rookiepy",
+    "ton_core",
+    "tonutils",
+    "tonutils.*",
+]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+# rookiepy = None assignment is valid when the package is installed (type: ModuleType)
+# but mypy on CI (without rookiepy) sees it as Any and flags the comment as unused.
+module = "pyfragment.services.cookies.service"
+warn_unused_ignores = false

requirements.txt

@@ -1,4 +0,0 @@
-python-dotenv==1.2.2
-asyncio==4.0.0
-httpx==0.28.1
-tonutils[pytoniq]==2.0.0

tests/001_test_decode.py

@@ -1,35 +1,132 @@
-"""Tests for clean_decode() — BOC-encoded Fragment payloads decode to
-human-readable UTF-8 with the Telegram label and Ref# intact."""
+"""Decode Fragment BOC payloads so comments become text and structured messages stay raw."""
 
+import base64
 import re
+from unittest.mock import patch
 
 import pytest
+from ton_core import Cell
 
-from app.utils.decoder import clean_decode
+from pyfragment import ParseError
+from pyfragment.services.tonapi.transaction import clean_decode
 
-PAYLOADS = [
+PAYLOAD_CASES = [
     pytest.param(
         "te6ccgEBAgEALwABTgAAAAAxMDAwMDAwIFRlbGVncmFtIFN0YXJzIAoKUmVmI1RQb01wegEABkM3ZQ",
+        True,
         id="stars",
     ),
     pytest.param(
         "te6ccgEBAgEANAABTgAAAABUZWxlZ3JhbSBQcmVtaXVtIGZvciAxIHllYXIgCgpSZWYjcgEAEE9OQnM2cmNt",
+        True,
         id="premium",
     ),
     pytest.param(
         "te6ccgEBAgEAMAABTgAAAABUZWxlZ3JhbSBhY2NvdW50IHRvcCB1cCAKClJlZiNrMXpDRQEACFkxd3g",
+        True,
         id="topup",
     ),
+    pytest.param(
+        "te6ccgEBAgEAfgABqA-KfqVP885dhccidjC3GwgBCkiH8LM_zUu0afyGCTWJwX1mDjdlf2rMa9UoQlD4UHUAF1jLlcMomlo5RJTwl8jnDDdfdhc7EgQQWPqFQ9IjyLPCAwEASgAAAAA1MCBUZWxlZ3JhbSBTdGFycyAKClJlZiNtOUpoWndBcFE",
+        False,
+        id="real_stars_50",
+    ),
+    pytest.param(
+        "te6ccgEBAgEANgABTgAAAABUZWxlZ3JhbSBQcmVtaXVtIGZvciAzIG1vbnRocyAKClJlZgEAFCMzcFdKdGJkYnU",
+        False,
+        id="real_premium_3m",
+    ),
+    pytest.param(
+        "te6ccgEBAwEAhgABqg-KfqWibdDaYaJCPUWWgvAIAQpIh_CzP81LtGn8hgk1icF9Zg43ZX9qzGvVKEJQ-FB1ABdYy5XDKJpaOUSU8JfI5ww3X3YXOxIEEFj6hUPSI8izwgMBAU4AAAAAMTAwMDAwIFRlbGVncmFtIFN0YXJzIAoKUmVmIzBoZ0RmNEYCAAQ5VA",
+        False,
+        id="real_stars_100k",
+    ),
 ]
 
 
-@pytest.mark.parametrize("payload", PAYLOADS)
-def test_payload(payload: str) -> None:
+# Decode valid payload tests
+
+
+@pytest.mark.parametrize(("payload", "strict_ref"), PAYLOAD_CASES)
+def test_decode_payload(payload: str, strict_ref: bool) -> None:
     result = clean_decode(payload)
-    assert "Telegram" in result
-    assert re.search(r"Ref#[A-Za-z0-9]+", result), f"no Ref# in {result!r}"
-    assert all(ord(c) <= 127 for c in result), f"non-ASCII chars in {result!r}"
+    if isinstance(result, str):
+        assert "Telegram" in result
+        if strict_ref:
+            assert re.search(r"Ref#[A-Za-z0-9]+", result), f"no Ref# in {result!r}"
+        assert all(ord(c) < 128 for c in result), f"non-ASCII chars in {result!r}"
+    else:
+        assert isinstance(result, Cell)
 
 
-def test_empty_input_returns_string() -> None:
-    assert isinstance(clean_decode(""), str)
+# Edge case tests
+
+
+def test_empty_payload_returns_empty_string() -> None:
+    assert clean_decode("") == ""
+
+
+def test_invalid_payload_raises_parse_error() -> None:
+    with pytest.raises(ParseError):
+        clean_decode("!!!not-valid-base64!!!")
+
+
+def test_decode_payload_accepts_base64url_alphabet() -> None:
+    class _FakeSlice:
+        def load_uint(self, _: int) -> int:
+            return 0
+
+        def load_snake_string(self) -> str:
+            return "Telegram Stars Ref#abc"
+
+    class _FakeCell:
+        def begin_parse(self) -> _FakeSlice:
+            return _FakeSlice()
+
+    raw = b"\xfb\xef\xff\x00"
+    payload = base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+    with patch("pyfragment.services.tonapi.transaction.Cell.one_from_boc", return_value=_FakeCell()) as mocked:
+        result = clean_decode(payload)
+
+    mocked.assert_called_once_with(raw)
+    assert result == "Telegram Stars Ref#abc"
+
+
+def test_clean_decode_returns_text_comment_when_utf8() -> None:
+    class _FakeSlice:
+        def load_uint(self, _: int) -> int:
+            return 0
+
+        def load_snake_string(self) -> str:
+            return "Telegram Premium Ref#abc"
+
+    class _FakeCell:
+        def begin_parse(self) -> _FakeSlice:
+            return _FakeSlice()
+
+    payload = base64.urlsafe_b64encode(b"\x00\x01").decode().rstrip("=")
+    with patch("pyfragment.services.tonapi.transaction.Cell.one_from_boc", return_value=_FakeCell()):
+        parsed = clean_decode(payload)
+
+    assert parsed == "Telegram Premium Ref#abc"
+
+
+def test_clean_decode_returns_cell_for_binary_payload() -> None:
+    class _FakeSlice:
+        def load_uint(self, _: int) -> int:
+            return 0
+
+        def load_snake_string(self) -> str:
+            raise UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid start byte")
+
+    class _FakeCell:
+        def begin_parse(self) -> _FakeSlice:
+            return _FakeSlice()
+
+    payload = base64.urlsafe_b64encode(b"\x00\x01").decode().rstrip("=")
+    fake_cell: object = _FakeCell()
+    with patch("pyfragment.services.tonapi.transaction.Cell.one_from_boc", return_value=fake_cell):
+        parsed = clean_decode(payload)
+
+    assert parsed is fake_cell

tests/002_test_client.py

@@ -0,0 +1,144 @@
+"""Validate FragmentClient setup, cookie parsing, and wallet version checks."""
+
+import json
+
+import pytest
+
+from pyfragment import ConfigurationError, CookieError, FragmentClient
+from pyfragment.core.constants import MNEMONIC_WORD_COUNTS_VALID
+from tests.shared import VALID_API_KEY, VALID_COOKIES, VALID_SEED
+
+# Client init tests
+
+
+def test_valid_init() -> None:
+    client = FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES)
+    assert client.seed == VALID_SEED.strip()
+    assert client.api_key == VALID_API_KEY
+    assert client.wallet_version == "V5R1"
+    assert client.api_provider == "tonapi"
+
+
+# API provider tests
+
+
+def test_api_provider_default_is_tonapi() -> None:
+    client = FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES)
+    assert client.api_provider == "tonapi"
+
+
+def test_api_provider_toncenter() -> None:
+    client = FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES, api_provider="toncenter")
+    assert client.api_provider == "toncenter"
+
+
+def test_api_provider_is_case_insensitive() -> None:
+    client = FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES, api_provider="TONAPI")
+    assert client.api_provider == "tonapi"
+
+
+def test_unsupported_api_provider_raises() -> None:
+    with pytest.raises(ConfigurationError):
+        FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES, api_provider="infura")
+
+
+# Wallet version tests
+
+
+def test_wallet_version_v4r2() -> None:
+    client = FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES, wallet_version="V4R2")
+    assert client.wallet_version == "V4R2"
+
+
+def test_wallet_version_is_case_insensitive() -> None:
+    client = FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES, wallet_version="v5r1")
+    assert client.wallet_version == "V5R1"
+
+
+def test_unsupported_wallet_version_raises() -> None:
+    with pytest.raises(ConfigurationError):
+        FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES, wallet_version="V3R2")
+
+
+# Seed and mnemonic validation tests
+
+
+def test_missing_seed_raises() -> None:
+    with pytest.raises(ConfigurationError):
+        FragmentClient(seed="", api_key=VALID_API_KEY, cookies=VALID_COOKIES)
+
+
+def test_both_seed_and_api_key_missing_raises() -> None:
+    with pytest.raises(ConfigurationError):
+        FragmentClient(seed="", api_key="", cookies=VALID_COOKIES)
+
+
+def test_whitespace_only_seed_raises() -> None:
+    with pytest.raises(ConfigurationError):
+        FragmentClient(seed="   ", api_key=VALID_API_KEY, cookies=VALID_COOKIES)
+
+
+def test_invalid_mnemonic_length_raises() -> None:
+    bad_seed = " ".join(["word"] * 23)
+    with pytest.raises(ConfigurationError):
+        FragmentClient(seed=bad_seed, api_key=VALID_API_KEY, cookies=VALID_COOKIES)
+
+
+def test_valid_mnemonic_lengths() -> None:
+    for length in sorted(MNEMONIC_WORD_COUNTS_VALID):
+        seed = " ".join(["abandon"] * (length - 1) + ["about"])
+        client = FragmentClient(seed=seed, api_key=VALID_API_KEY, cookies=VALID_COOKIES)
+        assert len(client.seed.split()) == length
+
+
+# API key validation tests
+
+
+def test_missing_api_key_raises() -> None:
+    with pytest.raises(ConfigurationError):
+        FragmentClient(seed=VALID_SEED, api_key="", cookies=VALID_COOKIES)
+
+
+# Cookie validation tests
+
+
+def test_cookies_as_json_string() -> None:
+    client = FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=json.dumps(VALID_COOKIES))
+    assert client.cookies == VALID_COOKIES
+
+
+def test_invalid_cookies_json_raises() -> None:
+    with pytest.raises(CookieError):
+        FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies="{not valid json}")
+
+
+def test_missing_cookie_key_raises() -> None:
+    with pytest.raises(CookieError):
+        FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies={"stel_ssid": "x"})
+
+
+def test_empty_cookie_value_raises() -> None:
+    bad = {**VALID_COOKIES, "stel_token": ""}
+    with pytest.raises(CookieError):
+        FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=bad)
+
+
+def test_whitespace_cookie_value_raises() -> None:
+    bad = {**VALID_COOKIES, "stel_ton_token": "   "}
+    with pytest.raises(CookieError):
+        FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=bad)
+
+
+def test_repr() -> None:
+    client = FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES)
+    r = repr(client)
+    assert "FragmentClient" in r
+    assert "V5R1" in r
+    assert "tonapi" in r
+    assert "4 keys" in r
+
+
+@pytest.mark.asyncio
+async def test_async_context_manager() -> None:
+    async with FragmentClient(seed=VALID_SEED, api_key=VALID_API_KEY, cookies=VALID_COOKIES) as client:
+        assert isinstance(client, FragmentClient)

tests/002_test_hash.py

@@ -1,17 +0,0 @@
-"""Tests for get_fragment_hash() — fetches a valid lowercase hex hash
-from the fragment.com/stars/buy page source."""
-
-import re
-
-import pytest
-
-from app.core.constants import BASE_HEADERS, STARS_PAGE
-from app.utils.hash import get_fragment_hash
-
-
-@pytest.mark.asyncio
-async def test_hash_is_valid_hex(cookies: dict) -> None:
-    result = await get_fragment_hash(cookies, BASE_HEADERS, STARS_PAGE)
-    assert isinstance(result, str)
-    assert len(result) >= 10, f"hash too short: {result!r}"
-    assert re.fullmatch(r"[a-f0-9]+", result), f"not a hex string: {result!r}"

tests/003_test_balance.py

@@ -0,0 +1,180 @@
+"""Exercise transaction signing, balance checks, and retry behavior for GRAM (ex TON) and USDT flows."""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from tonutils.exceptions import ProviderResponseError
+
+from pyfragment import TransactionError, WalletError
+from pyfragment.enums import PaymentMethod
+from pyfragment.services.tonapi.transaction import process_transaction
+from tests.shared import VALID_SEED
+
+
+def _provider_error(code: int, message: str = "error") -> ProviderResponseError:
+    return ProviderResponseError(code=code, message=message, endpoint="api.tonapi.io")
+
+
+TRANSACTION_DATA = {
+    "transaction": {
+        "messages": [
+            {
+                "address": "0:852443f8599fe6a5da34fe43049ac4e0beb3071bb2bfb56635ea9421287c283a",
+                "amount": "500000000",  # 0.5 GRAM
+                "payload": "",
+            }
+        ]
+    }
+}
+
+
+def _make_client() -> MagicMock:
+    client = MagicMock()
+    client.api_key = "test_key"
+    client.seed = VALID_SEED.split()
+    client.wallet_version = "V5R1"
+    return client
+
+
+def _make_wallet(balance_nanotons: int) -> MagicMock:
+    wallet = MagicMock()
+    wallet.refresh = AsyncMock()
+    wallet.balance = balance_nanotons
+    wallet.transfer = AsyncMock(return_value=MagicMock(normalized_hash="abc123"))
+    return wallet
+
+
+@contextmanager
+def _patch_wallet(wallet: MagicMock) -> Generator[None, None, None]:
+    mock_ton_ctx = MagicMock()
+    mock_ton_ctx.__aenter__ = AsyncMock(return_value=MagicMock())
+    mock_ton_ctx.__aexit__ = AsyncMock(return_value=False)
+    with (
+        patch("pyfragment.services.tonapi.transaction._make_ton_client", return_value=mock_ton_ctx),
+        patch("pyfragment.services.tonapi.transaction.WALLET_CLASSES") as mock_classes,
+    ):
+        mock_classes["V5R1"].from_mnemonic.return_value = (wallet, MagicMock(), None, None)
+        yield
+
+
+# Balance threshold tests
+
+
+@pytest.mark.asyncio
+async def test_sufficient_balance_broadcasts() -> None:
+    wallet = _make_wallet(balance_nanotons=1_000_000_000)  # 1 GRAM, above threshold
+    with _patch_wallet(wallet), patch("pyfragment.services.tonapi.transaction.clean_decode", return_value="50 Telegram Stars"):
+        result = await process_transaction(_make_client(), TRANSACTION_DATA)
+    assert result == "abc123"
+    wallet.transfer.assert_called_once()
+
+
+@pytest.mark.asyncio
+async def test_insufficient_balance_raises() -> None:
+    wallet = _make_wallet(balance_nanotons=100_000_000)  # 0.1 GRAM, below threshold
+    with _patch_wallet(wallet):
+        with pytest.raises(WalletError, match="required"):
+            await process_transaction(_make_client(), TRANSACTION_DATA)
+    wallet.transfer.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_exact_minimum_balance_broadcasts() -> None:
+    wallet = _make_wallet(balance_nanotons=500_000_000)  # exactly transaction amount threshold
+    with _patch_wallet(wallet), patch("pyfragment.services.tonapi.transaction.clean_decode", return_value="50 Telegram Stars"):
+        result = await process_transaction(_make_client(), TRANSACTION_DATA)
+    assert result == "abc123"
+
+
+@pytest.mark.asyncio
+async def test_one_nanoton_below_minimum_raises() -> None:
+    wallet = _make_wallet(balance_nanotons=499_999_999)  # 1 nanogram below transaction amount threshold
+    with _patch_wallet(wallet):
+        with pytest.raises(WalletError, match="required"):
+            await process_transaction(_make_client(), TRANSACTION_DATA)
+
+
+# Error handling tests
+
+
+@pytest.mark.asyncio
+async def test_invalid_payload_raises() -> None:
+    with pytest.raises(TransactionError):
+        await process_transaction(_make_client(), {"transaction": {}})
+
+
+@pytest.mark.asyncio
+async def test_empty_messages_list_raises() -> None:
+    with pytest.raises(TransactionError):
+        await process_transaction(_make_client(), {"transaction": {"messages": []}})
+
+
+@pytest.mark.asyncio
+async def test_balance_check_failed_raises_wallet_error() -> None:
+    wallet = _make_wallet(balance_nanotons=1_000_000_000)
+    wallet.refresh = AsyncMock(side_effect=RuntimeError("network timeout"))
+    with _patch_wallet(wallet):
+        with pytest.raises(WalletError, match="balance"):
+            await process_transaction(_make_client(), TRANSACTION_DATA)
+    wallet.transfer.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_rate_limit_retries_and_succeeds() -> None:
+    wallet = _make_wallet(balance_nanotons=1_000_000_000)
+    wallet.transfer = AsyncMock(side_effect=[_provider_error(429, "rate limited"), MagicMock(normalized_hash="abc123")])
+    with _patch_wallet(wallet), patch("pyfragment.services.tonapi.transaction.clean_decode", return_value=""):
+        result = await process_transaction(_make_client(), TRANSACTION_DATA)
+    assert result == "abc123"
+    assert wallet.transfer.call_count == 2
+
+
+@pytest.mark.asyncio
+async def test_duplicate_seqno_raises_after_retries() -> None:
+    wallet = _make_wallet(balance_nanotons=1_000_000_000)
+    err = _provider_error(406, "Duplicate msg_seqno")
+    wallet.transfer = AsyncMock(side_effect=[err, err, err])
+    with _patch_wallet(wallet), patch("pyfragment.services.tonapi.transaction.clean_decode", return_value=""):
+        with pytest.raises(TransactionError, match="seqno"):
+            await process_transaction(_make_client(), TRANSACTION_DATA)
+    assert wallet.transfer.call_count == 3
+
+
+@pytest.mark.asyncio
+async def test_usdt_payment_requires_min_gram_gas_reserve() -> None:
+    wallet = _make_wallet(balance_nanotons=10_000_000)  # 0.01 GRAM below MIN_GRAM_BALANCE
+    with _patch_wallet(wallet), patch("pyfragment.services.tonapi.account.get_usdt_balance", AsyncMock(return_value=100.0)):
+        with pytest.raises(WalletError, match="Insufficient GRAM"):
+            await process_transaction(_make_client(), TRANSACTION_DATA, payment_method=PaymentMethod.USDT_GRAM)
+
+
+@pytest.mark.asyncio
+async def test_usdt_payment_checks_usdt_balance() -> None:
+    wallet = _make_wallet(balance_nanotons=1_000_000_000)
+    transaction = {
+        "transaction": {
+            "messages": [
+                {
+                    "address": "0:852443f8599fe6a5da34fe43049ac4e0beb3071bb2bfb56635ea9421287c283a",
+                    "amount": "50000000",
+                    "payload": "",
+                }
+            ]
+        },
+        "required_usdt": 12.5,
+    }
+
+    with (
+        _patch_wallet(wallet),
+        patch("pyfragment.services.tonapi.transaction.clean_decode", return_value=""),
+        patch("pyfragment.services.tonapi.account.get_usdt_balance", AsyncMock(return_value=5.0)),
+    ):
+        with pytest.raises(WalletError, match="Insufficient USDT balance"):
+            await process_transaction(
+                _make_client(),
+                transaction,
+                payment_method=PaymentMethod.USDT_GRAM,
+                required_payment_amount=12.5,
+            )

tests/004_test_stars.py

@@ -0,0 +1,343 @@
+"""Cover stars purchase and giveaway flows, including validation and request wiring."""
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+import pyfragment.domains.giveaways.giveaway as _giveaway_stars_mod
+import pyfragment.domains.purchases.purchase as _purchase_stars_mod
+from pyfragment import ConfigurationError, FragmentClient, StarsGiveawayResult, StarsResult, UserNotFoundError
+from pyfragment.core.constants import (
+    STARS_GIVEAWAY_MAX,
+    STARS_GIVEAWAY_MIN,
+    STARS_PURCHASE_MAX,
+    STARS_PURCHASE_MIN,
+    STARS_WINNERS_MAX,
+    STARS_WINNERS_MIN,
+)
+from pyfragment.enums import PaymentMethod
+from tests.shared import FAKE_ACCOUNT, FAKE_RECIPIENT, FAKE_REQ_ID, FAKE_TRANSACTION, FAKE_TX_HASH
+
+# Stars purchase validation tests
+
+
+@pytest.mark.asyncio
+async def test_purchase_stars_amount_too_low(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.purchase_stars("@user", amount=STARS_PURCHASE_MIN - 1)
+
+
+@pytest.mark.asyncio
+async def test_purchase_stars_amount_too_high(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.purchase_stars("@user", amount=STARS_PURCHASE_MAX + 1)
+
+
+@pytest.mark.asyncio
+async def test_purchase_stars_float_amount(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.purchase_stars("@user", amount=100.5)  # type: ignore[arg-type]
+
+
+@pytest.mark.asyncio
+async def test_purchase_stars_invalid_payment_method(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError, match="Invalid payment method"):
+        await client.purchase_stars("@user", amount=500, payment_method="btc")  # type: ignore[arg-type]
+
+
+# Stars purchase mocked tests
+
+
+@pytest.mark.asyncio
+async def test_purchase_stars_success(client: FragmentClient) -> None:
+    call_mock = AsyncMock(
+        side_effect=[
+            {"found": {"recipient": FAKE_RECIPIENT}},
+            {},  # updateStarsBuyState
+            {"req_id": FAKE_REQ_ID},
+            FAKE_TRANSACTION,
+        ]
+    )
+    with (
+        patch.object(client, "call", call_mock),
+        patch.object(_purchase_stars_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+        patch.object(_purchase_stars_mod, "process_transaction", AsyncMock(return_value=FAKE_TX_HASH)),
+    ):
+        result = await client.purchase_stars("@user", amount=500)
+
+    assert isinstance(result, StarsResult)
+    assert result.transaction_id == FAKE_TX_HASH
+    assert result.username == "@user"
+    assert result.amount == 500
+
+
+@pytest.mark.asyncio
+async def test_purchase_stars_passes_payment_method(client: FragmentClient) -> None:
+    call_mock = AsyncMock(
+        side_effect=[
+            {"found": {"recipient": FAKE_RECIPIENT}},
+            {},  # updateStarsBuyState
+            {"req_id": FAKE_REQ_ID},
+            FAKE_TRANSACTION,
+        ]
+    )
+    proc_mock = AsyncMock(return_value=FAKE_TX_HASH)
+    with (
+        patch.object(client, "call", call_mock),
+        patch.object(_purchase_stars_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+        patch.object(_purchase_stars_mod, "process_transaction", proc_mock),
+    ):
+        await client.purchase_stars("@user", amount=500, payment_method=PaymentMethod.USDT_GRAM)
+
+    init_call = call_mock.await_args_list[2]
+    assert init_call.args[0] == "initBuyStarsRequest"
+    assert init_call.args[1]["payment_method"] == "usdt_ton"
+    assert proc_mock.await_args is not None
+    assert proc_mock.await_args.kwargs["payment_method"] == "usdt_ton"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("query", ["@user", "monk", "https://t.me/monk"])
+async def test_purchase_stars_accepts_query_formats(client: FragmentClient, query: str) -> None:
+    call_mock = AsyncMock(return_value={"found": {}})
+    with patch.object(client, "call", call_mock):
+        with pytest.raises(UserNotFoundError):
+            await client.purchase_stars(query, amount=500)
+
+    search_call = call_mock.await_args_list[0]
+    assert search_call.args[0] == "searchStarsRecipient"
+    assert search_call.args[1]["query"] == query
+
+
+@pytest.mark.asyncio
+async def test_purchase_stars_user_not_found(client: FragmentClient) -> None:
+    with patch.object(client, "call", AsyncMock(return_value={"found": {}})):
+        with pytest.raises(UserNotFoundError):
+            await client.purchase_stars("@ghost", amount=500)
+
+
+# Stars giveaway validation tests
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_winners_too_low(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.giveaway_stars("@channel", winners=STARS_WINNERS_MIN - 1, amount=STARS_GIVEAWAY_MIN)
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_winners_too_high(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.giveaway_stars("@channel", winners=STARS_WINNERS_MAX + 1, amount=STARS_GIVEAWAY_MIN)
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_amount_too_low(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.giveaway_stars("@channel", winners=STARS_WINNERS_MIN, amount=STARS_GIVEAWAY_MIN - 1)
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_amount_too_high(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.giveaway_stars("@channel", winners=STARS_WINNERS_MIN, amount=STARS_GIVEAWAY_MAX + 1)
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_float_winners(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.giveaway_stars("@channel", winners=1.5, amount=500)  # type: ignore[arg-type]
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_float_amount(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.giveaway_stars("@channel", winners=1, amount=500.5)  # type: ignore[arg-type]
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_invalid_payment_method(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError, match="Invalid payment method"):
+        await client.giveaway_stars("@channel", winners=1, amount=500, payment_method="btc")  # type: ignore[arg-type]
+
+
+# Stars giveaway mocked tests
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_success(client: FragmentClient) -> None:
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},
+                    {},
+                    {"req_id": FAKE_REQ_ID},
+                    FAKE_TRANSACTION,
+                ]
+            ),
+        ),
+        patch.object(_giveaway_stars_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+        patch.object(_giveaway_stars_mod, "process_transaction", AsyncMock(return_value=FAKE_TX_HASH)),
+    ):
+        result = await client.giveaway_stars("@channel", winners=3, amount=1000)
+
+    assert isinstance(result, StarsGiveawayResult)
+    assert result.transaction_id == FAKE_TX_HASH
+    assert result.channel == "@channel"
+    assert result.winners == 3
+    assert result.amount == 1000
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_passes_payment_method(client: FragmentClient) -> None:
+    call_mock = AsyncMock(
+        side_effect=[
+            {"found": {"recipient": FAKE_RECIPIENT}},
+            {},
+            {},
+            {"req_id": FAKE_REQ_ID},
+            FAKE_TRANSACTION,
+        ]
+    )
+    proc_mock = AsyncMock(return_value=FAKE_TX_HASH)
+    with (
+        patch.object(client, "call", call_mock),
+        patch.object(_giveaway_stars_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+        patch.object(_giveaway_stars_mod, "process_transaction", proc_mock),
+    ):
+        await client.giveaway_stars("@channel", winners=3, amount=1000, payment_method=PaymentMethod.USDT_GRAM)
+
+    init_call = call_mock.await_args_list[3]
+    assert init_call.args[0] == "initGiveawayStarsRequest"
+    assert init_call.args[1]["payment_method"] == "usdt_ton"
+    assert proc_mock.await_args is not None
+    assert proc_mock.await_args.kwargs["payment_method"] == "usdt_ton"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("query", ["@channel", "monk", "https://t.me/id2757542991"])
+async def test_giveaway_stars_accepts_query_formats(client: FragmentClient, query: str) -> None:
+    call_mock = AsyncMock(return_value={"found": {}})
+    with patch.object(client, "call", call_mock):
+        with pytest.raises(UserNotFoundError):
+            await client.giveaway_stars(query, winners=1, amount=500)
+
+    search_call = call_mock.await_args_list[0]
+    assert search_call.args[0] == "searchStarsGiveawayRecipient"
+    assert search_call.args[1]["query"] == query
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_channel_not_found(client: FragmentClient) -> None:
+    with patch.object(client, "call", AsyncMock(return_value={"found": {}})):
+        with pytest.raises(UserNotFoundError):
+            await client.giveaway_stars("@ghost", winners=1, amount=500)
+
+
+# Stars purchase — error branches
+
+
+@pytest.mark.asyncio
+async def test_purchase_stars_not_a_user_raises(client: FragmentClient) -> None:
+    with patch.object(client, "call", AsyncMock(return_value={"error": "Please enter a username assigned to a user."})):
+        with pytest.raises(UserNotFoundError, match="does not belong"):
+            await client.purchase_stars("@channel", amount=500)
+
+
+@pytest.mark.asyncio
+async def test_purchase_stars_missing_req_id_raises(client: FragmentClient) -> None:
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},  # updateStarsBuyState
+                    {"amount": "0.1"},  # initBuyStarsRequest — no req_id
+                ]
+            ),
+        ),
+        patch.object(_purchase_stars_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+    ):
+        from pyfragment.exceptions import FragmentAPIError
+
+        with pytest.raises(FragmentAPIError):
+            await client.purchase_stars("@user", amount=500)
+
+
+@pytest.mark.asyncio
+async def test_purchase_stars_need_verify_raises(client: FragmentClient) -> None:
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},  # updateStarsBuyState
+                    {"req_id": FAKE_REQ_ID},
+                    {"need_verify": True},  # getBuyStarsLink
+                ]
+            ),
+        ),
+        patch.object(_purchase_stars_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+    ):
+        from pyfragment.exceptions import VerificationError
+
+        with pytest.raises(VerificationError):
+            await client.purchase_stars("@user", amount=500)
+
+
+# Stars giveaway — error branches
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_missing_req_id_raises(client: FragmentClient) -> None:
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},  # updateStarsGiveawayState
+                    {},  # updateStarsGiveawayPrices
+                    {"amount": "0.1"},  # initGiveawayStarsRequest — no req_id
+                ]
+            ),
+        ),
+        patch.object(_giveaway_stars_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+    ):
+        from pyfragment.exceptions import FragmentAPIError
+
+        with pytest.raises(FragmentAPIError):
+            await client.giveaway_stars("@channel", winners=3, amount=1000)
+
+
+@pytest.mark.asyncio
+async def test_giveaway_stars_need_verify_raises(client: FragmentClient) -> None:
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},  # updateStarsGiveawayState
+                    {},  # updateStarsGiveawayPrices
+                    {"req_id": FAKE_REQ_ID},
+                    {"need_verify": True},  # getGiveawayStarsLink
+                ]
+            ),
+        ),
+        patch.object(_giveaway_stars_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+    ):
+        from pyfragment.exceptions import VerificationError
+
+        with pytest.raises(VerificationError):
+            await client.giveaway_stars("@channel", winners=3, amount=1000)

tests/005_test_premium.py

@@ -0,0 +1,341 @@
+"""Cover premium purchase and giveaway flows, including validation and request wiring."""
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+import pyfragment.domains.giveaways.giveaway as _giveaway_premium_mod
+import pyfragment.domains.purchases.purchase as _purchase_premium_mod
+from pyfragment import ConfigurationError, FragmentClient, PremiumGiveawayResult, PremiumResult, UserNotFoundError
+from pyfragment.core.constants import PREMIUM_MONTHS_VALID, PREMIUM_WINNERS_MAX, PREMIUM_WINNERS_MIN
+from pyfragment.enums import PaymentMethod
+from pyfragment.exceptions import AlreadySubscribedError
+from tests.shared import FAKE_ACCOUNT, FAKE_RECIPIENT, FAKE_REQ_ID, FAKE_TRANSACTION, FAKE_TX_HASH
+
+# Premium purchase validation tests
+
+
+@pytest.mark.asyncio
+async def test_purchase_premium_invalid_months(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.purchase_premium("@user", months=5)
+
+
+@pytest.mark.asyncio
+async def test_purchase_premium_months_zero(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.purchase_premium("@user", months=min(PREMIUM_MONTHS_VALID) - 1)
+
+
+@pytest.mark.asyncio
+async def test_purchase_premium_invalid_payment_method(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError, match="Invalid payment method"):
+        await client.purchase_premium("@user", months=3, payment_method="btc")  # type: ignore[arg-type]
+
+
+# Premium purchase mocked tests
+
+
+@pytest.mark.asyncio
+async def test_purchase_premium_success(client: FragmentClient) -> None:
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},  # updatePremiumState
+                    {"req_id": FAKE_REQ_ID},
+                    FAKE_TRANSACTION,
+                ]
+            ),
+        ),
+        patch.object(_purchase_premium_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+        patch.object(_purchase_premium_mod, "process_transaction", AsyncMock(return_value=FAKE_TX_HASH)),
+    ):
+        result = await client.purchase_premium("@user", months=3)
+
+    assert isinstance(result, PremiumResult)
+    assert result.transaction_id == FAKE_TX_HASH
+    assert result.username == "@user"
+    assert result.amount == 3
+
+
+@pytest.mark.asyncio
+async def test_purchase_premium_passes_payment_method(client: FragmentClient) -> None:
+    call_mock = AsyncMock(
+        side_effect=[
+            {"found": {"recipient": FAKE_RECIPIENT}},
+            {},  # updatePremiumState
+            {"req_id": FAKE_REQ_ID},
+            FAKE_TRANSACTION,
+        ]
+    )
+    proc_mock = AsyncMock(return_value=FAKE_TX_HASH)
+    with (
+        patch.object(client, "call", call_mock),
+        patch.object(_purchase_premium_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+        patch.object(_purchase_premium_mod, "process_transaction", proc_mock),
+    ):
+        await client.purchase_premium("@user", months=6, payment_method=PaymentMethod.USDT_GRAM)
+
+    init_call = call_mock.await_args_list[2]
+    assert init_call.args[0] == "initGiftPremiumRequest"
+    assert init_call.args[1]["payment_method"] == "usdt_ton"
+    assert proc_mock.await_args is not None
+    assert proc_mock.await_args.kwargs["payment_method"] == "usdt_ton"
+
+
+@pytest.mark.asyncio
+async def test_purchase_premium_already_subscribed_raises(client: FragmentClient) -> None:
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},  # updatePremiumState
+                    {"error": "This account is already subscribed to Telegram Premium."},
+                ]
+            ),
+        ),
+    ):
+        with pytest.raises(AlreadySubscribedError):
+            await client.purchase_premium("@user", months=6)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("query", ["@user", "monk", "https://t.me/monk"])
+async def test_purchase_premium_accepts_query_formats(client: FragmentClient, query: str) -> None:
+    call_mock = AsyncMock(return_value={"found": {}})
+    with patch.object(client, "call", call_mock):
+        with pytest.raises(UserNotFoundError):
+            await client.purchase_premium(query, months=6)
+
+    search_call = call_mock.await_args_list[0]
+    assert search_call.args[0] == "searchPremiumGiftRecipient"
+    assert search_call.args[1]["query"] == query
+
+
+@pytest.mark.asyncio
+async def test_purchase_premium_user_not_found(client: FragmentClient) -> None:
+    with patch.object(client, "call", AsyncMock(return_value={"found": {}})):
+        with pytest.raises(UserNotFoundError):
+            await client.purchase_premium("@ghost", months=3)
+
+
+# Premium giveaway validation tests
+
+
+@pytest.mark.asyncio
+async def test_giveaway_premium_winners_too_low(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.giveaway_premium("@channel", winners=PREMIUM_WINNERS_MIN - 1, months=3)
+
+
+@pytest.mark.asyncio
+async def test_giveaway_premium_winners_too_high(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.giveaway_premium("@channel", winners=PREMIUM_WINNERS_MAX + 1, months=3)
+
+
+@pytest.mark.asyncio
+async def test_giveaway_premium_float_winners(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.giveaway_premium("@channel", winners=2.5, months=3)  # type: ignore[arg-type]
+
+
+@pytest.mark.asyncio
+async def test_giveaway_premium_invalid_months(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.giveaway_premium("@channel", winners=10, months=5)
+
+
+@pytest.mark.asyncio
+async def test_giveaway_premium_invalid_payment_method(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError, match="Invalid payment method"):
+        await client.giveaway_premium("@channel", winners=10, months=3, payment_method="btc")  # type: ignore[arg-type]
+
+
+# Premium giveaway mocked tests
+
+
+@pytest.mark.asyncio
+async def test_giveaway_premium_success(client: FragmentClient) -> None:
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},
+                    {},
+                    {"req_id": FAKE_REQ_ID},
+                    FAKE_TRANSACTION,
+                ]
+            ),
+        ),
+        patch.object(_giveaway_premium_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+        patch.object(_giveaway_premium_mod, "process_transaction", AsyncMock(return_value=FAKE_TX_HASH)),
+    ):
+        result = await client.giveaway_premium("@channel", winners=10, months=3)
+
+    assert isinstance(result, PremiumGiveawayResult)
+    assert result.transaction_id == FAKE_TX_HASH
+    assert result.channel == "@channel"
+    assert result.winners == 10
+    assert result.amount == 3
+
+
+@pytest.mark.asyncio
+async def test_giveaway_premium_passes_payment_method(client: FragmentClient) -> None:
+    call_mock = AsyncMock(
+        side_effect=[
+            {"found": {"recipient": FAKE_RECIPIENT}},
+            {},
+            {},
+            {"req_id": FAKE_REQ_ID},
+            FAKE_TRANSACTION,
+        ]
+    )
+    proc_mock = AsyncMock(return_value=FAKE_TX_HASH)
+    with (
+        patch.object(client, "call", call_mock),
+        patch.object(_giveaway_premium_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+        patch.object(_giveaway_premium_mod, "process_transaction", proc_mock),
+    ):
+        await client.giveaway_premium("@channel", winners=10, months=6, payment_method=PaymentMethod.USDT_GRAM)
+
+    init_call = call_mock.await_args_list[3]
+    assert init_call.args[0] == "initGiveawayPremiumRequest"
+    assert init_call.args[1]["payment_method"] == "usdt_ton"
+    assert proc_mock.await_args is not None
+    assert proc_mock.await_args.kwargs["payment_method"] == "usdt_ton"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("query", ["@channel", "monk", "https://t.me/id2757542991"])
+async def test_giveaway_premium_accepts_query_formats(client: FragmentClient, query: str) -> None:
+    call_mock = AsyncMock(return_value={"found": {}})
+    with patch.object(client, "call", call_mock):
+        with pytest.raises(UserNotFoundError):
+            await client.giveaway_premium(query, winners=10, months=3)
+
+    search_call = call_mock.await_args_list[0]
+    assert search_call.args[0] == "searchPremiumGiveawayRecipient"
+    assert search_call.args[1]["query"] == query
+
+
+@pytest.mark.asyncio
+async def test_giveaway_premium_channel_not_found(client: FragmentClient) -> None:
+    with patch.object(client, "call", AsyncMock(return_value={"found": {}})):
+        with pytest.raises(UserNotFoundError):
+            await client.giveaway_premium("@ghost", winners=1, months=3)
+
+
+# Premium purchase — error branches
+
+
+@pytest.mark.asyncio
+async def test_purchase_premium_not_a_user_raises(client: FragmentClient) -> None:
+    with patch.object(client, "call", AsyncMock(return_value={"error": "Please enter a username assigned to a user."})):
+        with pytest.raises(UserNotFoundError, match="does not belong"):
+            await client.purchase_premium("@channel", months=3)
+
+
+@pytest.mark.asyncio
+async def test_purchase_premium_missing_req_id_raises(client: FragmentClient) -> None:
+    from pyfragment.exceptions import FragmentAPIError
+
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},  # updatePremiumState
+                    {"amount": "0.1"},  # initGiftPremiumRequest — no req_id
+                ]
+            ),
+        ),
+        patch.object(_purchase_premium_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+    ):
+        with pytest.raises(FragmentAPIError):
+            await client.purchase_premium("@user", months=3)
+
+
+@pytest.mark.asyncio
+async def test_purchase_premium_need_verify_raises(client: FragmentClient) -> None:
+    from pyfragment.exceptions import VerificationError
+
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},  # updatePremiumState
+                    {"req_id": FAKE_REQ_ID},
+                    {"need_verify": True},  # getGiftPremiumLink
+                ]
+            ),
+        ),
+        patch.object(_purchase_premium_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+    ):
+        with pytest.raises(VerificationError):
+            await client.purchase_premium("@user", months=3)
+
+
+# Premium giveaway — error branches
+
+
+@pytest.mark.asyncio
+async def test_giveaway_premium_missing_req_id_raises(client: FragmentClient) -> None:
+    from pyfragment.exceptions import FragmentAPIError
+
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},  # updatePremiumGiveawayState
+                    {},  # updatePremiumGiveawayPrices
+                    {"amount": "0.1"},  # initGiveawayPremiumRequest — no req_id
+                ]
+            ),
+        ),
+        patch.object(_giveaway_premium_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+    ):
+        with pytest.raises(FragmentAPIError):
+            await client.giveaway_premium("@channel", winners=10, months=3)
+
+
+@pytest.mark.asyncio
+async def test_giveaway_premium_need_verify_raises(client: FragmentClient) -> None:
+    from pyfragment.exceptions import VerificationError
+
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {},  # updatePremiumGiveawayState
+                    {},  # updatePremiumGiveawayPrices
+                    {"req_id": FAKE_REQ_ID},
+                    {"need_verify": True},  # getGiveawayPremiumLink
+                ]
+            ),
+        ),
+        patch.object(_giveaway_premium_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+    ):
+        with pytest.raises(VerificationError):
+            await client.giveaway_premium("@channel", winners=10, months=3)

tests/006_test_topup.py

@@ -0,0 +1,123 @@
+"""Cover GRAM (ex TON) top-up through Telegram Ads, including recipient lookup and transaction building."""
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+import pyfragment.domains.ads.tonup as _topup_gram_mod
+from pyfragment import AdsTopupResult, ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.core.constants import GRAM_TOPUP_MAX, GRAM_TOPUP_MIN
+from tests.shared import FAKE_ACCOUNT, FAKE_RECIPIENT, FAKE_REQ_ID, FAKE_TRANSACTION, FAKE_TX_HASH
+
+# Topup GRAM (ex TON) validation tests
+
+
+@pytest.mark.asyncio
+async def test_topup_gram_amount_zero(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.topup_gram("@user", amount=GRAM_TOPUP_MIN - 1)
+
+
+@pytest.mark.asyncio
+async def test_topup_gram_amount_too_high(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.topup_gram("@user", amount=GRAM_TOPUP_MAX + 1)
+
+
+@pytest.mark.asyncio
+async def test_topup_gram_float_amount(client: FragmentClient) -> None:
+    with pytest.raises(ConfigurationError):
+        await client.topup_gram("@user", amount=1.5)  # type: ignore[arg-type]
+
+
+# Topup GRAM (ex TON) mocked tests
+
+
+@pytest.mark.asyncio
+async def test_topup_gram_success(client: FragmentClient) -> None:
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {},  # updateAdsTopupState
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {"req_id": FAKE_REQ_ID},
+                    FAKE_TRANSACTION,
+                ]
+            ),
+        ),
+        patch.object(_topup_gram_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+        patch.object(_topup_gram_mod, "process_transaction", AsyncMock(return_value=FAKE_TX_HASH)),
+    ):
+        result = await client.topup_gram("@user", amount=10)
+
+    assert isinstance(result, AdsTopupResult)
+    assert result.transaction_id == FAKE_TX_HASH
+    assert result.username == "@user"
+    assert result.amount == 10
+
+
+@pytest.mark.asyncio
+async def test_topup_gram_user_not_found(client: FragmentClient) -> None:
+    with patch.object(
+        client,
+        "call",
+        AsyncMock(
+            side_effect=[
+                {},  # updateAdsTopupState
+                {"found": {}},
+            ]
+        ),
+    ):
+        with pytest.raises(UserNotFoundError):
+            await client.topup_gram("@ghost", amount=10)
+
+
+# topup_gram — error branches
+
+
+@pytest.mark.asyncio
+async def test_topup_gram_missing_req_id_raises(client: FragmentClient) -> None:
+    from pyfragment.exceptions import FragmentAPIError
+
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {},  # updateAdsTopupState
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {"amount": "0.1"},  # initAdsTopupRequest — no req_id
+                ]
+            ),
+        ),
+        patch.object(_topup_gram_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+    ):
+        with pytest.raises(FragmentAPIError):
+            await client.topup_gram("@user", amount=10)
+
+
+@pytest.mark.asyncio
+async def test_topup_gram_need_verify_raises(client: FragmentClient) -> None:
+    from pyfragment.exceptions import VerificationError
+
+    with (
+        patch.object(
+            client,
+            "call",
+            AsyncMock(
+                side_effect=[
+                    {},  # updateAdsTopupState
+                    {"found": {"recipient": FAKE_RECIPIENT}},
+                    {"req_id": FAKE_REQ_ID},
+                    {"need_verify": True},  # getAdsTopupLink
+                ]
+            ),
+        ),
+        patch.object(_topup_gram_mod, "get_account_info", AsyncMock(return_value=FAKE_ACCOUNT)),
+    ):
+        with pytest.raises(VerificationError):
+            await client.topup_gram("@user", amount=10)

tests/007_test_wallet.py

@@ -0,0 +1,154 @@
+"""Verify wallet inspection returns friendly GRAM (ex TON) and USDT balances from Tonapi."""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from pyfragment import FragmentClient, WalletInfo
+from tests.shared import FAKE_ADDRESS, FAKE_BALANCE_NANOGRAM
+
+# Wallet mocked tests (GRAM and USDT balances are returned separately)
+
+
+@pytest.mark.asyncio
+async def test_get_wallet_returns_wallet_info(client: FragmentClient) -> None:
+    mock_wallet = MagicMock()
+    mock_wallet.refresh = AsyncMock()
+    mock_wallet.balance = FAKE_BALANCE_NANOGRAM
+    mock_wallet.state = MagicMock(value="active")
+    mock_wallet.address.to_str.return_value = FAKE_ADDRESS
+
+    with (
+        patch("pyfragment.services.tonapi.account._make_ton_client") as mock_tonapi,
+        patch("pyfragment.services.tonapi.account.WALLET_CLASSES") as mock_classes,
+        patch("pyfragment.services.tonapi.account.get_usdt_balance", AsyncMock(return_value=12.3456)),
+    ):
+        mock_tonapi.return_value.__aenter__ = AsyncMock(return_value=MagicMock())
+        mock_tonapi.return_value.__aexit__ = AsyncMock(return_value=False)  # _make_ton_client returns context manager
+        mock_classes["V5R1"].from_mnemonic.return_value = (mock_wallet, MagicMock(), None, None)
+
+        result = await client.get_wallet()
+
+    assert isinstance(result, WalletInfo)
+    assert result.address == FAKE_ADDRESS
+    assert result.state == "active"
+    assert result.gram_balance == round(FAKE_BALANCE_NANOGRAM / 1_000_000_000, 4)
+    assert result.usdt_balance == 12.3456
+
+
+@pytest.mark.asyncio
+async def test_get_wallet_balance_is_zero(client: FragmentClient) -> None:
+    mock_wallet = MagicMock()
+    mock_wallet.refresh = AsyncMock()
+    mock_wallet.balance = 0
+    mock_wallet.state = MagicMock(value="uninit")
+    mock_wallet.address.to_str.return_value = FAKE_ADDRESS
+
+    with (
+        patch("pyfragment.services.tonapi.account._make_ton_client") as mock_tonapi,
+        patch("pyfragment.services.tonapi.account.WALLET_CLASSES") as mock_classes,
+        patch("pyfragment.services.tonapi.account.get_usdt_balance", AsyncMock(return_value=0.0)),
+    ):
+        mock_tonapi.return_value.__aenter__ = AsyncMock(return_value=MagicMock())
+        mock_tonapi.return_value.__aexit__ = AsyncMock(return_value=False)  # _make_ton_client returns context manager
+        mock_classes["V5R1"].from_mnemonic.return_value = (mock_wallet, MagicMock(), None, None)
+
+        result = await client.get_wallet()
+
+    assert result.gram_balance == 0.0
+    assert result.usdt_balance == 0.0
+    assert result.state == "uninit"
+
+
+# _make_ton_client — provider selection
+
+
+def test_make_ton_client_uses_toncenter_for_toncenter_provider(client: FragmentClient) -> None:
+    from tonutils.clients import ToncenterClient
+
+    from pyfragment.enums import ApiProvider
+    from pyfragment.services.tonapi.account import _make_ton_client
+
+    client.api_provider = ApiProvider.TONCENTER
+    result = _make_ton_client(client)
+    assert isinstance(result, ToncenterClient)
+
+
+def test_make_ton_client_uses_tonapi_for_tonapi_provider(client: FragmentClient) -> None:
+    from tonutils.clients import TonapiClient
+
+    from pyfragment.enums import ApiProvider
+    from pyfragment.services.tonapi.account import _make_ton_client
+
+    client.api_provider = ApiProvider.TONAPI
+    result = _make_ton_client(client)
+    assert isinstance(result, TonapiClient)
+
+
+# get_usdt_balance — error paths
+
+
+@pytest.mark.asyncio
+async def test_get_usdt_balance_non_404_provider_error_raises() -> None:
+    from tonutils.exceptions import ProviderResponseError
+
+    from pyfragment import WalletError
+    from pyfragment.services.tonapi.account import get_usdt_balance
+
+    ton = MagicMock()
+    err = ProviderResponseError(code=500, message="server error", endpoint="api.tonapi.io")
+
+    with patch("pyfragment.services.tonapi.account.get_wallet_address_get_method", AsyncMock(side_effect=err)):
+        with pytest.raises(WalletError):
+            await get_usdt_balance(ton, "0:abc")
+
+
+@pytest.mark.asyncio
+async def test_get_usdt_balance_generic_exception_raises() -> None:
+    from pyfragment import WalletError
+    from pyfragment.services.tonapi.account import get_usdt_balance
+
+    ton = MagicMock()
+
+    with patch(
+        "pyfragment.services.tonapi.account.get_wallet_address_get_method", AsyncMock(side_effect=RuntimeError("timeout"))
+    ):
+        with pytest.raises(WalletError):
+            await get_usdt_balance(ton, "0:abc")
+
+
+# get_account_info / get_wallet_info — exception paths
+
+
+@pytest.mark.asyncio
+async def test_get_account_info_exception_raises_wallet_error(client: FragmentClient) -> None:
+    from pyfragment import WalletError
+    from pyfragment.services.tonapi.account import get_account_info
+
+    with (
+        patch("pyfragment.services.tonapi.account._make_ton_client") as mock_tonapi,
+        patch("pyfragment.services.tonapi.account.WALLET_CLASSES") as mock_classes,
+    ):
+        mock_tonapi.return_value.__aenter__ = AsyncMock(return_value=MagicMock())
+        mock_tonapi.return_value.__aexit__ = AsyncMock(return_value=False)
+        mock_classes["V5R1"].from_mnemonic.side_effect = RuntimeError("wallet init failed")
+
+        with pytest.raises(WalletError, match="account info"):
+            await get_account_info(client)
+
+
+@pytest.mark.asyncio
+async def test_get_wallet_info_exception_raises_wallet_error(client: FragmentClient) -> None:
+    from pyfragment import WalletError
+    from pyfragment.services.tonapi.account import get_wallet_info
+
+    with (
+        patch("pyfragment.services.tonapi.account._make_ton_client") as mock_tonapi,
+        patch("pyfragment.services.tonapi.account.WALLET_CLASSES") as mock_classes,
+    ):
+        mock_tonapi.return_value.__aenter__ = AsyncMock(return_value=MagicMock())
+        mock_tonapi.return_value.__aexit__ = AsyncMock(return_value=False)
+        mock_classes["V5R1"].from_mnemonic.side_effect = RuntimeError("key derivation failed")
+
+        with pytest.raises(WalletError, match="wallet info"):
+            await get_wallet_info(client)