https://github.com/gavino1730/cryptiq
Cryptiq is an AI-powered Telegram bot that helps you track your crypto portfolio, set price alerts, view real-time market data, and receive personalized insights.
https://github.com/gavino1730/cryptiq
ai bot coingecko-api crypto cryptocurrency finance openai portfoliotracker privacy python telegrambot
Last synced: 2 months ago
JSON representation
Cryptiq is an AI-powered Telegram bot that helps you track your crypto portfolio, set price alerts, view real-time market data, and receive personalized insights.
- Host: GitHub
- URL: https://github.com/gavino1730/cryptiq
- Owner: Gavino1730
- License: mit
- Created: 2025-06-12T04:39:56.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-12T07:28:36.000Z (about 1 year ago)
- Last Synced: 2025-06-12T08:23:26.649Z (about 1 year ago)
- Topics: ai, bot, coingecko-api, crypto, cryptocurrency, finance, openai, portfoliotracker, privacy, python, telegrambot
- Language: Python
- Homepage:
- Size: 51.8 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Cryptiq – AI Crypto Portfolio Telegram Bot
[](LICENSE)
[](https://www.python.org/downloads/)
[]()
[](https://t.me/yourbotusername)
[](CONTRIBUTING.md)
**Track your crypto portfolio with AI-powered insights directly in Telegram**
[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Contributing](#contributing) • [License](#license)
---
## 🚧 Development Status
**Cryptiq is in early development (v0.1.0).** This bot is experimental and under active development. Features may change, and bugs are expected. Use at your own risk.
---
## ⚠️ Legal Disclaimer
**Cryptiq does NOT provide financial, investment, or trading advice.** All information and analysis provided by this bot is for informational and educational purposes only. You are solely responsible for your investment decisions. The developers and maintainers of Cryptiq are NOT liable for any losses, damages, or consequences resulting from the use of this bot.
---
## 📖 What is Cryptiq?
Cryptiq is a powerful Telegram bot that helps you:
- 📊 Track your cryptocurrency portfolio in real-time
- 💰 Monitor your total portfolio value and individual holdings
- 🔔 Set price alerts for your favorite coins
- 📰 Get the latest crypto news and market updates
- 🤖 Receive AI-powered market insights and analysis
- 🌍 Use the bot in multiple languages
- 🔒 Keep your data private and secure
All from the convenience of your Telegram app!
---
## ✨ Features
### Core Features
- **Portfolio Management** - Track multiple cryptocurrencies and your total portfolio value
- **Real-Time Prices** - Get up-to-date price data from CoinGecko API
- **Price Alerts** - Set custom alerts for specific price targets
- **Performance Tracking** - Monitor portfolio changes over time with charts
- **Bank Balance** - Track your fiat currency alongside crypto holdings
- **Trading Strategy** - Document your investment approach
### AI-Powered Features
- **Market Analysis** - Get AI-generated insights about market trends
- **Smart Responses** - Natural language interaction with the bot
- **Personalized Recommendations** - Tailored to your portfolio and strategy
### User Experience
- **Multi-Language Support** - Available in multiple languages
- **Interactive Menus** - Easy-to-use button-based navigation
- **Portfolio Visualizations** - Pie charts and line graphs
- **Privacy-First** - Your data stays on your server, never shared
- **Easy Setup** - Simple onboarding process
---
## 🚀 Installation
### Prerequisites
- **Python 3.8 or higher** - [Download here](https://www.python.org/downloads/)
- **Telegram Account** - To create and use the bot
- **OpenAI API Key** - For AI features [Get here](https://platform.openai.com/account/api-keys)
- **Git** (optional) - [Download here](https://git-scm.com/downloads/)
### Step 1: Clone the Repository
```bash
git clone https://github.com/yourusername/cryptiq.git
cd cryptiq
```
Or download the ZIP file from GitHub and extract it.
### Step 2: Install Dependencies
Create a virtual environment (recommended):
```bash
# Create virtual environment
python -m venv venv
# Activate it
# On Windows:
venv\Scripts\activate
# On Mac/Linux:
source venv/bin/activate
# Install requirements
pip install -r requirements.txt
```
### Step 3: Configure Environment Variables
1. Copy the example environment file:
```bash
# On Windows:
copy .env.example .env
# On Mac/Linux:
cp .env.example .env
```
2. Edit `.env` and add your API keys:
- **TELEGRAM_TOKEN** - Get from [@BotFather](https://t.me/botfather) on Telegram
1. Message @BotFather and type `/newbot`
2. Follow the prompts to create your bot
3. Copy the token BotFather gives you
- **OPENAI_API_KEY** - Get from [OpenAI Platform](https://platform.openai.com/account/api-keys)
1. Create an OpenAI account
2. Go to API keys section
3. Create a new API key
4. Copy the key (you won't see it again!)
Your `.env` file should look like:
```env
TELEGRAM_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
OPENAI_API_KEY=sk-proj-abcdefghijklmnopqrstuvwxyz
```
### Step 4: Run the Bot
```bash
python main.py
```
You should see: `Cryptiq bot is running...`
---
## 📱 Usage
### Getting Started with Your Bot
1. **Find your bot on Telegram**
- Search for the bot name you chose with BotFather
- Or click the link BotFather provided
2. **Start interacting**
- Type `/start` to begin
- Follow the onboarding process
- Set up your portfolio
### Available Commands
| Command | Description |
|---------|-------------|
| `/start` | Start the bot or reset your profile |
| `/menu` | Show main menu with interactive buttons |
| `/portfolio` | View your current portfolio and performance |
| `/setbank` | Set or update your bank balance |
| `/setholdings` | Add or update crypto holdings |
| `/setstrategy` | Define your trading strategy |
| `/setalert` | Create price alerts for specific coins |
| `/news` | Get latest cryptocurrency news |
| `/settings` | Configure bot settings |
| `/language` | Change interface language |
| `/deleteprofile` | Delete all your data from the bot |
| `/help` | Show all available commands |
### Example Workflow
```
You: /start
Bot: Welcome to Cryptiq! Let's set up your portfolio...
You: /setbank 10000
Bot: Bank balance set to $10,000
You: /setholdings BTC 0.5
Bot: Holdings updated: 0.5 BTC
You: /portfolio
Bot: [Shows your portfolio with charts and current values]
You: /setalert BTC 50000
Bot: Alert set! I'll notify you when BTC reaches $50,000
```
---
## 🏗️ Project Structure
```
cryptiq/
├── main.py # Main entry point, bot initialization
├── handlers.py # Command and message handlers
├── utils.py # Utility functions (API calls, charts, etc.)
├── database.py # Data storage and retrieval
├── keyboards.py # Telegram keyboard layouts
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
├── .gitignore # Git ignore rules
├── README.md # This file
├── LICENSE # MIT License
├── CONTRIBUTING.md # Contribution guidelines
├── CODE_OF_CONDUCT.md # Community guidelines
├── PRIVACY_POLICY.md # Privacy policy
└── CHANGELOG.md # Version history
```
---
## 🛠️ Technology Stack
- **Python 3.8+** - Core programming language
- **python-telegram-bot** - Telegram Bot API wrapper
- **OpenAI API** - AI-powered responses and analysis
- **CoinGecko API** - Real-time cryptocurrency data
- **matplotlib** - Chart generation
- **requests** - HTTP requests
- **python-dotenv** - Environment variable management
- **pytz** - Timezone handling
---
## 🔒 Security & Privacy
- **API Keys**: Stored in `.env` file (never commit this file!)
- **User Data**: Stored locally in JSON files on your server
- **Data Sharing**: Your data is NEVER shared with third parties
- **Data Deletion**: Use `/deleteprofile` to permanently delete your data
- **Open Source**: Full transparency - inspect the code yourself
See [PRIVACY_POLICY.md](PRIVACY_POLICY.md) for complete details.
---
## 🤝 Contributing
We love contributions! Whether it's:
- 🐛 Bug reports
- 💡 Feature requests
- 📝 Documentation improvements
- 🔧 Code contributions
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
---
## 🗺️ Roadmap
### Version 0.2.0 (Planned)
- [ ] Unit tests and CI/CD pipeline
- [ ] Exchange API integration (Binance, Coinbase)
- [ ] Automated trading capabilities
- [ ] Advanced portfolio analytics
- [ ] Historical performance tracking
### Version 0.3.0 (Future)
- [ ] Price prediction models
- [ ] Trade signal generation
- [ ] Multi-exchange support
- [ ] DeFi protocol integration
- [ ] NFT portfolio tracking
### Long-term Vision
- [ ] Web dashboard
- [ ] Mobile apps (iOS & Android)
- [ ] Desktop application
- [ ] Community features & leaderboards
- [ ] Premium subscription tier
See [CHANGELOG.md](CHANGELOG.md) for completed features and version history.
---
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## ⚠️ Disclaimer
**IMPORTANT**: Cryptiq is provided "as is" without warranty of any kind. This bot:
- Does NOT provide financial advice
- Should NOT be used as the sole basis for investment decisions
- May contain bugs or inaccuracies
- Is NOT responsible for any financial losses
Always do your own research (DYOR) and consult with licensed financial advisors before making investment decisions.
---
## 🆘 Support
### Troubleshooting
**Bot won't start?**
- Check Python version: `python --version` (should be 3.8+)
- Verify all dependencies are installed
- Confirm `.env` file exists and contains valid API keys
- Check terminal for error messages
**Bot not responding in Telegram?**
- Ensure the bot is running (`Cryptiq bot is running...` message)
- Verify your Telegram token is correct
- Check if BotFather shows your bot as active
- Look for errors in terminal output
**API errors?**
- Verify OpenAI API key is valid and has credits
- Check CoinGecko API rate limits
- Ensure internet connection is stable
**Still need help?**
- [Open an issue](https://github.com/yourusername/cryptiq/issues)
- Check existing issues for solutions
- Join our community discussions
---
## 🙏 Acknowledgments
- [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) - Excellent Telegram Bot framework
- [CoinGecko](https://www.coingecko.com/) - Free cryptocurrency API
- [OpenAI](https://openai.com/) - Powering AI features
- All contributors who help improve Cryptiq
---
## 📧 Contact
- **Issues**: [GitHub Issues](https://github.com/yourusername/cryptiq/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/cryptiq/discussions)
- **Email**: your-email@example.com
---
**⭐ Star this repo if you find it useful!**
Made with ❤️ by [Gavin Galan](https://github.com/yourusername)
[Report Bug](https://github.com/yourusername/cryptiq/issues) • [Request Feature](https://github.com/yourusername/cryptiq/issues) • [View Roadmap](https://github.com/yourusername/cryptiq/projects)