Metadata-Version: 2.4
Name: fragment-api-dev
Version: 1.2.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)
[![SDK](https://img.shields.io/badge/SDK-1.2.0-0ea5e9?style=flat-square)](https://pypi.org/project/fragment-api-dev/1.2.0/)

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

This example uses a 12-word wallet at account index `0`. If you use a 24-word TON mnemonic or a Base64 32-byte private key, remove `account_index`.

```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"],
    account_index=0,  # Required for a 12-word 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.

## 12-word wallets

A 12-word wallet can contain many TON accounts. Tell the API which account pays:

| What you know | Send | What happens |
|---|---|---|
| Seed + wallet address | `seed`, `wallet_address` | The API finds the index |
| Seed + account index | `seed`, `account_index` | The API uses V5R1 at that index |
| Seed + address + index | all three | The API verifies and uses that exact wallet |

**A 12-word seed alone is not enough. Send `wallet_address` or `account_index`.**

```python
wallet = api.resolve_wallet(
    seed=os.environ["TON_WALLET_SEED"],
    wallet_address=os.environ["TON_WALLET_ADDRESS"],
)

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

If you already know the index, skip `resolve_wallet()` and pass `account_index=0` (or your actual index). You may also pass `wallet_address="UQ..."` directly. The API searches indices `0..20` during a purchase and `0..100` through `resolve_wallet()`.

For a 24-word TON mnemonic or Base64 32-byte private key, omit both wallet selectors.

## Wallet selection errors

`FragmentAPIError` exposes `code` and `action` so your app can show the correct next step.

| Code | Client action |
|---|---|
| `WALLET_SELECTION_REQUIRED` | Add `wallet_address` or `account_index` |
| `INVALID_BIP39_SEED` | Check all 12 words and their order |
| `INVALID_WALLET_ADDRESS` | Send a valid TON friendly or raw address |
| `INVALID_ACCOUNT_INDEX` | Send an integer from 0 to 100 |
| `WALLET_ADDRESS_MISMATCH` | Remove the index to search, or correct it |
| `WALLET_INDEX_NOT_FOUND` | Call the resolver, then use its returned index |
| `WALLET_RESOLVER_BUSY` | Wait briefly and retry the same resolve request |

## 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"],
    account_index=0,  # Required for a 12-word 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 |
| `resolve_wallet()` | Find the account index for a 12-word wallet |
| `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#examples)
- [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)
