pyfragment 2026.0.1__tar.gz

pyfragment-2026.0.1/.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.

pyfragment-2026.0.1/.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.

pyfragment-2026.0.1/.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.

pyfragment-2026.0.1/.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

pyfragment-2026.0.1/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - 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"

pyfragment-2026.0.1/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: actions/setup-python@v6.2.0
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v7.5.0
+
+      - run: uv pip install --system ".[dev]"
+
+      - run: ruff check .
+
+      - run: black --check . --target-version py312
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: actions/setup-python@v6.2.0
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v7.5.0
+
+      - run: uv pip install --system ".[dev]"
+
+      - name: Write cookies.json
+        if: ${{ env.COOKIES_JSON != '' }}
+        run: echo "$COOKIES_JSON" > cookies.json
+        env:
+          COOKIES_JSON: ${{ secrets.COOKIES_JSON }}
+
+      - run: pytest

pyfragment-2026.0.1/.github/workflows/publish.yml

@@ -0,0 +1,101 @@
+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.0.2
+        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.0.2
+
+      - uses: actions/setup-python@v6.2.0
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v7.5.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.0.1
+        with:
+          name: dist
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@v1.13.0
+
+  release:
+    name: GitHub Release
+    needs: [version-check, build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: dist
+          path: dist
+
+      - uses: softprops/action-gh-release@v2.6.1
+        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

pyfragment-2026.0.1/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+
+# Logs
+logs/
+*.log
+
+# Environment variables
+.env
+
+# System files
+.DS_Store
+Thumbs.db
+
+# Testing & tooling artifacts
+.hypothesis/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+demo.run.py
+
+# Build & distribution
+dist/
+build/
+*.egg-info/

pyfragment-2026.0.1/CHANGELOG.md

@@ -0,0 +1,24 @@
+# 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.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.0.1]: https://github.com/bohd4nx/pyfragment/releases/tag/v2026.0.1

pyfragment-2026.0.1/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.

pyfragment-2026.0.1/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: pyfragment
+Version: 2026.0.1
+Summary: Python library for the Fragment.com API — purchase Telegram Stars, Premium, and top up TON Ads balance.
+Project-URL: Homepage, https://github.com/bohd4nx/pyfragment
+Project-URL: Repository, https://github.com/bohd4nx/pyfragment
+Project-URL: Issues, https://github.com/bohd4nx/pyfragment/issues
+Project-URL: Changelog, https://github.com/bohd4nx/pyfragment/blob/master/CHANGELOG.md
+Author: bohd4nx
+License: MIT
+License-File: LICENSE
+Keywords: blockchain,crypto,fragment,premium,stars,telegram,ton
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx==0.28.1
+Requires-Dist: tonutils[pytoniq]==2.0.4
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
+Requires-Dist: pytest==9.0.2; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="fragment.svg" alt="Fragment Logo" width="120" height="120" style="border-radius: 24px;">
+
+  <h1 style="margin-top: 24px;">Fragment API</h1>
+
+  <p style="font-size: 18px; margin-bottom: 24px;">
+    <b>Python library for the Fragment.com API — purchase Telegram Stars, Premium, and top up TON Ads balance.</b>
+  </p>
+
+[![PyPI version](https://img.shields.io/pypi/v/pyfragment?style=flat&color=blue)](https://pypi.org/project/pyfragment/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/pyfragment?style=flat&color=brightgreen)](https://pypi.org/project/pyfragment/)
+[![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=flat&logo=python&logoColor=white)](https://python.org)
+[![License](https://img.shields.io/github/license/bohd4nx/pyfragment?style=flat&color=lightgrey)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/bohd4nx/pyfragment?style=flat&color=yellow)](https://github.com/bohd4nx/pyfragment/stargazers)
+[![CI](https://img.shields.io/github/actions/workflow/status/bohd4nx/pyfragment/ci.yml?style=flat&label=tests&logo=github)](https://github.com/bohd4nx/pyfragment/actions)
+
+[Report Bug](https://github.com/bohd4nx/pyfragment/issues) · [Request Feature](https://github.com/bohd4nx/pyfragment/issues) · [**Donate TON**](https://app.tonkeeper.com/transfer/UQCppfw5DxWgdVHf3zkmZS8k1mt9oAUYxQLwq2fz3nhO8No5)
+
+</div>
+
+> **Disclaimer:** This project is not affiliated with, endorsed by, or in any way officially connected with [Fragment](https://fragment.com) or [Telegram](https://telegram.org).
+
+---
+
+## ✨ Features
+
+- 💰 **TON Advertisement Topups** — Top up Telegram Ads balance (1–1,000,000,000 TON)
+- 👑 **Telegram Premium** — Purchase Premium for any user (3, 6, or 12 months)
+- ⭐ **Telegram Stars Purchases** — Purchase Stars for any Telegram user (50–1,000,000 Stars)
+- 🔐 **Multi-wallet support** — V4R2 and V5R1 wallet contract versions
+- ⚡ **Async-first** — Built on `httpx` and `asyncio`
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pyfragment
+```
+
+Requires **Python 3.12+**.
+
+---
+
+## 🚀 Quick Start
+
+```python
+import asyncio
+from pyfragment import FragmentClient
+
+async def main():
+    async with FragmentClient(
+        seed="word1 word2 ... word24",
+        api_key="YOUR_TONAPI_KEY",
+        cookies={
+            "stel_ssid": "...",
+            "stel_dt": "...",
+            "stel_token": "...",
+            "stel_ton_token": "...",
+        },
+    ) as client:
+        # Purchase 6 months of Telegram Premium
+        result = await client.purchase_premium("@username", months=6)
+        print(result.transaction_id)
+
+        # Purchase 500 Stars
+        result = await client.purchase_stars("@username", amount=500)
+        print(result.transaction_id)
+
+        # Top up 10 TON to Ads balance
+        result = await client.topup_ton("@username", amount=10)
+        print(result.transaction_id)
+
+asyncio.run(main())
+```
+
+See the [`examples/`](examples/) folder for ready-to-run scripts.
+
+---
+
+## 🔧 Configuration
+
+### `FragmentClient` parameters
+
+| Parameter        | Type          | Required | Default  | Description                                              |
+| ---------------- | ------------- | -------- | -------- | -------------------------------------------------------- |
+| `seed`           | `str`         | ✅        | —        | 24-word TON wallet mnemonic phrase                       |
+| `api_key`        | `str`         | ✅        | —        | Tonapi key from [tonconsole.com](https://tonconsole.com) |
+| `cookies`        | `dict \| str` | ✅        | —        | Fragment session cookies (dict or JSON string)           |
+| `wallet_version` | `str`         | ❌        | `"V5R1"` | Wallet contract version: `"V4R2"` or `"V5R1"`            |
+
+### Methods
+
+> Usernames can be passed with or without `@`.
+
+| Method                                             | Returns          | Description                        | Limits                    |
+| -------------------------------------------------- | ---------------- | ---------------------------------- | ------------------------- |
+| `purchase_premium(username, months, show_sender=True)` | `PremiumResult`  | Purchase Telegram Premium          | `months`: 3, 6, or 12     |
+| `purchase_stars(username, amount, show_sender=True)`   | `StarsResult`    | Purchase Telegram Stars            | `amount`: 50–1,000,000    |
+| `topup_ton(username, amount, show_sender=True)`    | `AdsTopupResult` | Top up Telegram Ads balance        | `amount`: 1–1,000,000,000 |
+| `get_wallet()`                                     | `WalletInfo`     | Get wallet address, state, balance | —                         |
+
+---
+
+## ⚙️ Getting Required Credentials
+
+### 🍪 Fragment.com Cookies
+
+**Prerequisites**: Log in to [fragment.com](https://fragment.com), connect your TON wallet.
+
+1. Install [Cookie Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm)
+2. Open [fragment.com](https://fragment.com) while logged in
+3. Click the extension → **Export** → **Header String**
+4. Extract these four fields:
+
+```json
+{
+  "stel_ssid": "...",
+  "stel_dt": "...",
+  "stel_token": "...",
+  "stel_ton_token": "..."
+}
+```
+
+> ⚠️ Cookies expire. Refresh them if you start getting `FragmentPageError` or auth errors.
+
+### 🔑 Tonapi Key
+
+1. Go to [tonconsole.com](https://tonconsole.com)
+2. Register and generate a new API key
+3. Pass it as `api_key` to `FragmentClient`
+
+### 🌱 Wallet Seed Phrase
+
+If you don't have a TON wallet, create one in [Tonkeeper](https://tonkeeper.com).  
+Go to **Settings → Backup** → copy the 24 words.
+
+> ⚠️ Never share your seed phrase. Store it offline.
+
+### 🔐 Wallet Version
+
+| Version | Use when                                                       |
+| ------- | -------------------------------------------------------------- |
+| `V5R1`  | Default — Tonkeeper / MyTonWallet (wallets created after 2024) |
+| `V4R2`  | Older Tonkeeper or hardware wallets                            |
+
+---
+
+## 🗂️ Error Handling
+
+All exceptions inherit from `FragmentError` — see [`pyfragment/types/exceptions.py`](pyfragment/types/exceptions.py) for the full list.
+
+```python
+from pyfragment import FragmentClient, UserNotFoundError, ConfigurationError, WalletError
+
+try:
+    result = await client.purchase_stars("@unknown", amount=100)
+except UserNotFoundError:
+    print("User not found on Fragment")
+except WalletError as e:
+    print(f"Wallet issue: {e}")
+except ConfigurationError as e:
+    print(f"Bad params: {e}")
+```
+
+---
+
+<div align="center">
+
+### Made with ❤️ by [@bohd4nx](https://t.me/bohd4nx)
+
+**Star ⭐ this repo if you found it useful!**
+
+</div>