Metadata-Version: 2.4
Name: fragment-api-py
Version: 3.0.2
Summary: Python client for the Fragment API
Home-page: https://github.com/S1qwy/fragment-api-py
Author: S1qwy
Author-email: amirhansuper75@example.com
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: tonutils>=0.3.0
Requires-Dist: pytoniq-core>=0.1.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Fragment API Python

Professional Python library for Fragment.com API with async and sync support. Send Telegram Stars, Premium, and TON with automatic wallet validation.

## Features

- ✅ Async & Sync interfaces
- ✅ 3 payment methods (Stars, Premium, TON)
- ✅ Automatic wallet balance validation
- ✅ WalletV4R2 support
- ✅ Comprehensive error handling
- ✅ Type hints & logging

## Installation

```bash
pip install fragment-api-py
```

## Quick Start

### Synchronous

```python
from FragmentAPI import SyncFragmentAPI

api = SyncFragmentAPI(
    cookies="your_cookies",
    hash_value="your_hash",
    wallet_mnemonic="your mnemonic...",
    wallet_api_key="your_api_key"
)

result = api.buy_stars('username', 100)
if result.success:
    print(f"TX: {result.transaction_hash}")
else:
    print(f"Error: {result.error}")

api.close()
```

### Asynchronous

```python
import asyncio
from FragmentAPI import AsyncFragmentAPI

async def main():
    api = AsyncFragmentAPI(
        cookies="your_cookies",
        hash_value="your_hash",
        wallet_mnemonic="your mnemonic...",
        wallet_api_key="your_api_key"
    )
    
    result = await api.buy_stars('username', 100)
    if result.success:
        print(f"TX: {result.transaction_hash}")
    
    await api.close()

asyncio.run(main())
```

## Methods

### buy_stars(username, quantity)
Send Telegram Stars to user
- `username` (str): Target username
- `quantity` (int): Number of stars (1-999999)

### gift_premium(username, months)
Gift Premium subscription (3, 6, or 12 months)
- `username` (str): Target username
- `months` (int): Duration in months

### topup_ton(username, amount)
Top up Telegram Ads account with TON
- `username` (str): Target username
- `amount` (int): Amount of TON (1-999999)

### get_wallet_balance()
Get current wallet balance and address

## Setup

### 1. Get Fragment Cookies

1. Open fragment.com in browser
2. Press F12 → Application → Cookies
3. Copy cookies: `stel_ssid`, `stel_token`, `stel_dt`, `stel_ton_token`
4. Combine: `stel_ssid=value; stel_token=value; ...`

### 2. Get Hash Value

From DevTools Network tab → fragment.com/api requests → copy `hash` parameter

### 3. Setup TON Wallet

1. Get 24-word seed phrase from TON wallet (Tonkeeper, MyTonWallet, etc)
2. Fund wallet with TON for transactions

### 4. Get API Key

1. Go to https://tonconsole.com
2. Create project
3. Generate API key from Settings

## Exceptions

- `AuthenticationError` - Invalid cookies/hash
- `UserNotFoundError` - User doesn't exist
- `InvalidAmountError` - Invalid quantity/amount
- `InsufficientBalanceError` - Low wallet balance
- `TransactionError` - TX execution failed
- `NetworkError` - Network request failed
- `WalletError` - Wallet operation failed
- `PaymentInitiationError` - Fragment API error

## Error Handling

```python
from FragmentAPI import InsufficientBalanceError, UserNotFoundError

try:
    result = api.buy_stars('username', 100)
    if not result.success:
        print(f"Error: {result.error}")
except InsufficientBalanceError as e:
    print(f"Low balance: {e}")
except UserNotFoundError as e:
    print(f"User not found: {e}")
finally:
    api.close()
```

## Security

Store credentials in environment variables:

```python
import os

api = SyncFragmentAPI(
    cookies=os.getenv('FRAGMENT_COOKIES'),
    hash_value=os.getenv('FRAGMENT_HASH'),
    wallet_mnemonic=os.getenv('WALLET_MNEMONIC'),
    wallet_api_key=os.getenv('WALLET_API_KEY')
)
```

## Requirements

- Python 3.7+
- requests >= 2.28.0
- aiohttp >= 3.8.0
- tonutils >= 0.3.0
- pytoniq-core >= 0.1.0

## Documentation

Full documentation: https://github.com/S1qwy/fragment-api-py

## License

MIT License

## Support

- GitHub: https://github.com/S1qwy/fragment-api-py
- Issues: https://github.com/S1qwy/fragment-api-py/issues
