Гайд - Исходники - Бот - KodoStars — реферальный бот Telegram Stars + бот для монетизации OP | End Way — сообщество разработчиков и готовых решений
  • Больше материалов без ожидания и лишних условий
    Доступ к скрытым публикациям на 2 месяца, 3 месяца или навсегда. Ограничения «Команда форума» и «Личный» сохраняются.

    Сравнить варианты доступа →

    🔔 EndWay в Telegram

    Следите за новостями и релизами:
    EndWay | EndSoft

Гайд Исходники Бот KodoStars — реферальный бот Telegram Stars + бот для монетизации OP

KodoDrive

Бот
Автор темы
5 Янв 2025
123
224
Telegram-бот на Python 3.12 / aiogram 3: реферальная экономика на внутренних Stars, ежедневные задания, промокоды, бусты за Telegram Stars (XTR), очередь вывода средств и полноценная админка внутри Telegram. Монетизация трафика — каскад обязательной подписки (ОП): Flyer → SubGram → BotoHub → PiarFlow → TGrass → Trafsly → свои каналы.

Интерфейс — русский. Выплаты пользователям — только 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 .venv
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 у бота ничего дополнительно включать не нужно; для проверки подписок добавьте бота администратором в каналы.

Запуск​

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. Основные группы:

ГруппаКлючи
TelegramBOT_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
ManualMANUAL_ENABLED, MANUAL_OP_CHANNELS (@channel или -100…)
ЛогиLOG_LEVEL, LOG_JSON
Все параметры экономики, лимиты вывода, каналы manual-ОП, контакт поддержки и режим обслуживания можно переопределить в Админка → ⚙️ Настройки. Переопределение хранится в БД, помечается ✏️ и сбрасывается к значению из .env одной кнопкой.

Антитвинк: проверка устройства через 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 дней.
  • Админ может отметить пользователя 🤝 доверенным (семья с одним телефоном): флаг снимается, отложенный бонус выплачивается при следующей активности.
  • Раздел 🕵️ Антифрод → 👯 Твинки показывает кластеры «одно устройство — несколько аккаунтов».
Честное ограничение: отпечаток снимает браузер, и технически подкованный человек может подменить его на каждом аккаунте. Это отсекает массовый сценарий (несколько аккаунтов в одном приложении Telegram, фермы на одном устройстве), а не целевую атаку — поэтому IP и история проверок сохраняются и видны администратору. Эндпоинты: GET / (лендинг), GET /health, GET /verify (Mini App), POST /api/device (лимит 20 запросов в минуту с IP).

Вывод Stars​

Bot API не умеет переводить произвольное количество Stars с баланса бота на баланс пользователя (sendInvoice / refundStarPayment — прием и возврат оплаты боту; sendGift отправляет подарок, а не сумму из заявки). Поэтому очередь такая:

  1. Пользователь создает заявку — сумма резервируется (списывается в холд), администраторы получают карточку с кнопками.
  2. Администратор нажимает Согласовать → пользователь получает уведомление.
  3. Администратор отправляет Stars вручную (подарок Stars с личного аккаунта или согласованного канала).
  4. Администратор нажимает Подтвердить отправку → статус sent, пользователь уведомлен.
  5. Отклонить (с указанием причины) или отмена пользователем — холд возвращается на баланс.
Не подтверждайте отправку, пока Stars реально не ушли.

Платежи и возвраты​

Бусты продаются как цифровые товары за 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.ruPOST /get-sponsors, заголовок AuthPOST /get-user-subscriptions
БотоХабbotohub.me/integrationPOST /get-tasks-extended, заголовок Auth, тело {chat_id, max_op} → tasks[].{url, completed}, completed, skipповтор запроса (спонсоры закреплены на 3 мин)
Поток пиаровpiarflow.com/api-docsPOST /sponsors, Authorization: Bearer → sponsors[].{link, status} (not_counted = выполнено)POST /sponsors/check с показанными links
ТГрассtgrass.space/integrationPOST /offers, заголовок Auth, тело {tg_user_id, is_premium, lang, tg_login} → status ok/not_ok/no_offers, offers[].subscribedповтор запроса; плюс локальный список TGRASS_CHANNELS
Trafslytrafsly.com/api-docsPOST /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 (редактируется из панели)повтор проверки
Старые плейсхолдеры URL из прежнего .env.example (api.flyerservice.io, botohub.me/api/v1, api.tgrass.online/v1) автоматически заменяются на документированные хосты.

Свои каналы: публичные, приватные и платные​

Запись канала — Username, @username|Название или -1001234567890|Join group chat on Telegram | End Way - Форум программирования и сливов различных скриптов. Первое поле — что бот проверяет через getChatMember (бот должен быть администратором канала), ссылка — куда ведет кнопка, название — подпись кнопки. Для приватных и платных каналов ссылка обязательна: t.me/c/<id> открывается только у участников. Платный канал подключается платной пригласительной ссылкой (цена в звездах) — оплативший подписку числится member, срок подписки истёк → left, и ОП снова покажет кнопку.

В панели (📢 Каналы ОП → Добавить) достаточно переслать любой пост из канала: бот определит ID и название, для приватного канала попросит ссылку, а по команде auto / auto 50 сам создаст бесплатную или платную (50 ⭐/мес) пригласительную ссылку (createChatSubscriptionInviteLink, требуется право «Приглашать пользователей»). Тот же формат работает в заданиях типа «Подписка на канал».

Как добавить OP-провайдера​

  1. Создайте app/op/myprovider.py с классом-адаптером:
    • name: str
    • async def check(user: OpContext) -> OpResult
    • async def verify(user: OpContext) -> OpResult (кнопка «Я подписался»)
  2. Если ключа нет — OpResult.skip(...). Если API не работает — OpResult.fail_open_result(...). Если есть невыполненные спонсоры — OpResult.blocked(name, sponsors).
  3. Зарегистрируйте адаптер в default_adapters() и укажите имя в CASCADE / PROVIDER_TITLES (app/op/gate.py) и PROVIDER_NAMES (app/db/seed.py).
  4. Добавьте *_ENABLED и ключи в app/config.py и .env.example; учтите их в provider_configured().
Эффективные настройки (с учетом переопределений из БД) доступны адаптеру через OpContext.settings. Добавьте контрактный тест в tests/test_op_adapters.py с примером ответа из документации провайдера — FakeHttp заменяет post_json в модуле адаптера.

Миграции​

Схема управляется 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.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





Собственно вот ссылка на мой реп:

Личный даю за коммент + симпу на тему
 
  • 20
Реакции: 19 users

Doker007

Нейросеть
13 Мар 2023
331
570
Открыл админку от настроек и функций аж поседел :pepecool- знатно заморочился :utka
 
Последнее редактирование:
  • 1
Реакции: 1 user
Активность:
Пока что здесь никого нет