Crypto Hub Bot — High-On-Chain Ops 🚀

Telegram channel automation + bot that publishes crypto market updates, on-chain alpha, mobile-money opportunities, and drives traffic to crypto.loopnet.tech.

Tech Stack: Node.js (Telegraf), MongoDB (Mongoose), node-cron, Gemini AI, Express
Timezone Support: Europe/London (with DST handling)
Tone: Hacker / High-energy / Mobile-first

🎯 Overview

Crypto Hub Bot automates publishing crypto market updates, alerts, memes, and mobile-money CTAs to a Telegram channel. Key features:

✅ Persistent schedule management — Create/list/pause/resume jobs stored in MongoDB
✅ Timezone-aware scheduling — Europe/London with automatic DST handling
✅ Gemini AI content generation — Dynamic market summaries and alerts
✅ Public crypto APIs — CoinGecko price feeds with caching
✅ Mobile money integrations — M-Pesa (Kenya), Airtel Money (Uganda/Malawi)
✅ Crypto deposits — USDT/BTC addresses from environment
✅ Admin management — Broadcasts, scheduled posts, dispute resolution
✅ Analytics tracking — Message views, clicks, reactions
✅ Retry/backoff logic — Resilient channel posting with exponential backoff

🚀 Quick Start

Prerequisites

Node.js 20+
MongoDB (local or Atlas)
Telegram Bot Token (create via @BotFather)
Telegram Channel (bot must be admin)

Installation

# 1. Clone repository
git clone <repo-url>
cd crypto-hub-bot

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your credentials

# 4. Start development server
npm run dev

Verify Setup

# Check bot is running
curl http://localhost:3000/api/health

# Test Telegram bot
# Send /start to your bot in Telegram

📁 Project Structure

src/
├── bot/
│   ├── admin.js              # Admin commands (schedule management)
│   └── commands.js           # User commands (/start, /deposit, /prices)
├── cron/
│   ├── channelScheduler.js   # DB-backed persistent scheduler
│   └── scheduler.js          # Simple cron jobs (price caching)
├── services/
│   ├── geminiClient.js       # Gemini AI wrapper
│   ├── priceFetcher.js       # CoinGecko API client
│   ├── channelManager.js     # Channel posting + analytics
│   ├── telegramBot.js        # Bot initialization
│   ├── analytics.js          # Analytics tracking
│   └── payments.js           # Payment helpers (placeholder)
├── models/
│   ├── User.js               # User accounts
│   ├── ChannelMessage.js     # Posted messages + analytics
│   ├── ScheduledJob.js       # Cron job definitions
│   ├── Transaction.js        # Payment records
│   ├── Subscription.js       # User subscriptions
│   ├── Alert.js              # Price alerts
│   └── PriceCache.js         # Cached price data
├── routes/
│   └── api.js                # REST API endpoints
├── utils/
│   └── paymentContacts.js    # Mobile money contact helper
├── config.js                 # Environment configuration
├── server.js                 # Express server
└── index.js                  # Application entry point

docs/                         # Comprehensive documentation (11 guides)
__tests__/                    # Jest test suite

⚙️ Environment Variables

Create .env file (never commit to git):

# === Core ===
NODE_ENV=development
PORT=3000
BASE_URL=https://crypto.loopnet.tech

# === Database ===
MONGO_URI=mongodb://localhost:27017/crypto_hub
# Or MongoDB Atlas:
# MONGO_URI=mongodb+srv://user:pass@cluster.mongodb.net/crypto_hub

# === Telegram ===
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_CHANNEL_ID=-1001234567890
ADMIN_TELEGRAM_ID=123456789

# === Gemini AI ===
GEMINI_API_KEY=AIzaSy...
GEMINI_MODEL=gemini-2.0-flash
GEMINI_TEMPERATURE=0.8
GEMINI_MAX_TOKENS=500

# === Crypto Addresses (public) ===
CRYPTO_USDT_ADDRESS=0xYourTetherUSDTAddressHere
CRYPTO_BTC_ADDRESS=bc1qyourbtcaddresshere

# === Mobile Money (E.164 format, no +) ===
MOBILE_MPESA_KE=254XXXXXXXXX
MOBILE_AIRTEL_UG=256XXXXXXXXX
MOBILE_AIRTEL_MW=265XXXXXXXXX
DEFAULT_PAYMENT_COUNTRY=KE

# === M-Pesa Daraja (optional - for STK Push) ===
MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_SHORTCODE=174379
MPESA_PASSKEY=your_passkey
MPESA_ENVIRONMENT=sandbox
MPESA_CALLBACK_URL=https://yourdomain.com/api/webhook/mpesa/callback

# === Airtel Money (optional) ===
AIRTEL_CLIENT_ID=your_client_id
AIRTEL_CLIENT_SECRET=your_client_secret
AIRTEL_ENVIRONMENT=staging

See .env.example for complete reference.

🤖 Bot Commands

User Commands

Command	Description
`/start`	Welcome message & signup CTA
`/help`	Show available commands
`/prices`	Latest crypto prices (BTC, ETH, BNB, SOL, ADA)
`/deposit [country]`	Show crypto addresses & mobile money number
`/confirm_deposit <amount>`	Confirm payment (for reconciliation)
`/alerts`	View active price alerts
`/subscribe <ticker> <price>`	Set price alert

Admin Commands (requires `ADMIN_TELEGRAM_ID`)

Command	Description
`/job_create Name \|\| cron \|\| type \|\| content`	Create scheduled job
`/job_list`	List all scheduled jobs
`/job_pause <jobId>`	Pause a job
`/job_resume <jobId>`	Resume paused job
`/job_reschedule <jobId> \|\| <newCron>`	Update job schedule
`/job_run <jobId>`	Force-run job immediately
`/broadcast <message>`	Send message to channel
`/pin <messageId>`	Pin message in channel
`/show_config`	Display configured addresses
`/seed_jobs`	Seed all automation blueprint jobs
`/clear_jobs`	Clear all jobs (requires confirm)

Job Creation Examples

Daily morning alpha (9 AM London time):

/job_create MorningAlpha || 0 9 * * * || alpha || gemini:Write a hacker-style alpha for BTC and ETH

Quick market update (every 15 minutes):

/job_create QuickUpdate || */15 * * * * || update || gemini:QUICK_UPDATE

Daily digest (6 PM London time):

/job_create EveningDigest || 0 18 * * * || digest || gemini:DAILY_DIGEST

⏰ Scheduler & Channel Management

🚀 Quick Start: Automated Content Blueprint

Seed 13 pre-configured jobs in one command:

/seed_jobs

This creates:

✅ 5-min marketing messages (drive signups)
✅ 5-min strategy tips (educate users)
✅ 10-min whale alerts (real-time on-chain data)
✅ 15-min trending coins (CoinGecko hot list)
✅ 30-min top movers (gainers/losers)
✅ Hourly market alpha (AI-generated insights)
✅ 3-hour motivation posts (inspire action)
✅ Daily greetings (morning/afternoon/night)
✅ Daily digest (complete market summary)

See full blueprint: docs/12-CHANNEL-AUTOMATION-BLUEPRINT.md

How It Works

Persistent Storage — Jobs stored in MongoDB (ScheduledJob model)
Timezone-Aware — Uses cron library with Europe/London timezone (handles DST automatically)
Dynamic Loading — On startup, loads all enabled jobs from DB
Content Rotation — Automatically rotates through 30+ pre-written templates
API Integration — Fetches live data from CoinGecko + Etherscan
AI Enhancement — Uses Gemini for dynamic content generation
Admin Control — Create/pause/resume/reschedule via Telegram commands

ScheduledJob Payload

{
  name: "MorningAlpha",
  cron: "0 9 * * *",
  timezone: "Europe/London",
  channelId: "-1001234567890",
  enabled: true,
  payload: {
    type: "alpha",           // alpha, update, digest, promo
    geminiPrompt: "...",     // AI-generated content
    content: "...",          // OR static content
    appendCTA: true          // Add CTA + disclaimer
  },
  retryPolicy: {
    retries: 2,
    backoffSec: 30
  }
}

Channel Posting Pipeline

Generate Content — Static text or Gemini AI call
Append CTA — Add link to https://crypto.loopnet.tech
Post with Retry — channelManager.postToChannel() with exponential backoff
Log Analytics — Store ChannelMessage record for tracking

💰 Payment Integrations

Crypto Deposits

Addresses configured in .env:

USDT: ERC-20 or TRC-20 address
BTC: Native SegWit (bc1...) recommended

User Flow:

User sends /deposit
Bot displays addresses with instructions
User sends crypto and uses /confirm_deposit <amount> <txid>
Admin manually verifies transaction

Future Enhancement: Implement automated verification via Etherscan/Blockchain.info APIs.

M-Pesa (Kenya)

Integration Type: Daraja API (STK Push)

Flow:

User initiates payment via bot command
Backend calls STK Push API
User receives M-Pesa prompt on phone
User enters PIN
Daraja sends callback to webhook
System updates Transaction status

Documentation: See docs/05-PAYMENT-INTEGRATION.md

Airtel Money (Uganda/Malawi)

Integration Type: Collections API

Flow:

User provides phone number
Backend initiates collection request
User receives payment prompt
User approves transaction
Webhook confirms payment
System updates Transaction status

Documentation: See docs/05-PAYMENT-INTEGRATION.md

🤖 Gemini AI Usage

Configuration

Set in .env:

GEMINI_API_KEY=your_key
GEMINI_MODEL=gemini-2.0-flash  
GEMINI_TEMPERATURE=0.7
GEMINI_MAX_TOKENS=500

Example Prompts

Hacker-style alpha:

await generateOneLineSummary({
  btc: { usd: 50000, change_24h: 2.5 },
  eth: { usd: 3000, change_24h: -1.2 }
});
// Output: "Bitcoin surges past $50K as bulls dominate the market."

Daily digest:

await generateDailyDigest(priceData);
// Output: Professional 3-4 sentence market summary

Best Practices

✅ Cache AI responses for repeated prompts
✅ Limit token length (cost optimization)
✅ Always have fallback content for API failures
✅ Monitor token usage and costs
✅ Test prompts iteratively for quality

Documentation: See docs/06-GEMINI-AI.md

🌐 API Endpoints

Public Endpoints

GET  /api/health          # Health check
GET  /api/prices          # Latest crypto prices
POST /api/subscribe       # Create subscription

Webhook Endpoints (secure in production)

POST /api/webhook/mpesa/callback       # M-Pesa STK callback
POST /api/webhook/mpesa/validation     # M-Pesa C2B validation
POST /api/webhook/mpesa/confirmation   # M-Pesa C2B confirmation
POST /api/webhook/airtel/callback      # Airtel payment callback

Admin Endpoints (add authentication)

GET  /api/admin/jobs           # List scheduled jobs
POST /api/admin/jobs           # Create job
PUT  /api/admin/jobs/:id       # Update job
DELETE /api/admin/jobs/:id     # Delete job

📚 Documentation

Comprehensive guides in docs/ directory:

00-OVERVIEW.md — Project vision & navigation
01-SETUP.md — Local development setup
02-ARCHITECTURE.md — System design
03-API-REFERENCE.md — Complete API reference
04-SCHEDULER-GUIDE.md — Cron job management
05-PAYMENT-INTEGRATION.md — M-Pesa, Airtel, crypto
06-GEMINI-AI.md — AI content generation
07-DEPLOYMENT.md — PM2, Docker, Kubernetes
08-OPERATIONS.md — Monitoring & troubleshooting
09-ROADMAP.md — 24-week implementation plan
10-SECURITY.md — Security best practices
11-TESTING.md — Testing guide with Jest

🚢 Deployment

Option 1: PM2 (Simple VPS)

# Install PM2
npm install -g pm2

# Start application
pm2 start src/index.js --name crypto-hub-bot

# Save configuration
pm2 save
pm2 startup

Option 2: Docker

# Build image
docker build -t crypto-hub-bot .

# Run container
docker run -d \
  --name crypto-hub-bot \
  --env-file .env \
  -p 3000:3000 \
  crypto-hub-bot

Option 3: Docker Compose

docker-compose up -d

Option 4: Kubernetes

See docs/07-DEPLOYMENT.md for complete Kubernetes manifests.

🧪 Testing

Run Tests

# Install test dependencies
npm install --save-dev jest supertest mongodb-memory-server nock @jest/globals

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Test Structure

__tests__/
├── setup.js                      # MongoDB Memory Server setup
├── models/
│   ├── User.test.js
│   └── Transaction.test.js
├── services/
│   └── priceFetcher.test.js
└── utils/
    └── paymentContacts.test.js

Documentation: See docs/11-TESTING.md

🔧 Troubleshooting

Bot Not Responding

Check:

TELEGRAM_BOT_TOKEN is correct
Bot is admin in channel
MongoDB connection successful

# Test bot connection
curl https://api.telegram.org/bot<TOKEN>/getMe

# Check logs
pm2 logs crypto-hub-bot

Jobs Not Running

Check:

Job is enabled (ScheduledJob.enabled = true)
Cron expression is valid
Timezone is set to Europe/London

# List jobs via admin command
/job_list

# Force run to test
/job_run <jobId>

Payment Webhook Not Received

Check:

Webhook URL is HTTPS
Port 443 is open
URL is registered with payment provider
Server responds with 200 status quickly

# Test webhook endpoint
curl -X POST https://yourdomain.com/api/webhook/mpesa/callback \
  -H "Content-Type: application/json" \
  -d '{"test":"data"}'

More troubleshooting: See docs/08-OPERATIONS.md

🛣️ Roadmap

Phase 1: MVP (Weeks 1-8)

✅ Bot with basic commands
✅ Channel automation
✅ Price fetching
✅ Admin commands
✅ Payment integration setup

Phase 2: Growth (Weeks 9-16)

Phase 3: Enterprise (Weeks 17-24)

Full roadmap: See docs/09-ROADMAP.md

🔒 Security

⚠️ Important Security Notes:

Never commit .env to git
Use environment variables for all secrets
Rotate API keys regularly
Validate all webhook payloads
Implement rate limiting on API endpoints
Use HTTPS for all webhook URLs
Add authentication to admin endpoints

Full security guide: See docs/10-SECURITY.md

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

📞 Support

Documentation: Check docs/ directory
Issues: Open GitHub issue
Email: support@crypto.loopnet.tech
Telegram: @your_support_channel

🎯 Quick Commands Cheat Sheet

# Development
npm run dev                    # Start with hot reload
npm test                       # Run tests
npm run test:coverage          # Generate coverage report

# Production
npm start                      # Start application
pm2 start src/index.js         # Start with PM2
docker-compose up -d           # Start with Docker

# Admin (via Telegram)
/job_create                    # Create scheduled job
/job_list                      # View all jobs
/broadcast <msg>               # Send to channel
/show_config                   # View configuration

Built with ❤️ for the crypto community

🔗 crypto.loopnet.tech

Name		Name	Last commit message	Last commit date
.github		.github
__tests__		__tests__
docs		docs
logs		logs
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
STARTUP.md		STARTUP.md
ecosystem.config.cjs		ecosystem.config.cjs
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
test-gemini.js		test-gemini.js

Latest commit

History

Folders and files

Repository files navigation

Crypto Hub Bot — High-On-Chain Ops 🚀

📋 Table of Contents

🎯 Overview

🚀 Quick Start

Prerequisites

Installation

Verify Setup

📁 Project Structure

⚙️ Environment Variables

🤖 Bot Commands

User Commands

Admin Commands (requires ADMIN_TELEGRAM_ID)

Job Creation Examples

⏰ Scheduler & Channel Management

🚀 Quick Start: Automated Content Blueprint

How It Works

ScheduledJob Payload

Channel Posting Pipeline

💰 Payment Integrations

Crypto Deposits

M-Pesa (Kenya)

Airtel Money (Uganda/Malawi)

🤖 Gemini AI Usage

Configuration

Example Prompts

Best Practices

🌐 API Endpoints

Public Endpoints

Webhook Endpoints (secure in production)

Admin Endpoints (add authentication)

📚 Documentation

🚢 Deployment

Option 1: PM2 (Simple VPS)

Option 2: Docker

Option 3: Docker Compose

Option 4: Kubernetes

🧪 Testing

Run Tests

Test Structure

🔧 Troubleshooting

Bot Not Responding

Jobs Not Running

Payment Webhook Not Received

🛣️ Roadmap

Phase 1: MVP (Weeks 1-8)

Phase 2: Growth (Weeks 9-16)

Phase 3: Enterprise (Weeks 17-24)

🔒 Security

📄 License

🤝 Contributing

📞 Support

🎯 Quick Commands Cheat Sheet

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Admin Commands (requires `ADMIN_TELEGRAM_ID`)