Metadata-Version: 2.4
Name: fragment-api-dev
Version: 1.0.1
Summary: Python SDK for buying Telegram Stars and Premium through Fragment with GRAM or USDT on TON
Author: labamgo
License-Expression: MIT
Project-URL: Homepage, https://github.com/labamgo/fragment-api-dev
Project-URL: Documentation, https://github.com/labamgo/fragment-api-dev#quick-start
Project-URL: Repository, https://github.com/labamgo/fragment-api-dev
Project-URL: Issues, https://github.com/labamgo/fragment-api-dev/issues
Project-URL: API Status, https://api-stars.duckdns.org/health
Keywords: telegram stars api,telegram premium api,fragment api,fragment stars,telegram bot,ton blockchain,gram,usdt ton,python sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# fragment-api-dev

[![PyPI](https://img.shields.io/pypi/v/fragment-api-dev?style=flat-square&color=0ea5e9)](https://pypi.org/project/fragment-api-dev/)
[![Python](https://img.shields.io/pypi/pyversions/fragment-api-dev?style=flat-square)](https://pypi.org/project/fragment-api-dev/)
[![License](https://img.shields.io/pypi/l/fragment-api-dev?style=flat-square)](https://github.com/labamgo/fragment-api-dev/blob/main/LICENSE)
[![API](https://img.shields.io/badge/API-ONLINE-22c55e?style=flat-square)](https://api-stars.duckdns.org/health)

The focused Python SDK for buying **Telegram Stars** and **Telegram Premium** through Fragment.

- GRAM and USDT on TON
- No API key
- Automatic status polling
- Zero runtime dependencies

## Install

```bash
pip install fragment-api-dev
```

## Quick start

```python
import os

from fragment_api import FragmentAPI


api = FragmentAPI()

purchase = api.buy_stars(
    username="@telegram_user",
    amount=50,
    payment_method="gram",
    seed=os.environ["TON_WALLET_SEED"],
)

result = api.wait(purchase.purchase_id)

if result.completed:
    print("Delivered:", result.transaction_hash)
else:
    print("Not completed:", result.status, result.error)
```

The SDK generates an idempotency key automatically, submits the purchase, and provides a typed `Purchase` result.

## Telegram Premium

```python
purchase = api.buy_premium(
    username="@telegram_user",
    months=3,
    payment_method="usdt",
    seed=os.environ["TON_WALLET_SEED"],
)

result = api.wait(purchase.purchase_id)
```

Premium durations are `3`, `6`, or `12` months.

## Payments

| Value | Payment |
|---|---|
| `gram` | GRAM on TON |
| `usdt` | USDT on TON |

USDT purchases require a small GRAM balance for the network fee.

## Public API

| Method | Purpose |
|---|---|
| `buy_stars()` | Buy 50 or more Telegram Stars |
| `buy_premium()` | Buy Telegram Premium |
| `create_purchase()` | Create a purchase with explicit product fields |
| `get_purchase()` | Read the latest purchase state |
| `wait()` | Poll until the purchase reaches a terminal state |

No authentication token or API key is required.

## Links

- [GitHub repository](https://github.com/labamgo/fragment-api-dev)
- [REST and Node.js examples](https://github.com/labamgo/fragment-api-dev#direct-rest)
- [OpenAPI specification](https://github.com/labamgo/fragment-api-dev/blob/main/openapi.yaml)
- [API status](https://api-stars.duckdns.org/health)
- [Integration support](https://github.com/labamgo/fragment-api-dev/issues)
