fragment-api-nk 1.0.0

Async No-KYC Fragment.com client. Buys Stars / Premium / Ads top-up via a remote backend without KYC.

Fragment API Python SDK — No KYC Edition

Lightweight Python library for Fragment.com automation
No KYC required — Send Stars, Premium, and TON Ads directly from your wallet

---

🚀 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

pip install fragment-api-nk

🧪 Requirements

• Python 3.10+
• Fragment API token (get from Fragment.com after login)
• TON wallet seed phrase (12/18/24 words)

---

🎯 Quick Start

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

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

@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

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
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:

pip install fragment-api-py

---

💖 Support the Project

UQBsyxZvyQxDwAeOxoaWwO2HJoAmCKUoJlS_OpLzWHD9i2Xj

---

📄 License

MIT License — free for commercial and personal use.

---

GitHub (nokyc branch) • PyPI