Telegram Bubblemap Bot

A powerful Telegram bot that integrates with the BubbleMaps API to deliver token insights, distribution analytics, and interactive bubblemaps — all directly within Telegram.

---

✨ Features

• 🔍 Check token details for any supported token address
• 🫧 Generate bubblemaps for supported tokens across multiple chains
• 📊 Inline token distribution breakdowns with visual data
• 🧾 Fetch holder/address-specific insights for a token
• 📈 CoinGecko integration for market data and metadata
• 📦 Redis-compatible Valkey caching for performance and response optimization
• 🌐 Webhook or polling support for Telegram integration
• 🔗 Multi-chain support including: eth, bsc, ftm, avax, cro, arbi, poly, base, sol, and sonic

---

📦 Installation

1. Clone the Repository

git clone git@github.com:Atlas-Projects/BubbleMapsBot.git
cd BubbleMapsBot/

2. Create a Virtual Environment (Optional)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt
playwright install chromium --with-deps --only-shell

---

⚙️ Configuration

1. Copy the sample config:

cp sample_config.yaml config.yaml

2. Edit config.yaml to include your Telegram Bot Token, supported features, and API details.

Refer to the Configuration File Documentation for a complete explanation of each parameter.

---

🚀 Usage

Run in Polling Mode (default)

python3 -OO -m bubblemaps_bot   # On Windows: python -OO -m bubblemaps_bot

Ensure webhook: false in your config.yaml.

Run in Webhook Mode

Ensure you have:

• A public HTTPS server
• Proper webhook_url, webhook_port, and SSL cert path set

Then:

python3 -OO -m bubblemaps_bot   # On Windows: python -OO -m bubblemaps_bot

---

🧪 Example Commands

Here are some of the capabilities your users can try within Telegram:

• /check <address> – View details about a token
• /mapshot <address> – Get an interactive Bubblemap
• /meta <token_address> or /meta <chain> <token_address> – Get metadata about a specific token
• /distribution <token> – Get distribution information about a token
• /coin <address> – Price and market data from CoinGecko
• /address <chain> <token_address> <address> – Fetch details of a specific address for a token
• /clear – Clear the Valkey cache

---

🎥 Demonstrations

• Deployment Video: Learn how to deploy the bot.
  Watch on YouTube

• Bot Functioning Showcase: See the bot in action.
  Watch on YouTube

---

🧩 Supported Chains

• Ethereum (eth)
• Binance Smart Chain (bsc)
• Fantom (ftm)
• Avalanche (avax)
• Cronos (cro)
• Arbitrum (arbi)
• Polygon (poly)
• Base (base)
• Solana (sol)
• Sonic (sonic)

---

🔄 Updating

To update the project:

git pull origin main
pip install -r requirements.txt --upgrade

---

🐍 Python Dependencies

This project uses the following core Python packages:

Package	Description
python-telegram-bot	Official Telegram Bot API framework – used to handle messaging, commands, and updates.
SQLAlchemy	Python SQL toolkit and ORM used for database interactions.
aiohttp	Asynchronous HTTP client/server for non-blocking requests, ideal for webhook mode and API calls.
aiosqlite	Async interface to SQLite – useful for lightweight, non-blocking storage.
PyYAML	Used for reading and parsing the config.yaml configuration file.
valkey	Valkey/Redis-compatible client for high-performance in-memory caching and key-value store access.
setuptools	Helps with packaging and distributing the application, required by some dependencies.
playwright	Headless browser automation – used for capturing screenshots or rendering visual elements (if needed).

Full list can be found in requirements.txt

---

📜 License

MIT License. See LICENSE for full details.