WebPayy - Secure Custodial Telegram Wallet Bot

WebPayy is a secure, custodial cryptocurrency wallet bot for Telegram. It features a sleek user interface, advanced asset management, and robust security protocols. Built with Fastify, Prisma, BullMQ, and viem.

Features

💻 User Interface

• Clean Aesthetic: A professional, monochrome interface designed for clarity and ease of use.
• Interactive Menus: Persistent, easy-to-navigate keyboards for quick access to all features.
• Smart Feedback: Real-time status updates with clear visual indicators (🟢, 🔴, 🌑).

🔐 Advanced Security

• Self-Destruct Keys: Private keys sent in chat are automatically deleted after 5 seconds to prevent leakage.
• AES-256 Encryption: Keys are encrypted at rest using industry-standard AES-256-CBC.
• Status Monitoring: Track wallet health (ACTIVE, FROZEN, COMPROMISED) in real-time.

💰 Asset Management

• Multi-Wallet Support: Connect and manage unlimited wallets under one account.
• Real-Time Balances: Instantly check ETH and ERC20 token balances across all connected wallets.
• Custom Token Scanner: Check balances for ANY ERC20 token by simply pasting its contract address.

⚡ Transaction Engine

• Async Processing: High-performance payment queue powered by BullMQ and Redis.
• Gas Optimization: Smart gas estimation and pre-flight checks to prevent failed transactions.
• Multi-Network Ready: Seamlessly switch between Ethereum Mainnet and Sepolia Testnet.

📱 Social Features

• Contact Book: Save friends' addresses with custom aliases for quick payments.
• Transaction History: View detailed logs of all incoming and outgoing transfers.
• Notifications: Instant alerts for payments, deposits, and security events.

Architecture

High-Level System Overview

graph TD
    User((User)) <--> Bot[Telegram Bot]
    Bot <--> API[Fastify API Server]
    API <--> DB[(PostgreSQL)]
    API <--> Redis[(Redis / BullMQ)]
    Redis <--> Worker[Payment Worker]
    Worker <--> Chain[Ethereum Blockchain]
    Worker --> Bot

Loading

Payment Flow (Async)

sequenceDiagram
    participant U as User
    participant B as Telegram Bot
    participant A as API Server
    participant Q as BullMQ (Redis)
    participant W as Payment Worker
    participant C as Blockchain (Viem)

    U->>B: /send
    B->>U: Ask for details (Recipient, Amount)
    U->>B: Provide details
    B->>A: POST /api/payments/send
    A->>A: Validate & Check Balance
    A->>Q: Add Job: processPayment
    A-->>B: 202 Accepted (Payment ID)
    B-->>U: "Payment queued..."
    
    Q->>W: Pick up Job
    W->>W: Decrypt Private Key
    W->>C: Send Transaction
    C-->>W: Transaction Hash
    W->>C: Wait for Confirmation
    C-->>W: Success/Failure
    W->>A: Update Status in DB
    W->>B: Trigger Notification
    B->>U: "🟢 Transaction Confirmed"

Loading

Wallet Connection Flow

flowchart TD
    Start(["User starts /connect_wallet"]) --> Input["User provides Address & Private Key"]
    Input --> Validate{"Valid Address & Key?"}
    Validate -- No --> Error["Show Error Message"]
    Validate -- Yes --> Encrypt["Encrypt Private Key"]
    Encrypt --> Save["Save to DB"]
    Save --> Delete["🗑️ Auto-Delete Key Message (5s)"]
    Delete --> Notify["Send Confirmation"]
    Notify --> End(["Wallet Connected"])
    Error --> Input

Loading

Tech Stack

Layer	Technology
Runtime	Node.js >= 20
Framework	Fastify
Database	PostgreSQL + Prisma ORM
Queue	BullMQ + Redis
Blockchain	viem
Validation	Zod
Logging	Pino
Testing	Vitest
Documentation	Swagger / OpenAPI

Getting Started

Prerequisites

• Node.js: v20 or higher
• PostgreSQL: v14 or higher
• Redis: v6 or higher
• Telegram Bot Token: Obtain from @BotFather

Installation

# 1. Clone & Install
git clone https://github.com/jerrygeorge360/webpayybot.git
cd webpayybot
npm install

# 2. Environment Setup
cp .env.example .env
# Edit .env with your credentials (DB URL, Bot Token, etc.)

# 3. Database Initialization
npm run db:generate
npm run db:push

> **Note**: This project uses **Prisma 7**. Database connection is managed via `prisma.config.ts`.

Running the Application

For detailed production deployment instructions using Docker, please refer to the Deployment Guide.

🧪 Testnet Mode (Sepolia)

Run the bot in test mode using the dedicated test environment configuration (.env.test).

npm run dev:test

🚀 Production Mode (Mainnet)

Run the bot connected to the Ethereum Mainnet.

# Run all services concurrently
npm run dev:all

# Or run separately:
npm run dev         # API Server
npm run dev:worker  # Payment Worker
npm run dev:bot     # Telegram Bot

Testing

The project includes a comprehensive test suite with 82 tests covering unit and integration scenarios.

# Run all tests
npm test

# Run tests with UI
npx vitest --ui

# Check coverage
npx vitest run --coverage

API Documentation

The API is fully documented using Swagger. You can access the interactive documentation at: http://localhost:3000/docs

All API requests (except user creation) require the x-user-id header for authentication. You can set this in the Swagger UI by clicking the Authorize button.

API Endpoints

Category	Method	Endpoint	Description
Users	POST	/api/users	Register a new user
	GET	/api/users/me	Get current user profile
Wallets	POST	/api/wallets/connect	Connect a custodial wallet
	GET	/api/wallets	List all connected wallets
	PATCH	/api/wallets/:id/status	Update wallet status
Payments	POST	/api/payments/send	Queue a payment (ETH/ERC20/Custom)
	GET	/api/payments/:id/status	Check job status
Contacts	POST	/api/contacts	Add a new contact
	GET	/api/contacts	List saved contacts

Telegram Commands

Command	Action
/start	Initialize the bot and see the dashboard
/connect_wallet	Securely add a new wallet (Auto-delete keys)
/send	Start the payment flow (ETH, Tokens, Custom)
/list_wallets	View portfolio and wallet status
/transactions	View recent transaction history
/add_contact	Save a new contact
/more	Access advanced options (Balances, Custom Tokens)

📝 License

ISC

👤 Author

Jerry George

• GitHub: @jerrygeorge360