feat: add payment method options for purchases and giveaways, enhance documentation and examples

examples/purchase/run_premium_giveaway.py

@@ -3,6 +3,8 @@ Example: run a Telegram Premium giveaway for a channel.
 
 winners must be an integer between 1 and 24 000.
 months (Premium duration per winner) must be 3, 6, or 12.
+payment_method can be "ton" or "usdt_ton".
+Channel can be "@channel", "channel", or "https://t.me/channel".
 """
 
 import asyncio
@@ -24,15 +26,21 @@ COOKIES = {
     "stel_ton_token": "YOUR_STEL_TON_TOKEN",
 }
 
-CHANNEL = "@channel"
+CHANNEL = "https://t.me/channel"
 WINNERS = 10  # 1–24 000
 MONTHS = 3  # 3, 6 or 12
+PAYMENT_METHOD = "ton"  # "ton" or "usdt_ton"
 
 
 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,
+                payment_method=PAYMENT_METHOD,
+            )
         except UserNotFoundError:
             print(f"Channel {CHANNEL} was not found on fragment.com — check the username and try again.")
             return

examples/purchase/run_stars_giveaway.py

@@ -3,6 +3,8 @@ Example: run a Telegram Stars giveaway for a channel.
 
 winners must be an integer between 1 and 5.
 amount (stars per winner) must be an integer between 500 and 1 000 000.
+payment_method can be "ton" or "usdt_ton".
+Channel can be "@channel", "channel", or "https://t.me/channel".
 """
 
 import asyncio
@@ -24,15 +26,21 @@ COOKIES = {
     "stel_ton_token": "YOUR_STEL_TON_TOKEN",
 }
 
-CHANNEL = "@channel"
+CHANNEL = "https://t.me/channel"
 WINNERS = 3  # 1–5
 AMOUNT = 1000  # 500–1 000 000 stars per winner
+PAYMENT_METHOD = "usdt_ton"  # "ton" or "usdt_ton"
 
 
 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,
+                payment_method=PAYMENT_METHOD,
+            )
         except UserNotFoundError:
             print(f"Channel {CHANNEL} was not found on fragment.com — check the username and try again.")
             return

examples/purchase/send_premium.py

@@ -3,6 +3,8 @@ Example: purchase Telegram Premium for a user.
 
 Supported durations: 3, 6, or 12 months.
 Set show_sender=False to send anonymously.
+payment_method can be "ton" or "usdt_ton".
+Username can be "@username", "username", or "https://t.me/username".
 """
 
 import asyncio
@@ -24,14 +26,20 @@ COOKIES = {
     "stel_ton_token": "YOUR_STEL_TON_TOKEN",
 }
 
-USERNAME = "@username"
+USERNAME = "https://t.me/username"
 MONTHS = 3  # 3, 6 or 12
+PAYMENT_METHOD = "ton"  # "ton" or "usdt_ton"
 
 
 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,
+                payment_method=PAYMENT_METHOD,
+            )
         except UserNotFoundError:
             print(f"User {USERNAME} was not found on fragment.com — check the username and try again.")
             return

examples/purchase/send_stars.py

@@ -3,6 +3,8 @@ Example: purchase Telegram Stars for a user.
 
 Amount must be an integer between 50 and 1 000 000.
 Set show_sender=False to send anonymously.
+payment_method can be "ton" or "usdt_ton".
+Username can be "@username", "username", or "https://t.me/username".
 """
 
 import asyncio
@@ -24,14 +26,20 @@ COOKIES = {
     "stel_ton_token": "YOUR_STEL_TON_TOKEN",
 }
 
-USERNAME = "@username"
+USERNAME = "https://t.me/username"
 AMOUNT = 500  # 50–1 000 000 stars
+PAYMENT_METHOD = "usdt_ton"  # "ton" or "usdt_ton"
 
 
 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,
+                payment_method=PAYMENT_METHOD,
+            )
         except UserNotFoundError:
             print(f"User {USERNAME} was not found on fragment.com — check the username and try again.")
             return