Metadata-Version: 2.4
Name: fragment-api-nk
Version: 1.0.0
Summary: Async No-KYC Fragment.com client. Buys Stars / Premium / Ads top-up via a remote backend without KYC.
Home-page: https://github.com/S1qwy/fragment-api-py/tree/nokyc
Author: S1qwy
Author-email: S1qwy@internet.ru
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: AsyncIO
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: tonutils>=0.5.0
Requires-Dist: ton-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

<p align="center">
  <img src="https://fragment.com/img/fragment_icon.svg" width="200" alt="Fragment API Python">
</p>

<h1 align="center">Fragment API Python SDK — No KYC Edition</h1>

<p align="center">
  <strong>Lightweight Python library for Fragment.com automation</strong><br>
  <strong>No KYC required — Send Stars, Premium, and TON Ads directly from your wallet</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/fragment-api-nk/"><img src="https://img.shields.io/pypi/v/fragment-api-nk.svg?style=flat-square" alt="PyPI"></a>
  <a href="https://pypi.org/project/fragment-api-nk/"><img src="https://img.shields.io/pypi/pyversions/fragment-api-nk.svg?style=flat-square" alt="Python Versions"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" alt="License"></a>
</p>

<p align="center">
  <a href="https://github.com/S1qwy/fragment-api-py/tree/nokyc"><img src="https://img.shields.io/badge/GitHub-nokyc-181717?style=flat-square&logo=github" alt="GitHub"></a>
</p>

---

## 🚀 What is This?

This is the **No KYC** edition of the Fragment API Python library. 

**Key differences from the full KYC version:**

| Feature | No KYC Edition | Full KYC Edition |
|---------|:-------------:|:----------------:|
| KYC Required | ❌ No | ✅ Yes |
| Purchase Stars | ✅ Yes | ✅ Yes |
| Purchase Premium | ✅ Yes | ✅ Yes |
| TON Ads Top-up | ✅ Yes | ✅ Yes |
| Giveaways (Stars/Premium) | ✅ Yes | ✅ Yes |
| Marketplace Search | ❌ No | ✅ Yes |
| Place Bids | ❌ No | ✅ Yes |
| Full Wallet Info | ❌ No | ✅ Yes |
| NFT/Gift Management | ❌ No | ✅ Yes |

---

## ✨ Features

- **No KYC Required** — start using immediately
- **Async-only** — full async/await support
- **Direct TON Payments** — send from your wallet (V4R2/V5R1)
- **Purchases** — Stars (50–10M), Premium (3/6/12 months), TON Ads
- **Giveaways** — Stars and Premium for Telegram channels (up to 24k winners)
- **TON Payment Gateway** — automatic invoice generation and payment
- **Status Tracking** — monitor operation status
- **Complete Error Hierarchy** — proper exception handling

---

## 📦 Installation

```bash
pip install fragment-api-nk
```

## 🧪 Requirements

- Python 3.10+
- Fragment API token (get from [Fragment.com](https://fragment.com) after login)
- TON wallet seed phrase (12/18/24 words)

---

## 🎯 Quick Start

```python
import asyncio
from FragmentNK import FragmentNK

async def main():
    async with FragmentNK(
        seed="your 12/18/24 word seed phrase...",
        api_token="your_fragment_api_token",
        wallet_version="V5R1",  # or "V4R2"
    ) as client:
        
        # Get wallet info
        address = await client.get_wallet_address()
        balance = await client.get_wallet_balance()
        print(f"Wallet: {address}")
        print(f"Balance: {balance} TON")
        
        # Check recipient before sending
        recipient = await client.get_stars_recipient("@durov")
        if recipient:
            print(f"Sending to: {recipient.name}")
        
        # Purchase Stars
        result = await client.purchase_stars("@durov", 100)
        print(f"Sent 100 Stars! TX: {result.transaction_id}")
        
        # Purchase Telegram Premium (3, 6, or 12 months)
        premium = await client.purchase_premium("@durov", 6)
        print(f"Sent 6 months Premium! TX: {premium.transaction_id}")
        
        # Top-up TON Ads balance
        topup = await client.topup_ton("@durov", 10)
        print(f"Topped up 10 TON! TX: {topup.transaction_id}")
        
        # Stars Giveaway for channel
        giveaway = await client.giveaway_stars("@channel", winners=10, amount=500)
        print(f"Giveaway created! TX: {giveaway.transaction_id}")
        
        # Premium Giveaway
        giveaway_prem = await client.giveaway_premium("@channel", winners=5, months=3)
        print(f"Premium giveaway created! TX: {giveaway_prem.transaction_id}")

asyncio.run(main())
```

---

## 📖 API Reference

### Initialization

```python
from FragmentNK import FragmentNK

client = FragmentNK(
    seed="24 words...",           # Required: TON wallet mnemonic
    api_token="your_token",       # Required: Fragment API token
    api_key=None,                  # Optional: tonapi.io API key
    wallet_version="V5R1",        # Optional: "V4R2" or "V5R1" (default: "V5R1")
    backend_url="https://fragment-api.tech",  # Optional: custom backend
    timeout=30.0,                  # Optional: request timeout
)
```

### Methods

| Method | Description | Returns |
|--------|-------------|---------|
| `get_wallet_address()` | Get wallet address | `str` |
| `get_wallet_balance()` | Get wallet balance in TON | `float` |
| `get_stars_recipient(username)` | Check Stars recipient info | `RecipientInfo \| None` |
| `get_premium_recipient(username, months)` | Check Premium recipient info | `RecipientInfo \| None` |
| `get_ads_topup_recipient(username)` | Check Ads top-up recipient | `RecipientInfo \| None` |
| `purchase_stars(username, amount, show_sender)` | Send Telegram Stars | `StarsResult` |
| `purchase_premium(username, months, show_sender)` | Send Telegram Premium | `PremiumResult` |
| `topup_ton(username, amount, show_sender)` | Top-up TON Ads balance | `AdsTopupResult` |
| `giveaway_stars(channel, winners, amount)` | Create Stars giveaway | `GiveawayStarsResult` |
| `giveaway_premium(channel, winners, months)` | Create Premium giveaway | `GiveawayPremiumResult` |
| `get_status(req_id)` | Check operation status | `OperationStatus` |

### Types

```python
@dataclass
class RecipientInfo:
    recipient: str      # @username
    name: str           # Display name
    photo_url: str | None
    myself: bool

@dataclass
class StarsResult:
    transaction_id: str
    username: str
    amount: int

@dataclass
class PremiumResult:
    transaction_id: str
    username: str
    amount: int   # months (3, 6, 12)

@dataclass
class OperationStatus:
    status: str           # "completed", "failed", "pending", "timeout"
    req_id: str
    transaction_id: str | None
    error: str | None
```

---

## 🔧 Error Handling

```python
from FragmentNK import (
    FragmentNK,
    KYCRequiredError,
    PaymentError,
    WalletError,
    ConfigError,
    BackendError,
)

try:
    async with FragmentNK(seed="...", api_token="...") as client:
        result = await client.purchase_stars("@username", 100)
except KYCRequiredError as e:
    print(f"This operation requires KYC: {e}")
except PaymentError as e:
    print(f"Payment failed: {e}")
except WalletError as e:
    print(f"Wallet error: {e}")
except ConfigError as e:
    print(f"Configuration error: {e}")
except BackendError as e:
    print(f"Backend error (status {e.status_code}): {e}")
```

---

## 💳 Purchase Limits

| Purchase Type | Limits |
|---------------|--------|
| **Stars** | 50 – 10,000,000 |
| **Premium** | 3, 6, or 12 months |
| **TON Ads** | 1 – 1,000,000,000 TON |
| **Giveaway Stars** | 1 – 24,000 winners |
| **Giveaway Premium** | 1 – 24,000 winners |

---

## 🔐 Getting an API Token

1. Log in to [fragment-api.tech](https://fragment-api.tech)
2. Login in your Telegram Account with OAuth2
3. The token will be automatically generated and displayed to you."
4. Copy the token and keep it secure

---

## ⚠️ Important Notes

- **No KYC required** — use immediately
- **Marketplace features** (search, bids) require KYC — use the full version
- **TON balance** must cover amount + ~0.05 TON for fees
- **Supported wallets**: V4R2 and V5R1 (W5)

---

## 🆚 Full Version vs No KYC Version

| | **No KYC (this)** | **Full KYC** |
|-|:-----------------:|:------------:|
| Stars/Premium/Ads | ✅ | ✅ |
| Giveaways | ✅ | ✅ |
| Marketplace Search | ❌ | ✅ |
| Place Bids | ❌ | ✅ |
| NFT Management | ❌ | ✅ |
| EVM Payments | ❌ | ✅ |
| KYC Required | ❌ | ✅ |

For full features with KYC, install:
```bash
pip install fragment-api-py
```

---

## 💖 Support the Project

<p align="center">
  <a href="https://app.tonkeeper.com/transfer/UQBsyxZvyQxDwAeOxoaWwO2HJoAmCKUoJlS_OpLzWHD9i2Xj">
    <img src="https://img.shields.io/badge/Donate-TON-0098ea?style=for-the-badge&logo=ton&logoColor=white" alt="Donate TON">
  </a>
</p>

<p align="center">
  <code>UQBsyxZvyQxDwAeOxoaWwO2HJoAmCKUoJlS_OpLzWHD9i2Xj</code>
</p>

---

## 📄 License

**MIT License** — free for commercial and personal use.

---

<p align="center">
  <a href="https://github.com/S1qwy/fragment-api-py/tree/nokyc">GitHub (nokyc branch)</a> •
  <a href="https://pypi.org/project/fragment-api-nk/">PyPI</a>
</p>
