Skip to content

dylanpersonguy/DCC-TG-Meme-Scanner-Bot

BranchesTags

Repository files navigation

🔎 DCC Token Scanner Bot

Real-Time Token Intelligence for DecentralChain — Powered by Telegram

TypeScript Node.js Telegram Bot PostgreSQL Redis pnpm License: MIT

Scan any token. Detect risk. Track deployers. Monitor alpha.

A production-grade, Telegram-native token intelligence platform for the DecentralChain ecosystem. Instantly scan tokens, analyze risk scores, inspect deployer history, monitor whale movements, track trending assets, and surface alpha — all from inside Telegram.

Getting Started · Architecture · Features · Commands · Self-Hosting

✨ Features

Feature Description
🔎 Instant Token Scan Paste any asset ID or use /scan — get name, supply, price, risk score, deployer info in seconds
⚠️ Risk Scoring Engine Pluggable rule-based risk evaluation (0–100) with severity factors and confidence scores
🏗️ Deployer Profiling Track deployer wallets — token count, scam history, first-seen block, labels
📊 Market Data Real-time price, volume, liquidity, market cap, and 24h change metrics
📈 Trending Tokens Algorithmically ranked trending assets based on on-chain activity
👥 Holder Analysis Top holder distribution with balance rankings and concentration percentages
💧 Pool & Liquidity DEX pool discovery with reserve tracking and liquidity depth
🕯️ OHLCV Charts Candle aggregation service (1m → 1d) for charting via Mini App
🔔 Smart Alerts User-configurable alerts delivered directly via Telegram DM
🏆 Alpha Leaderboard Track who calls winning tokens first in group chats
⭐ Watchlists Personal token watchlists with quick-access scanning
📱 Telegram Mini App Rich UI with interactive charts, holder tables, and risk badges
🛡️ Admin Console Web dashboard for managing flags, scam entities, and system health

🏗 Architecture

┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│  Telegram    │     │  Telegram   │     │   Admin      │
│  Bot         │     │  Mini App   │     │   Console    │
│  (Telegraf)  │     │  (Next.js)  │     │   (Next.js)  │
└──────┬───────┘     └──────┬──────┘     └──────┬───────┘
       │                    │                    │
       └────────────┬───────┴────────────────────┘
                    │
            ┌───────▼────────┐
            │  Scanner API   │  ← Fastify REST + WebSocket gateway
            │  (Fastify)     │
            └───────┬────────┘
                    │
       ┌────────────┼────────────────────┐
       │            │                    │
┌──────▼──┐  ┌─────▼──────┐  ┌──────────▼──────┐
│ Market   │  │   Risk     │  │  Chart          │
│ Data Svc │  │   Engine   │  │  Service        │
└──────┬───┘  └─────┬──────┘  └──────────┬──────┘
       │            │                    │
       └────────────┼────────────────────┘
                    │
            ┌───────▼────────┐
            │  Chain Indexer  │  ← Real-time block ingestion
            └───────┬────────┘
                    │
            ┌───────▼────────┐
            │  DecentralChain│  ← Mainnet node
            │  Node          │
            └────────────────┘

Cross-cutting: PostgreSQL · Redis · BullMQ

Monorepo Structure

dcc-tg-meme-scanner-bot/
├── apps/
│   ├── scanner-api/           # Fastify REST/WS API gateway
│   ├── telegram-bot/          # Telegraf-based Telegram bot
│   ├── telegram-miniapp/      # Next.js Telegram Mini App (TWA)
│   ├── chain-indexer/         # Real-time block & transaction ingestion
│   ├── market-data-service/   # Price, volume, trending computation
│   ├── risk-engine/           # Token risk scoring pipeline
│   ├── alerts-engine/         # Alert evaluation & Telegram delivery
│   ├── chart-service/         # OHLCV candle aggregation
│   └── admin-console/         # Next.js admin dashboard
│
├── packages/
│   ├── blockchain-client/     # DecentralChain node adapter layer
│   ├── shared-sdk/            # Types, DTOs, constants, event defs
│   ├── db/                    # Prisma schema (25 tables), migrations
│   ├── config/                # Zod-validated env loading
│   ├── logger/                # Pino structured logging
│   ├── telegram-ui/           # Message formatters & keyboard builders
│   └── risk-rules/            # Pluggable risk rule modules
│
├── docker/                    # Per-service Dockerfiles
├── docker-compose.yml         # Full-stack local dev environment
└── architecture.md            # Detailed architecture document

Data Flow

  1. Chain Indexer polls DecentralChain nodes for new blocks in real-time
  2. Transactions are parsed into normalized events (TOKEN_CREATED, SWAP_EXECUTED, TRANSFER, etc.)
  3. Events persist to PostgreSQL and publish to Redis/BullMQ job queues
  4. Market Data Service computes rolling metrics (price, volume, trending scores)
  5. Risk Engine evaluates tokens against pluggable rule modules, producing 0–100 risk scores
  6. Chart Service aggregates swap events into multi-timeframe OHLCV candles
  7. Alerts Engine evaluates user-defined rules and delivers notifications via Telegram
  8. Scanner API serves unified REST + WebSocket access to all data
  9. Telegram Bot handles commands, auto-detects pasted asset IDs, and renders rich scan cards
  10. Mini App provides interactive charts, holder tables, and detailed token views

🤖 Bot Commands

Command Description
/scan <assetId> Full token scan with risk analysis
/trending View top trending tokens by on-chain activity
/deployer <address> Inspect deployer wallet history
/wallet <address> View wallet profile and activity
/alpha Group alpha caller leaderboard
/watchlist Manage your personal token watchlist
/help Show all available commands

Tip: You can also paste any DCC asset ID directly — the bot auto-detects and scans it.

🚀 Getting Started

Prerequisites

Dependency Version Purpose
Node.js ≥ 20.0 Runtime
pnpm ≥ 9.0 Package manager
PostgreSQL ≥ 15 Primary database
Redis ≥ 7.0 Caching & job queues

Quick Start

# Clone the repository
git clone https://github.com/dylanpersonguy/DCC-TG-Meme-Scanner-Bot.git
cd DCC-TG-Meme-Scanner-Bot

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration (see Environment Variables below)

# Set up database
pnpm db:generate
pnpm db:migrate
pnpm db:seed

# Build all packages
pnpm build

# Start all services in development mode
pnpm dev

Docker Quick Start

# Start full stack with Docker Compose
docker compose up -d

# View logs
docker compose logs -f

⚙️ Environment Variables

Create a .env file in the project root:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dcc_scanner

# Redis
REDIS_URL=redis://localhost:6379

# DecentralChain Node
DCC_NODE_URL=https://mainnet-node.decentralchain.io
DCC_DATA_SERVICE_URL=https://mainnet-node.decentralchain.io
DCC_CHAIN_ID=D

# Telegram
TELEGRAM_BOT_TOKEN=your_bot_token_here

# API
API_PORT=3200

# Indexer
INDEXER_START_HEIGHT=0
INDEXER_BATCH_SIZE=10
INDEXER_POLL_INTERVAL_MS=2000

🛠 Self-Hosting Guide

1. Create a Telegram Bot

  1. Message @BotFather on Telegram
  2. Send /newbot and follow the prompts
  3. Copy the bot token to your .env file

2. Set Up PostgreSQL

createdb dcc_scanner
pnpm db:migrate
pnpm db:seed

3. Start Services

You can start services individually or all at once:

# All services (development)
pnpm dev

# Individual services
pnpm --filter @dcc-scanner/chain-indexer run dev
pnpm --filter @dcc-scanner/scanner-api run dev
pnpm --filter @dcc-scanner/telegram-bot run dev
pnpm --filter @dcc-scanner/market-data-service run dev
pnpm --filter @dcc-scanner/risk-engine run dev
pnpm --filter @dcc-scanner/alerts-engine run dev
pnpm --filter @dcc-scanner/chart-service run dev

4. Production Deployment

# Build all services
pnpm build

# Start in production
NODE_ENV=production pnpm --filter @dcc-scanner/scanner-api run start
NODE_ENV=production pnpm --filter @dcc-scanner/telegram-bot run start
# ... repeat for each service

🧪 Tech Stack

Layer Technology
Language TypeScript 5.7 (strict mode)
Runtime Node.js 20+ (ES2022 target)
Monorepo pnpm workspaces
Bot Framework Telegraf 4
API Framework Fastify 5 (REST + WebSocket)
Frontend Next.js 15 + React 19 + Tailwind CSS 4
Database PostgreSQL 16 + Prisma ORM
Cache & Queues Redis 7 + BullMQ 5
Charts Lightweight Charts (TradingView)
Logging Pino (structured, JSON)
Validation Zod schemas at all boundaries
Testing Vitest

📊 Database Schema

25 tables covering the full token intelligence domain:

  • Users & Telegram — telegram_users, telegram_groups
  • Tokens & Metadata — tokens, deployers, pools
  • Market Data — token_price_snapshots, candles
  • Risk Scoring — risk_scores, risk_score_factors
  • Holder Analytics — holder_snapshots
  • Trading Activity — swaps, transfers
  • Alerts & Watchlists — alerts, alert_notifications, watchlists, watchlist_items
  • Alpha Tracking — group_alpha_calls, group_alpha_performance
  • System — indexer_checkpoints, scan_history, admin_flags, known_scam_entities

🔑 Design Principles

  • Event-Driven Architecture — Chain indexer publishes normalized events; downstream services subscribe via BullMQ
  • Adapter Pattern — All blockchain SDK access isolated in blockchain-client package
  • Idempotent Ingestion — Indexer supports replay from any block height
  • Pluggable Risk Rules — Each risk factor is a self-contained, testable module
  • BigNumber Everywhere — No floating-point math for financial data
  • Zod at Boundaries — All API input/output validated with typed schemas
  • Structured Logging — Pino with correlation IDs across all services
  • Graceful Degradation — Bot falls back to direct node queries when API is unavailable

📁 API Endpoints

Scanner API (/api)

Method Endpoint Description
GET /tokens/trending Trending tokens by activity
GET /tokens/new Recently created tokens
GET /tokens/:assetId Token details
GET /tokens/:assetId/scan Full token scan with risk
GET /tokens/:assetId/holders Holder distribution
GET /tokens/:assetId/candles OHLCV price candles
GET /tokens/:assetId/risk Risk score breakdown
GET /deployers/:address Deployer profile
GET /deployers/:address/tokens Deployer's tokens
GET /wallets/:address Wallet profile
GET /watchlists/:userId User watchlist
POST /watchlists/:userId/items Add to watchlist
GET /health Service health check

🤝 Contributing

Contributions are welcome! Please read the contribution guidelines before submitting a PR.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'feat: add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Built for the DecentralChain ecosystem

⭐ Star this repo if you find it useful!

About

🔎 Real-time token intelligence for DecentralChain — Telegram bot with risk scoring, deployer profiling, whale tracking, and alpha detection. 9 microservices, TypeScript monorepo.

decentralchain.io

Topics

redis microservices typescript crypto telegram-bot risk-analysis nextjs blockchain monorepo telegraf pnpm fastify prisma defi bullmq token-scanner telegram-mini-app token-analysis whale-tracking decentralchain

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages