Telegram-бот на Python 3.12 / aiogram 3: реферальная экономика на внутренних Stars, ежедневные задания, промокоды, бусты за Telegram Stars (XTR), очередь вывода средств и полноценная админка внутри Telegram. Монетизация трафика — каскад обязательной подписки (ОП): Flyer → SubGram → BotoHub → PiarFlow → TGrass → Trafsly → свои каналы.
Интерфейс — русский. Выплаты пользователям — только Telegram Stars. CryptoBot нет.
Автор: KodoDrive
Режим обслуживания, поддержка и лимиты вывода — тоже переключаются из панели.
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
Заполните BOT_TOKEN (BotFather) и ADMIN_IDS (ваши Telegram ID через запятую). Для платежей в Stars у бота ничего дополнительно включать не нужно; для проверки подписок добавьте бота администратором в каналы.
Или через Docker:
docker compose up -d --build
На хост-панелях (RubyHost / Pterodactyl) укажите APP PY FILE=main.py в корне проекта. Не ставьте app/__main__.py — тогда падает import app (ModuleNotFoundError).
Точка входа: применяет миграции, сидирует каталог заданий/бустов, загружает админы и запускает long polling. С плейсхолдер-токеном процесс тоже запускается — Telegram выдаст ошибку авторизации, это ожидаемо.
Все параметры экономики, лимиты вывода, каналы manual-ОП, контакт поддержки и режим обслуживания можно переопределить в Админка → ⚙️ Настройки. Переопределение хранится в БД, помечается ✏️ и сбрасывается к значению из .env одной кнопкой.
Политика (все флаги — в Настройки → Антитвинк, без перезапуска):
Адаптеры реализованы по официальной документации сервисов, контракты закреплены тестами (tests/test_op_adapters.py) на примерах ответов из документации:
Старые плейсхолдеры URL из прежнего .env.example (api.flyerservice.io, botohub.me/api/v1, api.tgrass.online/v1) автоматически заменяются на документированные хосты.
В панели (📢 Каналы ОП → Добавить) достаточно переслать любой пост из канала: бот определит ID и название, для приватного канала попросит ссылку, а по команде auto / auto 50 сам создаст бесплатную или платную (50 ⭐/мес) пригласительную ссылку (createChatSubscriptionInviteLink, требуется право «Приглашать пользователей»). Тот же формат работает в заданиях типа «Подписка на канал».
alembic current
alembic revision --autogenerate -m "describe change"
alembic upgrade head
Новые миграции держите аддитивными (ADD COLUMN / CREATE TABLE), чтобы они применялись на SQLite без пересборки таблиц.
ruff check . # линтер
ruff format . # форматирование
Покрыты: атомарный леджер и сверка, холд/возврат/легаси-путь выводов, идемпотентность платежей и возвраты, ежедневка и серии, задания (включая проверку подписки), рефералы (первый старт, уровни, доля), промокоды, настройки в рантайме, роли админов, аудит, фоновая рассылка (блокировки, RetryAfter, отмена), статистика/лидерборд/экспорт, миграции (fresh == create_all, легаси-штамп), контракты ОП-провайдеров (Flyer sub/tasks, BotoHub, TGrass, PiarFlow, Trafsly — на примерах из документации, включая ошибки и fail-open), middleware и end-to-end сценарии через реальный диспетчер с фейковой Telegram-сессией (tests/fake_telegram.py): старт и ОП-гейт, рефералы, ежедневка, вывод с уведомлениями, админ-панель, настройки и режим обслуживания, платежи с возвратом, промокоды, задания, рассылка, экспорт, управление админами.
alembic.ini # CLI Alembic (бот применяет миграции сам)
Dockerfile, docker-compose.yml
app/
__main__.py # жизненный цикл: миграции → сид → polling → graceful shutdown
config.py # Settings + белый список рантайм-настроек
bot/
factory.py # Bot, Dispatcher, порядок middleware
handlers/ # пользовательские роутеры (start, commands, cabinet, earn, withdraw, promo, payments, system)
admin/ # админ-панель: router, texts, keyboards, states + разделы
middlewares/ # context, throttle, db(+events), runtime(settings/access/maintenance), user, op_gate
notify.py # доменные события → уведомления Telegram
errors.py # глобальный обработчик ошибок
services/ # ledger, users, referrals, daily, tasks, boosts, payments, economy,
# withdrawals, promo, access, audit, app_settings, broadcasts, stats,
# leaderboard, export, antifraud, events
op/ # OpGate + адаптеры, общий aiohttp-клиент
db/ # models, session, seed, migrate
migrations/ # Alembic env + versions
tests/ # pytest (сервисы, middleware, миграции, e2e через диспетчер)
docs/superpowers/specs/ # дизайн-спека v1.0
Собственно вот ссылка на мой реп:
Личный даю за коммент + симпу на тему
Интерфейс — русский. Выплаты пользователям — только Telegram Stars. CryptoBot нет.
Автор: KodoDrive
Что умеет бот
Для пользователя
- /start и deep-link ref_<tg_id>; реферер привязывается только при первом запуске (защита от переатрибуции старых аккаунтов)
- Двухуровневая рефералка: бонус за активацию друга + процент с его заработка; уведомления «пришёл новый друг» и «друг активировался: +N ⭐»
- Кнопка «Поделиться ссылкой» (t.me/share/url) и место в топе рефереров
- Ежедневка с серией, экран-превью «сколько получу сегодня» и таймером до сброса
- Задания: подписка на канал (проверка через getChatMember), приглашения, серии, переход по ссылке; автозачёт по событиям
- Уровни (XP → множитель до ×2) с прогресс-баром, бусты-множители и паки Stars за XTR
- Промокоды с лимитом активаций и сроком действия
- Топ по рефералам и по заработку за 7 дней (ники маскируются)
- История операций с пагинацией, список заявок, отмена своей pending-заявки
- Вывод: быстрые суммы, своя сумма, холд средств, уведомления о каждом изменении статуса
- /menu, /profile, /help, /terms, /paysupport (обязательные для ботов, принимающих Stars)
Для администратора (/admin)
| Раздел | Возможности |
|---|---|
| 📊 Статистика | пользователи всего/сегодня/7д/30д, регистрации по дням, DAU/WAU, баны и блокировки бота, воронка рефералов, экономика по видам начислений, холд, выводы, выручка XTR, баланс Stars бота (getMyStarBalance), сверка балансов с леджером |
| 👥 Пользователи | поиск по ID/Username, карточка (баланс, холд, уровень, рефералы, платежи, выплаты, фрод), ±баланс с причиной, бан/разбан, заметка, сообщение пользователю, леджер, список рефералов, подозрительные рефереры |
| 💸 Выводы | очередь по статусам с пагинацией, карточка с контекстом пользователя, согласовать / отклонить с причиной / подтвердить выплату; карточка новой заявки приходит админам сразу |
| 📣 Рассылка | любой тип контента (copyMessage), опциональная URL-кнопка, аудитория (все / активные 7д / активированные), тест себе, фоновая отправка с rate-limit и обработкой RetryAfter, прогресс-карточка, остановка |
| 📋 Задания / 🚀 Бусты | мастер создания, редактирование полей, вкл/выкл, удаление (мягкое, если были выполнения/продажи) |
| 🎟 Промокоды | создание (код или auto), награда, лимит, срок, вкл/выкл |
| 💳 Платежи | список покупок, карточка, возврат через refundStarPayment с откатом начисления / отключением буста |
| ⚙️ Настройки | экономика и операционные флаги меняются без перезапуска (хранятся в БД, валидируются как .env) |
| 🔒 ОП-провайдеры / 📢 Каналы ОП | тумблеры каскада, список своих каналов с проверкой прав бота |
| 🛡 Админы | владельцы из ADMIN_IDS добавляют/удаляют админов прямо в боте |
| 🧾 Журнал / 🕵️ Антифрод | аудит всех админ-действий, лента фрод-событий |
| 🗂 Данные | экспорт CSV (пользователи, выводы, леджер, платежи), импорт пользователей CSV |
Стек и архитектура
- aiogram 3.x, asyncio, FSM (MemoryStorage)
- SQLAlchemy 2 + aiosqlite (SQLite с WAL по умолчанию) или PostgreSQL (asyncpg)
- Alembic: миграции применяются автоматически при запуске; старая БД, созданная с помощью create_all, штампуется базовой версией и обновляется
- pydantic-settings (.env) + переопределения в таблице app_settings
- structlog (JSON или консоль), контекст update_id/user_id в каждой записи
- Баланс — колонка users.balance, изменяемая одним атомарным действием UPDATE … RETURNING; леджер — полный журнал с balance_after. Гонок при параллельных начислениях нет; есть инструмент сверки.
- Вывод с холдом: сумма списывается при создании заявки, возвращается при отклонении/отмене, confirm_sent только фиксирует факт выплаты.
- Платежи идемпотентны по telegram_payment_charge_id — повторная доставка successful_payment не начисляет дважды.
- Доменные события собираются в сессии и превращаются в уведомления только после commit (пользователь никогда не получит сообщение о неслучившемся).
- Транзакция не пересекает сетевой I/O: перед каждым вызовом Telegram API (request-middleware бота) и перед каскадом ОП текущая сессия коммитится, поэтому единственный писатель SQLite не блокируется на время HTTP-ожиданий. Обновления одного пользователя обрабатываются последовательно (UserLockMiddleware), разных — параллельно.
- Глобальный обработчик ошибок: пользователю — мягкий ответ, владельцам — трейсбек (с антиспамом).
- Throttle-промежуточное ПО, отслеживание блокировки бота (my_chat_member), fail-open для внешних ОП-сервисов.
Установка
python3.12 -m venv .venvsource .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
Заполните BOT_TOKEN (BotFather) и ADMIN_IDS (ваши Telegram ID через запятую). Для платежей в Stars у бота ничего дополнительно включать не нужно; для проверки подписок добавьте бота администратором в каналы.
Запуск
python -m appИли через Docker:
docker compose up -d --build
На хост-панелях (RubyHost / Pterodactyl) укажите APP PY FILE=main.py в корне проекта. Не ставьте app/__main__.py — тогда падает import app (ModuleNotFoundError).
Точка входа: применяет миграции, сидирует каталог заданий/бустов, загружает админы и запускает long polling. С плейсхолдер-токеном процесс тоже запускается — Telegram выдаст ошибку авторизации, это ожидаемо.
Переменные окружения
См. .env.example. Основные группы:| Группа | Ключи |
|---|---|
| Telegram | BOT_TOKEN, ADMIN_IDS, SUPPORT_CONTACT |
| Веб / антитвинк | WEB_PUBLIC_URL, SERVER_PORT, DEVICE_CHECK_ENABLED, DEVICE_CHECK_FOR_WITHDRAW, TWINK_BLOCK_REFERRAL, TWINK_BLOCK_WITHDRAW, TWINK_REQUIRE_IP_MATCH, TWINK_IP_WINDOW_DAYS |
| БД | DATABASE_URL (sqlite+aiosqlite:///./data/kodostars.db или postgresql+asyncpg://…) |
| Экономика | REFERRAL_LEVELS, проценты/бонусы L1/L2, MIN_REFERRAL_ACTIVITY, NOTIFY_REFERRER, ежедневка, SIGNUP_BONUS, CLAIM_COOLDOWN_SECONDS |
| Вывод | WITHDRAW_ENABLED, WITHDRAW_MIN, WITHDRAW_MAX, WITHDRAW_COOLDOWN_HOURS, WITHDRAW_MIN_REFERRALS |
| Операционные | MAINTENANCE_MODE, MAINTENANCE_TEXT, BROADCAST_RATE_PER_SEC, THROTTLE_SECONDS |
| Flyer / SubGram / BotoHub / PiarFlow / TGrass / Trafsly | *_ENABLED, *_API_KEY, *_API_URL, FLYER_TASKS_LIMIT, BOTOHUB_MAX_OP, PIARFLOW_MAX_SPONSORS, TGRASS_OFFERS_LIMIT, TGRASS_CHANNELS, TRAFSLY_MAX_SPONSORS |
| Manual | MANUAL_ENABLED, MANUAL_OP_CHANNELS (@channel или -100…) |
| Логи | LOG_LEVEL, LOG_JSON |
Антитвинк: проверка устройства через Mini App
Мультиаккаунты («твинки») — главный способ накрутки рефералки. Бот поднимает встроенный веб-сервер (aiohttp) на порту SERVER_PORT, доступный по HTTPS-адресу контейнера (WEB_PUBLIC_URL), и показывает пользователю кнопку «🛡 Подтвердить устройство» — это Telegram Mini App. Страница за секунду собирает отпечаток устройства (user agent, экран, GPU/canvas, таймзона, языки, шрифты, платформа и версия Telegram), хэширует его и отправляет на /api/device вместе с initData. Сервер проверяет подпись initData (HMAC на токене бота — подделать чужой user_id невозможно), добавляет IP и связывает отпечаток с аккаунтом.Политика (все флаги — в Настройки → Антитвинк, без перезапуска):
- Пока устройство не подтверждено, реферальный бонус за пользователя не начисляется (ежедневка, задания, промокоды работают); при DEVICE_CHECK_FOR_WITHDRAW недоступен и вывод.
- Второй аккаунт с тем же отпечатком помечается твинком (twink_of = первый аккаунт): бонус рефереру не платится, его заработок не даёт долю рефереру, в карточке заявки на вывод админ видит «👯 Твинк! То же устройство у: …». TWINK_BLOCK_WITHDRAW запрещает вывод.
- TWINK_REQUIRE_IP_MATCH смягчает правило для популярных моделей устройств: твинк — только если совпали и отпечаток, и IP за TWINK_IP_WINDOW_DAYS дней.
- Админ может отметить пользователя 🤝 доверенным (семья с одним телефоном): флаг снимается, отложенный бонус выплачивается при следующей активности.
- Раздел 🕵️ Антифрод → 👯 Твинки показывает кластеры «одно устройство — несколько аккаунтов».
Вывод Stars
Bot API не умеет переводить произвольное количество Stars с баланса бота на баланс пользователя (sendInvoice / refundStarPayment — прием и возврат оплаты боту; sendGift отправляет подарок, а не сумму из заявки). Поэтому очередь такая:- Пользователь создает заявку — сумма резервируется (списывается в холд), администраторы получают карточку с кнопками.
- Администратор нажимает Согласовать → пользователь получает уведомление.
- Администратор отправляет Stars вручную (подарок Stars с личного аккаунта или согласованного канала).
- Администратор нажимает Подтвердить отправку → статус sent, пользователь уведомлен.
- Отклонить (с указанием причины) или отмена пользователем — холд возвращается на баланс.
Платежи и возвраты
Бусты продаются как цифровые товары за XTR (sendInvoice, currency="XTR"). Каждый платёж сохраняется в payments. Администратор может вернуть покупку из карточки платежа: бот вызывает refundStarPayment, списывает начисленные Stars пака (баланс может уйти в минус — это видно в карточке) или мгновенно отключает множитель, пользователь получает уведомление. Команды /paysupport и /terms соответствуют требованиям Telegram к ботам, принимающим Stars.Каскад ОП
Провайдер без ключа не блокирует пользователей (пропуск), ошибка API — fail-open. Порядок фиксированный: Flyer → SubGram → BotoHub → PiarFlow → TGrass → Trafsly → свои каналы. Администратор может отключить любого провайдера в рантайме (таблица provider_states) и управлять списком своих каналов.Адаптеры реализованы по официальной документации сервисов, контракты закреплены тестами (tests/test_op_adapters.py) на примерах ответов из документации:
| Провайдер | Документация | Запрос | Проверка «Я подписался» |
|---|---|---|---|
| Флаер | api.flyerhubs.com | ключ sub: POST /check (skip), Flyer сам присылает сообщение со спонсорами; ключ tasks: POST /get_tasks → result[].links[], статусы incomplete/abort = не выполнено | повтор запроса; тип ключа определяется через POST /get_me |
| Подграмма | subgram.ru | POST /get-sponsors, заголовок Auth | POST /get-user-subscriptions |
| БотоХаб | botohub.me/integration | POST /get-tasks-extended, заголовок Auth, тело {chat_id, max_op} → tasks[].{url, completed}, completed, skip | повтор запроса (спонсоры закреплены на 3 мин) |
| Поток пиаров | piarflow.com/api-docs | POST /sponsors, Authorization: Bearer → sponsors[].{link, status} (not_counted = выполнено) | POST /sponsors/check с показанными links |
| ТГрасс | tgrass.space/integration | POST /offers, заголовок Auth, тело {tg_user_id, is_premium, lang, tg_login} → status ok/not_ok/no_offers, offers[].subscribed | повтор запроса; плюс локальный список TGRASS_CHANNELS |
| Trafsly | trafsly.com/api-docs | POST /api/v1/get-sponsors, заголовок Auth: at_… → status ok/warning, sponsors[].{ads_id, link, title} | POST /api/v1/confirm-subscription по каждому выданному ads_id; Sponsor was not shown / Order not found → повторный запрос списка |
| manual | — | getChatMember по MANUAL_OP_CHANNELS (редактируется из панели) | повтор проверки |
Свои каналы: публичные, приватные и платные
Запись канала — Username, @username|Название или -1001234567890|Join group chat on Telegram | End Way - Форум программирования и сливов различных скриптов. Первое поле — что бот проверяет через getChatMember (бот должен быть администратором канала), ссылка — куда ведет кнопка, название — подпись кнопки. Для приватных и платных каналов ссылка обязательна: t.me/c/<id> открывается только у участников. Платный канал подключается платной пригласительной ссылкой (цена в звездах) — оплативший подписку числится member, срок подписки истёк → left, и ОП снова покажет кнопку.В панели (📢 Каналы ОП → Добавить) достаточно переслать любой пост из канала: бот определит ID и название, для приватного канала попросит ссылку, а по команде auto / auto 50 сам создаст бесплатную или платную (50 ⭐/мес) пригласительную ссылку (createChatSubscriptionInviteLink, требуется право «Приглашать пользователей»). Тот же формат работает в заданиях типа «Подписка на канал».
Как добавить OP-провайдера
- Создайте app/op/myprovider.py с классом-адаптером:
- name: str
- async def check(user: OpContext) -> OpResult
- async def verify(user: OpContext) -> OpResult (кнопка «Я подписался»)
- Если ключа нет — OpResult.skip(...). Если API не работает — OpResult.fail_open_result(...). Если есть невыполненные спонсоры — OpResult.blocked(name, sponsors).
- Зарегистрируйте адаптер в default_adapters() и укажите имя в CASCADE / PROVIDER_TITLES (app/op/gate.py) и PROVIDER_NAMES (app/db/seed.py).
- Добавьте *_ENABLED и ключи в app/config.py и .env.example; учтите их в provider_configured().
Миграции
Схема управляется Alembic (app/migrations). При запуске бот сам приводит базу данных к актуальной ревизии:- пустая БД → создается с нуля;
- БД версии 0.1 (create_all, без alembic_version) → штампуется 0001_baseline и обновляется, баланс бэкапится из леджера;
- в остальных случаях — обычный upgrade head.
alembic current
alembic revision --autogenerate -m "describe change"
alembic upgrade head
Новые миграции держите аддитивными (ADD COLUMN / CREATE TABLE), чтобы они применялись на SQLite без пересборки таблиц.
Тесты и качество
pytest # 124 тестаruff check . # линтер
ruff format . # форматирование
Покрыты: атомарный леджер и сверка, холд/возврат/легаси-путь выводов, идемпотентность платежей и возвраты, ежедневка и серии, задания (включая проверку подписки), рефералы (первый старт, уровни, доля), промокоды, настройки в рантайме, роли админов, аудит, фоновая рассылка (блокировки, RetryAfter, отмена), статистика/лидерборд/экспорт, миграции (fresh == create_all, легаси-штамп), контракты ОП-провайдеров (Flyer sub/tasks, BotoHub, TGrass, PiarFlow, Trafsly — на примерах из документации, включая ошибки и fail-open), middleware и end-to-end сценарии через реальный диспетчер с фейковой Telegram-сессией (tests/fake_telegram.py): старт и ОП-гейт, рефералы, ежедневка, вывод с уведомлениями, админ-панель, настройки и режим обслуживания, платежи с возвратом, промокоды, задания, рассылка, экспорт, управление админами.
Структура
main.py # RubyHost / Pterodactyl: APP PY FILE=main.pyalembic.ini # CLI Alembic (бот применяет миграции сам)
Dockerfile, docker-compose.yml
app/
__main__.py # жизненный цикл: миграции → сид → polling → graceful shutdown
config.py # Settings + белый список рантайм-настроек
bot/
factory.py # Bot, Dispatcher, порядок middleware
handlers/ # пользовательские роутеры (start, commands, cabinet, earn, withdraw, promo, payments, system)
admin/ # админ-панель: router, texts, keyboards, states + разделы
middlewares/ # context, throttle, db(+events), runtime(settings/access/maintenance), user, op_gate
notify.py # доменные события → уведомления Telegram
errors.py # глобальный обработчик ошибок
services/ # ledger, users, referrals, daily, tasks, boosts, payments, economy,
# withdrawals, promo, access, audit, app_settings, broadcasts, stats,
# leaderboard, export, antifraud, events
op/ # OpGate + адаптеры, общий aiohttp-клиент
db/ # models, session, seed, migrate
migrations/ # Alembic env + versions
tests/ # pytest (сервисы, middleware, миграции, e2e через диспетчер)
docs/superpowers/specs/ # дизайн-спека v1.0
Собственно вот ссылка на мой реп:
Для просмотра скрытого содержимого вы должны войти или зарегистрироваться.
Личный даю за коммент + симпу на тему
- знатно заморочился 