SushBotSeller

Telegram bot that automates VPN service sales. Handles the entire flow: product catalog, payments, panel provisioning, usage tracking.

cp .env.template .env && $EDITOR .env
docker compose up -d

That's it. Bot is running.

Architecture
Quick Start
Configuration
Features
Panel Integrations
Payments
Database
Development
Security
Troubleshooting

Architecture

Stack:
  Bot Framework    python-telegram-bot 21.x (async)
  API              FastAPI + Uvicorn
  ORM              SQLAlchemy 2.0 (async, asyncpg)
  Database         PostgreSQL 15+
  Build            Hatchling
  Migrations       Alembic

Layout:
  bot/             Entry point, keyboards
  handlers/        Commands, callbacks, message handlers
  api/             REST API (admin panel, webhooks)
  database/        Models, migrations
  services/        Business logic
  integrations/    VPN panel clients (Marzban, PasarGuard)
  config/          Settings, feature flags
  utils/           Helpers (encryption, i18n, QR)

Quick Start

Docker (recommended)

git clone <repo> && cd sushbotseller
cp .env.template .env
# Edit: BOT_TOKEN, DATABASE_URL, SUPER_ADMIN_TELEGRAM_ID (minimum)
docker compose up -d
docker compose logs -f sushbotseller

Manual

python3.12 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.template .env && $EDITOR .env
alembic upgrade head
python -m bot.main

If SUPER_ADMIN_TELEGRAM_ID is set to 0, the first user to /start becomes super admin. Use this for fresh deployments only.

Configuration

Required

BOT_TOKEN=123456:ABCxyz
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/sushbotseller
SUPER_ADMIN_TELEGRAM_ID=123456789

Payments

At least one payment method must be configured:

# Card-to-card (manual approval by admin)
CARD_TO_CARD_NUMBER=6037-xxxx-xxxx-xxxx
CARD_TO_CARD_OWNER=Card Holder Name

# Crypto via NowPayments.io
NOWPAYMENTS_API_KEY=xxx
NOWPAYMENTS_IPN_SECRET=xxx

# Iranian gateway
AQAYEPARDAKHT_API_KEY=xxx
AQAYEPARDAKHT_GATEWAY_ID=xxx

Feature Flags

Kill switches for every major feature. All boolean, all optional:

FEATURE_PURCHASE=true            # Core purchase flow
FEATURE_TRIAL=true               # Free trials
FEATURE_PROTOCOL_SELECTION=true  # Let users pick protocol
FEATURE_WALLET=true              # User wallet system
FEATURE_AFFILIATE=true           # Referral commissions
FEATURE_DISCOUNT=true            # Promo codes
FEATURE_SUPPORT=true             # Ticket system
FEATURE_PHONE_VERIFICATION=false # Require phone number
FEATURE_CHANNEL_MEMBERSHIP=false # Require Telegram channel join
FEATURE_PAY_CARD_TO_CARD=true    # Manual card payment
FEATURE_PAY_NOWPAYMENTS=true     # Crypto
FEATURE_PAY_AQAYEPARDAKHT=true   # Iranian gateway
FEATURE_RESELLER=false           # Reseller mode
FEATURE_REFUNDS=false            # Allow refunds
FEATURE_SERVICE_REMOVAL=false    # Allow service deletion
FEATURE_SERVICE_TRANSFER=false   # Allow ownership transfer

Full list: 35 flags in config/features.py.

Features

Protocol Selection

Users choose their VPN protocol (VLESS, VMess, Trojan, Shadowsocks) before checkout.

Enable per product:

UPDATE products SET allowed_protocols = '["vless", "vmess", "trojan"]' WHERE id = 1;

Or via Admin Panel: Products, Edit, set allowed_protocols.

Disable globally:

FEATURE_PROTOCOL_SELECTION=false

Marzban's API expects lowercase protocol names. The bot normalizes automatically, but if you're hitting the API directly, use vless not VLESS.

Protocol aliases:

ss maps to shadowsocks
wg maps to wireguard

Single-protocol products skip the selection step entirely.

Dynamic Config

Edit settings from Telegram without touching .env or restarting the bot.

Access: /settings (admin only)

Categories:

Sales: profit margin, currency rate, min/max order
AI: vision toggle, provider selection
Protocols: default protocol, allowed list
Security: rate limits, auto-ban thresholds
Notifications: expiry warning hours, low traffic threshold
System: sync interval, debug mode

Programmatic access:

from services.config_manager import config

# Read (cached in memory)
margin = await config.get("pricing.profit_margin", default=10)

# Write (persists to DB, updates cache)
await config.set("ai.enabled", True, updated_by=admin_id)

# Toggle boolean
await config.toggle("ux.maintenance_mode", updated_by=admin_id)

Settings are stored in app_settings table. Changes take effect immediately without restart.

Admin Commands

User commands:

/start           Register, show main menu
/menu            Main menu
/help            Help text
/services        List my services
/trial           Get free trial
/support         Open support ticket
/tickets         View my tickets
/topen <subj>    Create ticket
/treply <id> <m> Reply to ticket
/tclose <id>     Close ticket
/setpass <pass>  Set service password

Admin commands:

/admin                          Full admin panel UI
/stats                          Sales and revenue stats
/addbal <user_id> <amount>      Add wallet balance
/sync <service_id>              Sync usage from panel
/renew <service_id> <days>      Extend service
/addgb <service_id> <gb>        Add traffic
/rotate <service_id>            Rotate credentials
/payapprove <payment_id>        Approve card payment
/payreject <payment_id>         Reject card payment
/setcard <number> <owner>       Set card-to-card details
/setnowpay <api_key>            Set NowPayments key
/setaqaye <api_key> <gw_id>     Set Aqayepardakht
/setfaq <text>                  Update FAQ content
/settutorial <text>             Update tutorial content
/refund <payment_id>            Process refund
/removesvc <service_id>         Delete service
/transfersvc <svc_id> <user_id> Transfer ownership
/settings                       Dynamic config editor

Admin Panel UI (/admin):

Pending payments with photo preview
Panel management (add, test, delete)
User management (search, ban, view history)
Service ops (sync, renew, add GB, rotate)
Product CRUD with protocol configs
Ticket management
Stats dashboard

Background Jobs

Defined in services/automation.py:

job_expiry_and_traffic_reminders   Warns users before expiry/low traffic
job_payment_reconcile              Checks pending gateway payments
job_cleanup                        Purges stale data
job_admin_daily_report             Daily summary to admin channel

Usage sync runs periodically to pull stats from panels.

Panel Integrations

Supported panels:

| Panel | Method | Notes | |-----------|-----------------|-----------------------------------| | Marzban | HTTP API | Full CRUD, stats, multi-node | | PasarGuard| Direct DB access| Requires DB credentials |

Adding a new panel:

Create integrations/yourpanel/service.py
Implement VPNPanelInterface:

class YourPanelService(VPNPanelInterface):
    async def create_user(self, username: str, data_limit_bytes: int, ...) -> dict
    async def get_user(self, username: str) -> dict | None
    async def delete_user(self, username: str) -> bool
    async def update_user(self, username: str, **kwargs) -> dict
    async def get_user_stats(self, username: str) -> dict
    async def test_connection(self) -> bool
    async def get_system_stats(self) -> dict

Usage:

from integrations.factory import PanelFactory

panel = await PanelFactory.create_panel(db_panel)
await panel.create_user(username="user123", data_limit_bytes=50*1024**3)

Payments

Three gateways supported:

Card-to-Card: User sends payment, uploads receipt photo. Admin approves/rejects manually.

NowPayments: Crypto payments. BTC, ETH, USDT, etc. Automatic via IPN webhook.

Aqayepardakht: Iranian payment gateway. Automatic callback.

Payment flow:

User selects product
User picks payment method
Payment created in pending state
Gateway webhook or admin action moves to completed/failed
On completed, service provisioning triggers automatically

Webhook URL must be publicly accessible. Set PUBLIC_BASE_URL correctly.

Database

Migrations via Alembic:

alembic upgrade head                        # Apply all
alembic revision --autogenerate -m "desc"   # Generate new
alembic downgrade -1                        # Rollback one

Key tables:

users              Telegram users, phone, ban status
admins             Admin accounts with roles
products           VPN packages, pricing, protocols
product_categories Category grouping
services           Active subscriptions
purchases          Orders linking user, product, payment
payments           Payment records with gateway details
panels             VPN panel configs (encrypted creds)
app_settings       Dynamic config (key-value)
wallet_transactions User wallet history
discount_codes     Promo codes
support_tickets    Ticket system
support_messages   Ticket replies
trial_accounts     Trial tracking
audit_logs         Admin action audit trail

Development

Setup

python -m venv venv && source venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
cp .env.template .env
alembic upgrade head

Testing

pytest                                       # All 91+ tests
pytest tests/test_flows.py -v               # Unit tests
pytest tes

Sushbot

Install / Use

README

SushBotSeller

Table of Contents

Architecture

Quick Start

Docker (recommended)

Manual

Configuration

Required

Payments

Feature Flags

Features

Protocol Selection

Dynamic Config

Admin Commands

Background Jobs

Panel Integrations

Payments

Database

Development

Setup

Testing