Metadata-Version: 2.4
Name: fragment-api-py
Version: 5.0.0
Summary: Professional Python library for Fragment.com API
Home-page: https://github.com/S1qwy/fragment-api-py
Author: S1qwy
Author-email: S1qwy@internet.ru
Project-URL: Bug Reports, https://github.com/S1qwy/fragment-api-py/issues
Project-URL: Source, https://github.com/S1qwy/fragment-api-py
Keywords: fragment telegram ton premium stars api
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: tonutils>=0.4.0
Requires-Dist: tonsdk>=1.2.0
Requires-Dist: pynacl>=1.5.0
Requires-Dist: ton-core>=0.1.0
Provides-Extra: async
Requires-Dist: aiohttp>=3.9.0; extra == "async"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: aiohttp>=3.9.0; extra == "all"
Requires-Dist: pytest>=7.0.0; extra == "all"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Fragment API Python

Professional Python library for [Fragment.com](https://fragment.com) automation — Telegram Stars, Premium, marketplace bidding, anonymous numbers, and giveaways. Sync + Async.

[![PyPI](https://img.shields.io/pypi/v/fragment-api-py.svg)](https://pypi.org/project/fragment-api-py/)
[![Python](https://img.shields.io/pypi/pyversions/fragment-api-py.svg)](https://pypi.org/project/fragment-api-py/)
[![Telegram](https://img.shields.io/badge/Telegram-Channel-2CA5E0?logo=telegram)](https://t.me/fragment_api_py)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

---

## Features

- **Sync & Async** — `FragmentClient` and `AsyncFragmentClient`
- **Purchases** — Stars (50–1M), Premium (3/6/12 months), TON Ads top-up
- **Payment Methods** — `ton` (default) and `usdt_ton`
- **Giveaways** — Stars and Premium for Telegram channels
- **Bidding / Buy Now** — `place_bid(item_type=1|3|5, slug, bid)`
- **Marketplace Search** — usernames, anonymous numbers, gift NFTs with filters + pagination
- **Anonymous Numbers** — `get_login_code()`, `toggle_login_codes()`, `terminate_sessions()`
- **Auto-Authentication** — generate cookies from mnemonic + Telegram phone (no manual copy)
- **Wallet** — V4R2 and V5R1 (W5), TON + USDT balance
- **Session Management** — list/terminate Fragment.com sessions
- **Full Exception Hierarchy** — precise error handling

---

## Installation

```bash
pip install fragment-api-py[async]   # sync + async
```

---

## Quick Start

```python
from FragmentAPI import FragmentClient

client = FragmentClient(
    seed="your 24-word mnemonic...",
    cookies={"stel_ssid": "...", "stel_token": "...", "stel_dt": "...", "stel_ton_token": "..."}
)

# Wallet info (TON + USDT)
wallet = client.get_wallet()
print(f"{wallet.balance_ton} TON, {wallet.balance_usdt} USDT")

# Purchase Stars with USDT
result = client.purchase_stars("@username", amount=100, payment_method="usdt_ton")

# Purchase Premium (3/6/12 months)
result = client.purchase_premium("@username", months=6, show_sender=True)

# Place a bid on a username (type 1)
client.place_bid(1, "username", bid=150)

# Place a bid on a number (type 3)
client.place_bid(3, "123456789", bid=50)

# Place a bid + buy-now on a gift (type 5)
client.place_bid(5, "gift-slug", bid=500)  # if bid == buy-now price → instant purchase

# Stars giveaway
client.giveaway_stars("@channel", winners=5, amount=1000)

# Search marketplace
items = client.search_usernames("gold", sort="price_asc", filter="sale")
for item in items.items:
    print(f"{item['name']} — {item['price']} TON")

# Anonymous number: get login code
code_info = client.get_login_code("+888123456789")
print(f"Code: {code_info.code}, Active sessions: {code_info.active_sessions}")

# Terminate all Telegram sessions for a number
client.terminate_sessions("+888123456789")
```

---

## Auto-Authentication (No Manual Cookies)

```python
from FragmentAPI import FragmentClient

# Get cookies automatically using TON wallet + Telegram phone
cookies = FragmentClient.authenticate(
    seed="your 24-word mnemonic...",
    wallet_version="V5R1",           # "V4R2" or "V5R1"
    telegram_phone="+71234567890"    # or telegram_auth_data
)

client = FragmentClient(seed="...", cookies=cookies)
```

---

## Async Example

```python
from FragmentAPI import AsyncFragmentClient

async with AsyncFragmentClient(seed="...", cookies=...) as client:
    wallet = await client.get_wallet()
    result = await client.purchase_stars("@username", 100)
    info = await client.get_username_info("@username")
```

---

## Detailed Item Info

```python
# Username details (bid history, owner history, auction timers)
info = client.get_username_info("@durov")
print(info.status, info.auction.buy_now_price)
print(info.bid_history)
print(info.owner_history)

# Number details (restricted detection)
info = client.get_number_info("+888123456789")
print(info.restricted)

# Gift details (attributes, rarity, image/sticker URLs)
info = client.get_gift_info("gift-slug")
for attr in info.attributes:
    print(f"{attr.name}: {attr.value} (rarity: {attr.rarity})")
```

---

## Requirements

- Python 3.10+
- Fragment session cookies: `stel_ssid`, `stel_dt`, `stel_token`, `stel_ton_token`
- TON wallet mnemonic with sufficient balance

---

## Error Reporting

If you encounter an unexpected error, please report it:

- [GitHub Issues](https://github.com/S1qwy/fragment-api-py/issues)
- [Telegram Chat](https://t.me/fragment_api_py)

This helps expand the exception database.

---

## Links

- **Documentation**: [https://fragment.s1qwy.ru](https://fragment.s1qwy.ru)
- **Telegram Community**: [https://t.me/fragment_api_py](https://t.me/fragment_api_py)
- **GitHub**: [https://github.com/S1qwy/fragment-api-py](https://github.com/S1qwy/fragment-api-py)

---

## License

**MIT** — free for any use.

Developed by [S1qwy](https://github.com/S1qwy) — `S1qwy@internet.ru`
