Telegram Payment Manager Bot

A Python Telegram bot that acts as a payment manager for freelancers and SMEs in France, helping with invoice creation and automated URSSAF payments.

Features

• AI-powered conversational interface using Mistral AI
• Virtual IBAN creation for each user
• Crypto wallet generation for payment management
• French regulation compliant invoice generation
• Automated 22% URSSAF payment via x402 protocol
• Staking integration for EURC/USDC on Coinbase

Architecture

The bot consists of several integrated components:

1. Telegram bot interface
2. AI agent with Mistral API
3. Virtual IBAN management
4. Crypto wallet management
5. Invoice generation system
6. Payment automation with staking

Setup

Prerequisites

• Python 3.8 or higher
• Telegram Bot Token (from @BotFather on Telegram)
• Mistral API key (from Mistral AI platform)
• (Optional) Coinbase API keys for production use

Installation

1. Clone or download this repository

2. Install dependencies:

   pip install -r requirements.txt
   

   Note: On Windows, you may need to use py -m pip install -r requirements.txt

3. Copy .env.example to .env and configure your API keys:

   TELEGRAM_BOT_TOKEN=your_bot_token
   MISTRAL_API_KEY=your_mistral_api_key
   

Testing

Run the setup test to verify everything works:

py test_setup.py

or on Windows:

run_test.bat

Running the Bot

To run just the bot:

py start_bot.py

To run the bot with the scheduler for automated tasks:

py run_bot.py

Bot Commands

• /start - Start the bot and create your accounts
• /help - Get help with creating invoices
• /create_invoice - Start the invoice creation process
• /my_wallets - View your payment methods
• /my_invoices - View all your invoices
• /account_status - Check your account status

Workflow

1. User creates an invoice through the bot
2. Client pays to the virtual IBAN
3. System automatically:
   • Records the payment
   • Calculates 22% for URSSAF
   • Converts to stablecoin (EURC/USDC)
   • Stakes the funds using x402 protocol
4. When payment is due to URSSAF:
   • System unstakes funds
   • Transfers to URSSAF account

Testing

Run setup test to verify everything works:

py test_setup.py

or on Windows:

run_test.bat

Mock Data Testing

Test the mock data functionality:

py test_mock_data.py

Bot Demo

Run a demo of the complete bot workflow:

py demo_bot.py

Configuration

For production use, configure these additional variables in .env:

• IBAN_PROVIDER_API_KEY - Your virtual IBAN provider API
• COINBASE_API_KEY & COINBASE_API_SECRET - Coinbase integration
• ETHEREUM_RPC_URL - Ethereum node for blockchain operations
• URSSAF_CRYPTO_ADDRESS - URSSAF wallet address

Mock Data Mode

The bot automatically uses mock data when API keys are not configured:

• No API keys required for initial testing
• Generates realistic but fake IBANs, wallets, and transactions
• Simulates the complete payment and URSSAF workflow
• Perfect for development and demonstration

To switch to production:

1. Configure your real API keys in .env
2. Restart the bot
3. The bot will automatically use real APIs

Structure

src/
├── bot/            # Telegram bot handlers
├── database/       # Database models and operations
├── services/       # Business logic (AI, payments, wallets, etc.)
├── scheduler/      # Automated tasks
└── utils/          # Utility functions