NumHub 🚀

A Persian Telegram bot for buying virtual phone numbers for Telegram account registration — a real shop powered by 10 SMS-activation providers.

📖 The Story

NumHub (نام هاب) was a Telegram bot my business partner and I built and ran to resell virtual phone numbers for creating Telegram accounts. Buyers topped up a wallet, picked a country, and the bot fetched a number from one of 10 activation panels, checked it was fresh, delivered the login code automatically, and refunded or cancelled with one tap.

It ran for real users, took real payments through the Zarinpal gateway, and quietly did the boring job of polling SMS APIs all day. We eventually sold the business. This repo is the production codebase, cleaned up for public viewing. 🖤

🙏 Special Thanks

Nima — thank you for everything along the way, from building this together to the day we closed the deal. This one's partly yours. 🖤

---

✨ Features

• ⚡ Multi-provider shop — 180+ numbers across 10 SMS-activation APIs (SMSLive, SMSVerified, VakSMS, TigerSMS, Durian, FASTTG, Grizzly, FASTPVA, Ijiema, SMSBower) behind one Telegram keyboard.
• 🔐 Channel gating — users must join your channel(s) before they can use the bot (FORCE_CHANNELS).
• 🧪 Phone verification — users must verify a phone number through a companion bot before charging their account.
• 🏦 Wallet system — top up by card or the Zarinpal gateway, transfer balance between users, and view the last 20 transactions.
• 🔍 Number checker — a fresh-number checker rejects occupied/banned numbers and only hands over "clean" ones.
• 🎟️ VIP plans & ready-made accounts — paid VIP tiers for premium providers, plus pre-registered "ready account" numbers.
• 📊 Admin panel — add/reset balances, grant VIP, cancel numbers, view sales by day and country, toggle providers on/off, ban/unban users.
• 🚦 Resilient queues — p-queue pipelines that retry number delivery and poll for codes until the SMS arrives or the order times out.
• 🗨️ Persian-first UX — every user-facing message and keyboard is in Persian.

🛠️ Tech Stack

Layer	Tech
Runtime	Node.js 18+
Language	TypeScript
Bot	grammY + conversations + ratelimiter
Database	MongoDB (Mongoose ODM)
Queues	p-queue
Payments	Zarinpal via a payment gateway API

🚀 Getting Started

Prerequisites

• Node.js 18+
• MongoDB (local or Atlas)

Installation

npm install

Configuration

Copy the env template and fill it in:

cp .env.example .env

Variable	Description
TOKEN	Telegram bot token (from @BotFather)
DATABASE_URL	Main MongoDB connection string
VERIFY_DATABASE_URL	MongoDB connection string for the verification DB
FORCE_CHANNELS	Comma-separated channel usernames users must join
LOG_CHANNEL	Telegram channel ID for sale logs
RECEIPT_CHANNEL	Telegram channel ID for payment receipts
SALES_CHANNEL	Telegram channel ID for public sale feed
PAYMENT_API_KEY	Payment gateway password
CHECKER_API_URL	Phone-number checker endpoint
CHECKER_API_KEY	Phone-number checker API key
SMS_API_KEY … SMSBOWER_API_KEY	Per-provider SMS-activation API keys
DURIAN_USERNAME	Durian panel account username
IJIEMA_UID	Ijiema panel account user ID
BANIAPP_API_KEY	Gateway balance-check API key

All provider keys are plaintext in .env — keep it gitignored (it already is).

Run

npm start

This compiles TypeScript in watch mode and restarts dist/bot.js on changes via nodemon. Open your bot in Telegram and hit /start.

📜 Scripts

npm start     # dev: watch-mode compile + nodemon restart
npm run build # compile TypeScript once into dist/

📁 Project Structure

src/
├── bot.ts                 # Bot setup, session, middleware wiring, DB connect
├── commands/              # /start, main menu, shop, admin panel
├── conversations/         # Step-by-step flows (payment, charge, VIP, transfers)
├── models/                # Mongoose schemas (user, purchase, balance, number, setting)
├── sms/                   # Provider adapters: get/cancel/status/newcode/checker
├── purchase/              # Order creation, cancellation, code-re-request
├── user/                  # Balance & VIP helpers
├── middleware/            # Auth, admin, forced-channel middlewares
├── data.ts                # Country catalog + prices per provider
├── keyboards.ts           # All reply/inline keyboards
└── queues.ts              # Delivery & code-polling pipelines

☁️ Deployment

Run it on any Node.js server or VPS: npm run build && npm start, with MongoDB reachable from DATABASE_URL and all credentials in .env. Everything the bot needs is configured through environment variables — no code changes required per environment.

⚠️ Disclaimer

This is an archived production codebase from a business that has been sold.

• No live credentials are included — hardcoded keys were moved to environment variables and secrets were stripped from the code.
• The bot is not actively maintained and the numbers/providers listed may no longer exist.
• Code style, Persian text, and architecture reflect a small two-person operation, not an enterprise codebase. It's shared as a learning/portfolio piece.

📄 License

All rights reserved. Published for viewing and educational purposes only.