adsun — Telegram bot ads for Python

Official Adsun 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+.

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

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

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)

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

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

MIT License. Adsun is not affiliated with Telegram.