Metadata-Version: 2.4
Name: fragment-api-dev
Version: 1.1.0
Summary: Python SDK for live GRAM/USDT prices and buying Telegram Stars and Premium through Fragment
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.

## Prices

Get the 50-Stars reference price and Premium prices for 3, 6, and 12 months before showing a price to your customer:

```python
catalog = api.get_prices()
print(catalog.stars.amount, catalog.stars.prices.gram, catalog.stars.prices.usdt)

quote = api.get_stars_price(100)
print(quote.prices.gram, quote.prices.usdt)
```

Use `get_premium_price(3)`, `get_premium_price(6)`, or `get_premium_price(12)` for Premium. Price values are strings to preserve their exact decimal value. A quote can have `stale=True` when the latest available quote is being served.

## 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 |
| `get_prices()` | Read the 50-Stars reference and Premium price catalog |
| `get_price()` | Read a Stars or Premium quote |
| `get_stars_price()` | Read a Stars quote for 50 to 1,000,000 Stars |
| `get_premium_price()` | Read a quote for 3, 6, or 12 months of Premium |
| `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)
