Metadata-Version: 2.4
Name: fragment-api-py
Version: 3.1.0
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)
- ✅ Direct TON transfers to any address
- ✅ Recipient lookup (get user info & avatar)
- ✅ 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"
)

# Get recipient info with avatar
recipient = api.get_recipient_stars('username')
print(f"Name: {recipient.name}")
print(f"Avatar: {recipient.avatar}")

# Send stars
result = api.buy_stars('username', 100)
if result.success:
    print(f"TX: {result.transaction_hash}")

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"
    )
    
    # Get recipient info with avatar
    recipient = await api.get_recipient_stars('username')
    print(f"Name: {recipient.name}")
    print(f"Avatar: {recipient.avatar}")
    
    # Send stars
    result = await api.buy_stars('username', 100)
    if result.success:
        print(f"TX: {result.transaction_hash}")
    
    await api.close()

asyncio.run(main())
```

## Methods

### Recipient Lookup

#### get_recipient_stars(username)
Get recipient info for Stars transfer
- Returns: `UserInfo` with name, recipient address, avatar (URL or base64)

#### get_recipient_premium(username)
Get recipient info for Premium gift
- Returns: `UserInfo` with name, recipient address, avatar

#### get_recipient_ton(username)
Get recipient info for Ads account top-up
- Returns: `UserInfo` with name, recipient address, avatar

### Payments

#### 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)

#### transfer_ton(to_address, amount, memo=None)
Direct TON transfer to any address or username
- `to_address` (str): Destination address (TON address or username like `user.t.me`)
- `amount` (float): Amount of TON to send
- `memo` (str, optional): Comment/memo for the transaction
- Returns: `TransferResult` with success status, transaction_hash, memo, and error (if any)

### Wallet

#### get_wallet_balance()
Get current wallet balance and address
- Returns: Dictionary with balance in TON/nanotons and address

## Recipient Info

```python
# Get user info before sending payment
user = api.get_recipient_stars('john_doe')

if user.found:
    print(f"Name: {user.name}")
    print(f"Address: {user.recipient}")
    print(f"Avatar: {user.avatar}")  # URL or base64 encoded image
```

**UserInfo object:**
- `name` - User's display name
- `recipient` - Blockchain address
- `found` - Boolean flag
- `avatar` - Avatar URL (HTTP/HTTPS) or base64 encoded image

## Direct TON Transfer

Send TON directly to any address or Telegram username:

### 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"
    )
    
    # Check balance first
    balance = await api.get_wallet_balance()
    print(f"Balance: {balance['balance_ton']} TON")
    print(f"Address: {balance['address']}")
    
    # Transfer to username (t.me format)
    result = await api.transfer_ton("username.t.me", 0.5, "Payment for services")
    
    # Or transfer to TON address
    # result = await api.transfer_ton("EQDrjaLahLkMB-hMCmkzOyBuHJ139ZUYmPHu6RRBKnbRELWt", 0.5)
    
    if result.success:
        print(f"Success! Hash: {result.transaction_hash}")
        print(f"Memo: {result.memo}")
    else:
        print(f"Error: {result.error}")
    
    await api.close()

asyncio.run(main())
```

### 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"
)

# Check balance
balance = api.get_wallet_balance()
print(f"Balance: {balance['balance_ton']} TON")
print(f"Address: {balance['address']}")

# Transfer with memo
result = api.transfer_ton("username.t.me", 0.01, "test payment")

if result.success:
    print(f"Success! Hash: {result.transaction_hash}")
    print(f"Memo: {result.memo}")
else:
    print(f"Error: {result.error}")

api.close()
```

### TransferResult Object

The `transfer_ton` method returns a `TransferResult` object:

| Attribute | Type | Description |
|-----------|------|-------------|
| `success` | bool | Whether the transfer was successful |
| `transaction_hash` | str \| None | Transaction hash on success |
| `memo` | str \| None | The memo/comment included in transaction |
| `error` | str \| None | Error message if transfer failed |

## 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, WalletError

try:
    # Get recipient info
    user = api.get_recipient_stars('username')
    
    # Send payment
    result = api.buy_stars('username', 100)
    if not result.success:
        print(f"Error: {result.error}")
        
    # Direct transfer
    transfer = api.transfer_ton('address.t.me', 1.0, 'memo')
    if not transfer.success:
        print(f"Transfer error: {transfer.error}")
        
except InsufficientBalanceError as e:
    print(f"Low balance: {e}")
except UserNotFoundError as e:
    print(f"User not found: {e}")
except WalletError as e:
    print(f"Wallet error: {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
