AiogramShopBot is a software product based on Aiogram3, SQLAlchemy, and SQLAdmin that allows you to automate the sale of digital and physical goods in Telegram. One of the advantages of the bot is that AiogramShopBot implements the ability to replenish funds using Bitcoin, Litecoin, Solana, Ethereum, Binance Coin and Stablecoins, which allows you to sell goods worldwide.
The bot implements the most popular features: a referral system, a review feature, a web admin panel for working with database objects, multiple i18n localization, and much more.

• 🤝 Commercial offers
  • ➤ Telegram.
  • 🤖 AiogramShopBotDemo.
• ✨ Donate
• 1.Launch the bot
  • 1.0 Description of required environment variables.
  • 1.1 Quick start.
  • 1.2 Launch AiogramShopBot without SQLCipher database encryption.
• 2. 👥 AiogramShopBot User's Manual
  • 2.1 🖥️ Registration
  • 2.2 ➕ Top Up Balance
  • 2.3 👜 Purchase of goods
  • 2.4 🧾 Purchase History
• 3. 🔑 AiogramShopBot Admin Manual
  • 3.1 🔑 Adding a new admin
  • 3.2 📢 Announcements
    • 3.2.1 📢 Send to Everyone
    • 3.2.2 🔄 Restocking Message
    • 3.2.3 🗂️ Current Stock
  • 3.3 📦 Inventory Management
    • 3.3.1 ➕ Add Items
      • 3.3.1.1 JSON
      • 3.3.1.2 TXT
  • 3.4 👥 User Management
    • 3.4.1 💳 Credit Management
      • 3.4.1.1 ➕ Add balance
      • 3.4.1.2 ➖ Reduce balance
    • 3.4.2 ↩️ Make Refund
  • 3.5 📊 Analytics & Reports
    • 3.5.1 📊 Statistics
  • 3.6 🔔 Admin notifications
    • 3.6.1 Notification to admin about new deposit
    • 3.6.2 Notification to admin about new buy
  • 3.8 👛 Wallet
    • 3.8.1 Cryptocurrency withdrawal
  • 3.9 📷 Media management
  • 3.10 🎪 Coupons management
    • 3.10.1 🎫 Create new coupon
    • 3.10.2 📋 View all coupons
  • 3.11 📦 Shipping management
    • 3.11.1 🚚 Create new shipping option
    • 3.11.2 📋 View all shipping options
  • 3.12 🛍 Buys management
  • 3.13 ⭐ Reviews Management
• 4.0 Cryptocurrency Forwarding
• 5.0 Referral System
  • 5.1 Access to the Referral System
  • 5.2 How Referrals Work
  • 5.3 Referral Bonuses (Referred User)
  • 5.4 Referrer Bonuses (Inviting User)
  • 5.5 Global Bonus Cap
  • 5.6 Anti-Abuse Guarantees
• 6.0 Admin panel with web interface (SQLAdmin)
• 7.0 Multibot (Experimental functionality)
  • 5.1 Starting the multibot
• 📋 Todo List
• MIT License

• BTC - bc1q2kv89q8yvf068xxw3x65gzfag98l9wnrda3x56
• LTC - ltc1q0tuvm5vqn9le5zmhvhtp7z9p2eu6yvv24ey686
• TRX - THzRw8UpTsEYBEG5CCbsCVnJzopSHFHJm6
• SOL - Avm7VAqPrwpHteXKfDTRFjpj6swEzjmj3a2KQvVDvugK
• ETH - 0xB49D720DE2630fA4C813d5B4c025706E25cF74fe
• TON - UQD0QetwXoYTsmbZWVbE_z_JUFh54RVVRUxCbCHQkLsl3Hfn
• USDT ERC20 - 0xB49D720DE2630fA4C813d5B4c025706E25cF74fe
• USDT BEP20 - 0xB49D720DE2630fA4C813d5B4c025706E25cF74fe
• USDT TRC20 - THzRw8UpTsEYBEG5CCbsCVnJzopSHFHJm6

Connect to your VPS via SSH and run this command. An interactive script will prompt you for variables for .env.

sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/ilyarolf/AiogramShopBot/refs/heads/master/scripts/deploy.sh)"

For local development on a computer which is not internet facing, set the "RUNTIME_ENVIRONMENT" to "dev". The bot will be connected via an ngrok tunnel.

⚠️ Note
To get the ngrok token, you need to register on the ngrok website and confirm your email. Then you will have the ngrok token in your personal account.
You will still need Redis.

On an internet facing production system you can either set your own hostname in the caddy label (in the template shown with "YOUR_DOMAIN_GOES_HERE" or make use of services like sslip.io. Caddy will automatically pull a TLS certificate and serves as reverse proxy for your bot. You can also run your bot together with an already existing reverse proxy. In this case you have to remove the caddy service from the docker-compose file and configure the reverse proxy accordingly.

⚠️ Note
Please note that in order to deploy the bot locally, you must have a reverse proxy, Redis, and PostgreSQL configured.

• Clone the project from the master branch.
  git clone https://github.com/ilyarolf/AiogramShopBot.git
• Install all necessary packages
  pip install -r requirements.txt
• Set the environment variables to run in the .env file.
  Example:

WEBHOOK_PATH = "/"
WEBAPP_HOST = "localhost"
WEBAPP_PORT = 5000
TOKEN = "1234567890:QWER.....TYI"
ADMIN_ID_LIST = 123456,654321
SUPPORT_LINK = "https://t.me/your_username_123"
POSTGRES_USER = "postgres"
DB_ENCRYPTION = "false"
POSTGRES_PASSWORD = "qwertyu"
DB_PORT = "5432"
DB_HOST = "localhost"
POSTGRES_DB = "aiogram-shop-bot"
NGROK_TOKEN = "NGROK_TOKEN_HERE"
PAGE_ENTRIES = "8"
MULTIBOT = "false"
CURRENCY = "USD"
RUNTIME_ENVIRONMENT = "PROD"
WEBHOOK_SECRET_TOKEN = "1234567890"
KRYPTO_EXPRESS_API_KEY = "API_KEY_HERE"
KRYPTO_EXPRESS_API_URL = "https://kryptoexpress.pro/api"
KRYPTO_EXPRESS_API_SECRET = "1234567890"
REDIS_PASSWORD = "1234567890"
REDIS_HOST = "localhost"
CRYPTO_FORWARDING_MODE = "false"
BTC_FORWARDING_ADDRESS = ""
LTC_FORWARDING_ADDRESS = ""
ETH_FORWARDING_ADDRESS = ""
SOL_FORWARDING_ADDRESS = ""
BNB_FORWARDING_ADDRESS = ""
MIN_REFERRER_TOTAL_DEPOSIT = "500"
REFERRAL_BONUS_PERCENT = "5"
REFERRAL_BONUS_DEPOSIT_LIMIT = "3"
REFERRER_BONUS_PERCENT = "3"
REFERRER_BONUS_DEPOSIT_LIMIT = "5"
REFERRAL_BONUS_CAP_PERCENT = "7"
REFERRER_BONUS_CAP_PERCENT = "7"
TOTAL_BONUS_CAP_PERCENT = "12"
SQLADMIN_RAW_PASSWORD = "admin"
JWT_EXPIRE_MINUTES = "30"
JWT_ALGORITHM = "HS256"
JWT_SECRET_KEY = "1234567890"

• After these steps the bot is ready to run, launch the bot with command python run.py

User registration occurs when the bot is first accessed with the /start command.

• Open my profile menu using the “👤 My profile” button.
• Open top-up menu using the “➕ Top Up Balance” button.
• In the resulting menu, click on cryptocurrency name button.
• Copy cryptocurrency address, and send cryptocurrency on this address.
• Once your transaction has at least one confirmation you will receive notification from the bot.

To buy any item, go to "All categories" -> Select any category -> Select any subcategory -> Select quantity -> Confirm purchase. If the purchase is successful, you will immediately receive a message in the format:

• To access your purchase history go to "My Profile" -> "Purchase History".
• You will be presented with an inline keyboard with all your purchases, by clicking on any of the purchases you will be sent a message in the format from paragraph 2.3.

To add a new admin you need to add his telegram id to the ADMIN_ID_LIST environment variable, separated by commas, and reload the bot.
For example: ADMIN_ID_LIST=123456,654321

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the announcements menu using the “📢 Announcements” button.
• In the resulting menu, click on “📢 Send to Everyone” button.
• Type a message or forward to the bot, the bot supports sending a message with pictures and Telegram markup (bold, italics, spoilers, etc.).
• Confirm or decline the sending of messages.
• After successful message sending, the original message with inline buttons "Confirm", "Decline" will change like on gif.
  

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the announcements menu using the “📢 Announcements” button.
• In the resulting menu, click on “🔄 Restocking Message” button.
• This message is generated based on items in the database that have "is_new" is true.

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the announcements menu using the “📢 Announcements” button.
• In the resulting menu, click on “🗂️ Current Stock” button.
• This message is generated based on items in the database that have "is_sold" is false.

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the announcements menu using the “📦 Inventory Management” button.
• Open the add items menu using the “➕ Add Items” button.
• In the resulting menu, click on “JSON” button.
• Send .json file with new items.
  Example of .json file:

⚠️ Note
The "private_data" property is what the user gets when they make a purchase.

[
  {
    "item_type": "Physical",
    "category": "Category#1",
    "subcategory": "Subcategory#1",
    "price": 50,
    "description": "Mocked description",
    "private_data": null
  },
  {
    "item_type": "Digital",
    "category": "Category#2",
    "subcategory": "Subcategory#2",
    "price": 100,
    "description": "Mocked description",
    "private_data": "Mocked private data"
  }
]

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the inventory management menu using the “📦 Inventory Management” button.
• Open the add items menu using the “➕ Add Items” button.
• In the resulting menu, click on “TXT” button.
• Send .txt file with new items.
  Example of .txt file:

PHYSICAL;CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;null
PHYSICAL;CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;null
PHYSICAL;CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;null
PHYSICAL;CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;null
DIGITAL;CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#5
DIGITAL;CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#6
DIGITAL;CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#7
DIGITAL;CATEGORY#1;SUBCATEGORY#1;DESCRIPTION#1;50.0;PRIVATE_DATA#8

⚠️ Note
This way, you will delete all products from “All categories” with the category or subcategory you picked and deleted.

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the inventory management menu using the “📦 Inventory Management” button.
• Open the add items menu using the “🗑️ Delete Category” or “🗑️ Delete Subcategory” button.
• In the resulting menu, select the category or subcategory you want to delete.
• Confirm or cancel the deletion of the category or subcategory.

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the user management menu using the “👥 User Management” button.
• Open the credit management menu using the “💳 Credit Management” button.
• In the resulting menu, click on “➕ Add balance” button.
• Send the user entity object that belongs to the user you want to add the balance to. This can be telegram id or telegram username.
• Send the value by which you want to add the balance to the user.

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the user management menu using the “👥 User Management” button.
• Open the credit management menu using the “💳 Credit Management” button.
• In the resulting menu, click on “➖ Reduce balance” button.
• Send the user entity object that belongs to the user you want to add the balance to. This can be telegram id or telegram username.
• Send the value by which you want to reduce the balance to the user.

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the user management menu using the “👥 User Management” button.
• Open the refund menu using the “↩️ Make Refund” button.
• In the resulting menu, click on the buy button you want to refund.
• Confirm or cancel refund.

• Open the admin menu using the “🔑 Admin Menu” button.
• Open the statistics menu using the “📊 Analytics & Reports” button.
• In the resulting menu, click on the entity for which you want to get statistics.
• In the resulting menu, click on the time period for which you want statistics.

⚠️ Note
All users with telegram id in the .env ADMIN_ID_LIST environment variable will receive these notifications

• If any user topped up the balance and clicked on the "Refresh balance" button, you will receive the following message from the bot:

After each purchase, you will receive a message in the format:

To withdraw cryptocurrency from the bot, open the admin menu, go to the wallet tab, select the cryptocurrency you want to withdraw, send the cryptocurrency address where you want to withdraw and confirm the withdrawal. After a successful withdrawal, the bot will send you a link to the blockchain browser with the transaction.

To change the media for a category, subcategory, or text buttons, open 🔑 Admin Menu->📷 Media management.

⚠️ Note
Media can be GIFs, images, or videos.

With 🎪 Coupons management, you can create a new coupon or modify an existing one.

To create a coupon, select the coupon type—either 📊 Percentage or 💰 Fixed. Then, choose the usage limit: ♾️ Infinite or 1️⃣ Single-use. Next, enter the coupon value (discount percentage or fixed amount). Provide a coupon name, and finally confirm or cancel the creation.

You can disable or enable coupons. Open 🔑 Admin Menu->🎪 Coupons management->📋 View all coupons, select a coupon by name, and choose an action.

To create a new shipping method, open 🔑 Admin Menu->📦 Shipping management->🚚 Create new shipping option, then enter the name of the shipping method and the cost in fiat currency.

You can change the price, name, or disable an existing shipping method. Open 🔑 Admin Menu->📦 Shipping management->📋 View all shipping options, then select the shipping method and choose the desired action.

With 🛍 Buys management, you can view all your users' purchases. This feature is mainly used to update tracking numbers for physical goods purchases. After the tracking number is updated, the user will receive a notification.

With ⭐ Reviews Management, you can view all reviews of your customers' purchases. You can also delete the text and image of a review to avoid unwanted advertising.

You can enable cryptocurrency forwarding, in which case all cryptocurrency will be redirected from KryptoExpress addresses to your addresses.
To enable cryptocurrency forwarding, you need to set the CRYPTO_FORWARDING_MODE variable to true and set values for {CRYPTO}_FORWARDING_ADDRESS in .env.

⚠️ Note
BTC and LTC addresses must be in Bech32 format.

The referral system is designed to stimulate organic growth of the bot while keeping the bonus economy fully controlled and predictable. All referral rewards are credited as internal bonus balance and cannot be withdrawn. Bonuses can only be used to purchase digital or physical products inside the bot.

A user can become a referrer only after reaching a minimum total deposit amount.

• MIN_REFERRER_TOTAL_DEPOSIT
  The minimum total amount of deposits required to unlock the referral system.

Until this threshold is reached, the user cannot generate or use a referral link.

Each eligible user can generate a unique referral link.
When a new user joins the bot using this link and makes a deposit, the referral relationship is permanently established.

Referral bonuses are applied only to deposits made after the referral relationship is created.

The referred user receives a bonus added to their balance on eligible deposits.

• REFERRAL_BONUS_PERCENT
  Percentage bonus applied to each eligible deposit made by the referred user.

• REFERRAL_BONUS_DEPOSIT_LIMIT
  Number of deposits that can receive the referral bonus.

• REFERRAL_BONUS_CAP_PERCENT
  Maximum total bonus the referred user can receive, expressed as a percentage of their own deposits.

If the cap is reached, no further referral bonuses are granted.

The referrer earns a bonus from the deposits made by each referred user.

• REFERRER_BONUS_PERCENT
  Percentage of the referred user’s deposit credited to the referrer.

• REFERRER_BONUS_DEPOSIT_LIMIT
  Number of deposits per referred user that generate a referrer bonus.

• REFERRER_BONUS_CAP_PERCENT
  Maximum total bonus the referrer can earn from a single referred user, expressed as a percentage of that referral’s deposits.

To ensure economic safety, a global cap limits the total bonuses generated from a single referral.

• TOTAL_BONUS_CAP_PERCENT
  The maximum combined bonus (referral + referrer) that can be generated from a referred user, expressed as a percentage of that user’s deposits.

If the combined bonuses exceed this limit, the system prioritizes the referred user’s bonus. Any remaining bonus capacity is applied to the referrer.

The referral system includes multiple safeguards:

• Referral access is locked behind a minimum deposit requirement
• Bonuses apply only to a limited number of deposits
• Individual and global bonus caps prevent excessive rewards
• Self-referrals are explicitly forbidden

These measures ensure sustainable growth and predictable costs without relying on product margins.

You can work with database objects using the SQLAdmin admin panel.
This panel is always available at {YOUR_IP_ADDRESS}.sslip.io/admin
Login: admin
Password: ${SQLADMIN_RAW_PASSWORD}

• Set all environment variables in docker-compose.yml and set the variable “true” for MULTIBOT. MULTIBOT="true"
• Run the docker-compose up command.
• After successful execution of the command, you will only deploy a manager bot for other bots, it will not have functionality for buying items etc. To deploy a bot with functionality to sell goods etc..., you need to send the command /add $TOKEN to the bot manager. If everything is successful, you will receive this notification.

• Make migration from direct raw database queries to SQLAlchemy ORM.
• Add option to encrypt database via SQLCipher (when using SQLAlchemy).
• Add an option to generate new crypto addresses using new mnemonic phrases so that 1 user=1 mnemonic phrase.
• Items pagination.
• Make the functionality of database backup by action in the admin in the Telegram bot.
• Make the functionality of generating statistics of sales and users in the bot for a month/week/day in the admin panel.
• Make the functionality of generating statistics of deposits in the bot for a month/week in the admin panel.
• Functionality for sorting products by name/quantity/price.
• Functionality for searching products by name (filtering).
• Cryptocurrency forwarding mode.
• Functionality for adding media to categories/subcategories/buttons. Media can be GIFs, images, or videos.
• Improved shopping cart functionality, added the ability to add and remove products as in marketplaces (+1/-1 buttons).
• Improved User Management functionality, added user blocking functionality.
• Review functionality.
• Functionality for selling physical goods with shipping.
• Multiple localization (i18n), the bot will respond in the language of your Telegram application or in English by default.
• Referral system.
• Web interface for the admin panel. (SQLAdmin)
• Interactive script for deploying the bot without programming skills, etc.