Metadata-Version: 2.5
Name: adsun
Version: 1.0.0
Summary: Official Adsun Python SDK: monetize Telegram bots with sponsored ads (aiogram, python-telegram-bot) and verify Telegram Mini App reward callbacks.
Project-URL: Homepage, https://adsun.io
Project-URL: Documentation, https://adsun.io/docs
Project-URL: Source, https://github.com/adsun-io/adsun-sdk
Project-URL: Issues, https://github.com/adsun-io/adsun-sdk/issues
Project-URL: Bot monetization, https://adsun.io/telegram-bot-monetization
Author-email: Adsun <support@adsun.io>
License-Expression: MIT
License-File: LICENSE
Keywords: ad-network,adsgram,adsgram-alternative,adsun,aiogram,bot-monetization,python-telegram-bot,rewarded-ads,telegram,telegram-ad-network,telegram-ads,telegram-bot,telegram-mini-app,telegram-monetization,ton,usdt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Provides-Extra: aiogram
Requires-Dist: aiogram>=3.0; extra == 'aiogram'
Requires-Dist: aiohttp>=3.8; extra == 'aiogram'
Provides-Extra: async
Requires-Dist: aiohttp>=3.8; extra == 'async'
Provides-Extra: ptb
Requires-Dist: python-telegram-bot>=20.0; extra == 'ptb'
Description-Content-Type: text/markdown

# adsun — Telegram bot ads for Python

Official [Adsun](https://adsun.io) Python SDK. **Monetize your Telegram bot** with sponsored messages and earn **USDT**,
and verify **Telegram Mini App reward callbacks** on your server. Zero required dependencies; helpers for
**aiogram 3** and **python-telegram-bot 20+**.

```bash
pip install adsun              # core (standard library only)
pip install "adsun[aiogram]"   # + aiogram helper
pip install "adsun[ptb]"       # + python-telegram-bot helper
```

1. Sign up at https://adsun.io/publishers, add your bot as a **Bot** platform and create a block.
2. Copy your **account token** (Profile → Token) and the numeric **block id** (e.g. `50001`).

## aiogram 3

```python
from aiogram.filters import Command
from adsun import AsyncAdsunBot
from adsun.integrations.aiogram import send_ad

ads = AsyncAdsunBot(token="YOUR_ACCOUNT_TOKEN", block_id="50001")

@dp.message(Command("bonus"))
async def bonus(message):
    ad = await send_ad(message.bot, message.chat.id, ads, message.from_user.id, message.from_user.language_code or "en")
    if ad is None:
        await message.answer("No offer right now")
```

## python-telegram-bot

```python
from adsun import AsyncAdsunBot
from adsun.integrations.ptb import send_ad

ads = AsyncAdsunBot(token="YOUR_ACCOUNT_TOKEN", block_id="50001")

async def bonus(update, context):
    u = update.effective_user
    await send_ad(context.bot, update.effective_chat.id, ads, u.id, u.language_code or "en")
```

## Any framework (sync, no dependencies)

```python
from adsun import AdsunBot

ads = AdsunBot(token="YOUR_ACCOUNT_TOKEN", block_id="50001")
ad = ads.get_ad(user_id=123456789, language="en")   # None = no ad right now
if ad:
    print(ad.text_html, ad.image_url, ad.buttons())  # [[(text, url)], [(reward_text, reward_url)]]
```

Send it yourself with `parse_mode="HTML"` and `protect_content=True` (ad messages must not be forwardable).

Errors: `InvalidToken` (401), `BlockNotActive` (404), `BadRequest` (400), `AdsunError` (others / network).

## Reward URL callback (Mini Apps and bots)

Set the block's Reward URL in the panel:
`https://your-app.com/adsun/reward?userid=[userId]&block=[blockId]&secret=LONG_RANDOM_SECRET`

```python
from adsun import parse_reward_callback

@app.get("/adsun/reward")            # Flask / FastAPI / Django — any dict-like query works
def reward():
    cb = parse_reward_callback(request.args, secret=REWARD_SECRET)
    if cb is None:
        return "forbidden", 403
    add_coins(cb.user_id)            # make this idempotent: Adsun retries on 5xx / network errors
    return "ok"
```

## HTTP API (what the SDK calls)

`GET https://api.adsun.io/advbot?tgid=<user id>&blockid=<number>&language=<code>&token=<account token>`
→ `200 {text_html, click_url, button_name, image_url, button_reward_name, reward_url}` or `204` (no ad).

Links: https://adsun.io/docs · https://adsun.io/telegram-bot-monetization · support@adsun.io ·
[@ADSunSupport](https://t.me/ADSunSupport)

MIT License. Adsun is not affiliated with Telegram.
