- Async Python client for the Fragment.com API — buy Telegram Stars and Premium, run giveaways, top up TON, Ads balance, manage anonymous numbers, and search the marketplace for usernames, numbers, and gifts. + Async Python client for the Fragment API — a unified toolkit to manage Telegram assets: purchase Stars and Premium, top up TON and Ads balances, run giveaways, manage anonymous numbers, and explore the marketplace for usernames, numbers, and gifts.
[](https://pypi.org/project/pyfragment/) diff --git a/examples/auctions/search_gifts.py b/examples/auctions/search_gifts.py index ec68a03..70ad338 100644 --- a/examples/auctions/search_gifts.py +++ b/examples/auctions/search_gifts.py @@ -8,6 +8,7 @@ Use next_offset for pagination. """ import asyncio +import json from pyfragment import FragmentClient, GiftsResult @@ -28,16 +29,10 @@ FILTER = "" # "", "auction", "sale", "sold" — or omit async def main() -> None: async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client: - result: GiftsResult = await client.search_gifts( - QUERY, collection=COLLECTION, sort=SORT, filter=FILTER - ) + result: GiftsResult = await client.search_gifts(QUERY, collection=COLLECTION, sort=SORT, filter=FILTER) print(f"Found {len(result.items)} result(s):") - for item in result.items: - price = f"{item['price']} TON" if item["price"] else "n/a" - print( - f" {item['name']:30s} {item['status'] or '':15s} {price:12s} {item['date'] or '—'}" - ) + print(json.dumps(result.items, indent=2)) if result.next_offset: print(f"\nMore results available — next page offset: {result.next_offset}") diff --git a/examples/auctions/search_numbers.py b/examples/auctions/search_numbers.py index 37e80fb..9a98a27 100644 --- a/examples/auctions/search_numbers.py +++ b/examples/auctions/search_numbers.py @@ -7,6 +7,7 @@ Use next_offset_id for pagination. """ import asyncio +import json from pyfragment import FragmentClient, NumbersResult @@ -26,21 +27,13 @@ FILTER = "" # "", "auction", "sale", "sold" — or omit async def main() -> None: async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client: - result: NumbersResult = await client.search_numbers( - QUERY, sort=SORT, filter=FILTER - ) + result: NumbersResult = await client.search_numbers(QUERY, sort=SORT, filter=FILTER) print(f"Found {len(result.items)} result(s):") - for item in result.items: - price = f"{item['price']} TON" if item["price"] else "n/a" - print( - f" {item['name']:20s} {item['status'] or '':15s} {price:10s} {item['date'] or '—'}" - ) + print(json.dumps(result.items, indent=2)) if result.next_offset_id: - print( - f"\nMore results available — next page offset: {result.next_offset_id}" - ) + print(f"\nMore results available — next page offset: {result.next_offset_id}") if __name__ == "__main__": diff --git a/examples/auctions/search_usernames.py b/examples/auctions/search_usernames.py index c71b6fe..68e5ea1 100644 --- a/examples/auctions/search_usernames.py +++ b/examples/auctions/search_usernames.py @@ -7,6 +7,7 @@ Use next_offset_id for pagination. """ import asyncio +import json from pyfragment import FragmentClient, UsernamesResult @@ -26,21 +27,13 @@ FILTER = "auction" # "", "auction", "sale", "sold" — or omit async def main() -> None: async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client: - result: UsernamesResult = await client.search_usernames( - QUERY, sort=SORT, filter=FILTER - ) + result: UsernamesResult = await client.search_usernames(QUERY, sort=SORT, filter=FILTER) print(f"Found {len(result.items)} result(s):") - for item in result.items: - price = f"{item['price']} TON" if item["price"] else "n/a" - print( - f" {item['name']:20s} {item['status'] or '':15s} {price:10s} {item['date'] or '—'}" - ) + print(json.dumps(result.items, indent=2)) if result.next_offset_id: - print( - f"\nMore results available — next page offset: {result.next_offset_id}" - ) + print(f"\nMore results available — next page offset: {result.next_offset_id}") if __name__ == "__main__": diff --git a/examples/numbers/manage_number.py b/examples/numbers/manage_number.py index e9f60a4..3355b22 100644 --- a/examples/numbers/manage_number.py +++ b/examples/numbers/manage_number.py @@ -27,21 +27,14 @@ async def main() -> None: # Fetch the latest login code result = await client.get_login_code(NUMBER) if result.code: - print( - f"Login code for {result.number}: {result.code} ({result.active_sessions} active session(s))" - ) + print(f"Login code for {result.number}: {result.code} ({result.active_sessions} active session(s))") else: - print( - f"No pending login code for {result.number} ({result.active_sessions} active session(s))" - ) + print(f"No pending login code for {result.number} ({result.active_sessions} active session(s))") # Terminate all active sessions try: terminated = await client.terminate_sessions(NUMBER) - print( - f"Sessions terminated for {terminated.number}" - + (f": {terminated.message}" if terminated.message else "") - ) + print(f"Sessions terminated for {terminated.number}" + (f": {terminated.message}" if terminated.message else "")) except AnonymousNumberError as e: print(f"Could not terminate sessions: {e}") diff --git a/examples/purchase/recharge_ads_balance.py b/examples/purchase/recharge_ads_balance.py index 3b02de2..6ec6121 100644 --- a/examples/purchase/recharge_ads_balance.py +++ b/examples/purchase/recharge_ads_balance.py @@ -30,9 +30,7 @@ AMOUNT = 10 # 1–1 000 000 000 TON async def main() -> None: async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client: try: - result: AdsRechargeResult = await client.recharge_ads( - ACCOUNT, amount=AMOUNT - ) + result: AdsRechargeResult = await client.recharge_ads(ACCOUNT, amount=AMOUNT) except WalletError as e: print(f"Wallet error — insufficient balance or misconfiguration: {e}") return @@ -40,9 +38,7 @@ async def main() -> None: print(f"Invalid argument: {e}") return - print( - f"{result.amount} TON recharged to Ads account {ACCOUNT} | tx: {result.transaction_id}" - ) + print(f"{result.amount} TON recharged to Ads account {ACCOUNT} | tx: {result.transaction_id}") if __name__ == "__main__": diff --git a/examples/purchase/run_premium_giveaway.py b/examples/purchase/run_premium_giveaway.py index 3a88f26..e2a5818 100644 --- a/examples/purchase/run_premium_giveaway.py +++ b/examples/purchase/run_premium_giveaway.py @@ -26,13 +26,9 @@ MONTHS = 3 # 3, 6 or 12 async def main() -> None: async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client: try: - result = await client.giveaway_premium( - CHANNEL, winners=WINNERS, months=MONTHS - ) + result = await client.giveaway_premium(CHANNEL, winners=WINNERS, months=MONTHS) except UserNotFoundError: - print( - f"Channel {CHANNEL} was not found on fragment.com — check the username and try again." - ) + print(f"Channel {CHANNEL} was not found on fragment.com — check the username and try again.") return except ConfigurationError as e: print(f"Invalid argument: {e}") diff --git a/examples/purchase/run_stars_giveaway.py b/examples/purchase/run_stars_giveaway.py index 19627d3..400a707 100644 --- a/examples/purchase/run_stars_giveaway.py +++ b/examples/purchase/run_stars_giveaway.py @@ -26,13 +26,9 @@ AMOUNT = 1000 # 500–1 000 000 stars per winner async def main() -> None: async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client: try: - result = await client.giveaway_stars( - CHANNEL, winners=WINNERS, amount=AMOUNT - ) + result = await client.giveaway_stars(CHANNEL, winners=WINNERS, amount=AMOUNT) except UserNotFoundError: - print( - f"Channel {CHANNEL} was not found on fragment.com — check the username and try again." - ) + print(f"Channel {CHANNEL} was not found on fragment.com — check the username and try again.") return except ConfigurationError as e: print(f"Invalid argument: {e}") diff --git a/examples/purchase/send_premium.py b/examples/purchase/send_premium.py index a2d571e..fc90f3b 100644 --- a/examples/purchase/send_premium.py +++ b/examples/purchase/send_premium.py @@ -25,21 +25,15 @@ MONTHS = 3 # 3, 6 or 12 async def main() -> None: async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client: try: - result = await client.purchase_premium( - USERNAME, months=MONTHS, show_sender=True - ) + result = await client.purchase_premium(USERNAME, months=MONTHS, show_sender=True) except UserNotFoundError: - print( - f"User {USERNAME} was not found on fragment.com — check the username and try again." - ) + print(f"User {USERNAME} was not found on fragment.com — check the username and try again.") return except ConfigurationError as e: print(f"Invalid argument: {e}") return - print( - f"{result.amount} months of Premium successfully sent to {result.username} | tx: {result.transaction_id}" - ) + print(f"{result.amount} months of Premium successfully sent to {result.username} | tx: {result.transaction_id}") if __name__ == "__main__": diff --git a/examples/purchase/send_stars.py b/examples/purchase/send_stars.py index 5106732..594f883 100644 --- a/examples/purchase/send_stars.py +++ b/examples/purchase/send_stars.py @@ -25,21 +25,15 @@ AMOUNT = 500 # 50–1 000 000 stars async def main() -> None: async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client: try: - result = await client.purchase_stars( - USERNAME, amount=AMOUNT, show_sender=True - ) + result = await client.purchase_stars(USERNAME, amount=AMOUNT, show_sender=True) except UserNotFoundError: - print( - f"User {USERNAME} was not found on fragment.com — check the username and try again." - ) + print(f"User {USERNAME} was not found on fragment.com — check the username and try again.") return except ConfigurationError as e: print(f"Invalid argument: {e}") return - print( - f"{result.amount} Stars successfully sent to {result.username} | tx: {result.transaction_id}" - ) + print(f"{result.amount} Stars successfully sent to {result.username} | tx: {result.transaction_id}") if __name__ == "__main__": diff --git a/examples/purchase/topup_ton_balance.py b/examples/purchase/topup_ton_balance.py index 12ce171..10681ad 100644 --- a/examples/purchase/topup_ton_balance.py +++ b/examples/purchase/topup_ton_balance.py @@ -34,9 +34,7 @@ async def main() -> None: try: result = await client.topup_ton(USERNAME, amount=AMOUNT, show_sender=True) except UserNotFoundError: - print( - f"User {USERNAME} was not found on fragment.com — check the username and try again." - ) + print(f"User {USERNAME} was not found on fragment.com — check the username and try again.") return except WalletError as e: print(f"Wallet error — insufficient balance or misconfiguration: {e}") @@ -45,9 +43,7 @@ async def main() -> None: print(f"Invalid argument: {e}") return - print( - f"{result.amount} TON successfully topped up for {result.username} | tx: {result.transaction_id}" - ) + print(f"{result.amount} TON successfully topped up for {result.username} | tx: {result.transaction_id}") if __name__ == "__main__": diff --git a/pyproject.toml b/pyproject.toml index 47c9cbb..d015d8b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "pyfragment" version = "2026.0.2" -description = "Async Python client for the Fragment.com API — buy Telegram Stars and Premium, run giveaways, top up TON Ads balance, and manage anonymous numbers." +description = "Async Python client for the Fragment API — a unified toolkit to manage Telegram assets: purchase Stars and Premium, top up TON and Ads balances, run giveaways, manage anonymous numbers, and explore the marketplace for usernames, numbers, and gifts." readme = "README.md" license = { text = "MIT" } requires-python = ">=3.12"