mantle-ai-trader/README.md

🤖 Mantle AI Trader

AI-Powered Cryptocurrency Trading Bot with News Sentiment Analysis

Free Open Source Trading Bot • Bybit Integration • Real-time Signals • Backtesting Engine

🏆 Built for Mantle Turing Test Hackathon - $120,000 Prize Pool

---

📋 Table of Contents

• Features
• Demo
• Quick Start
• Installation
• Usage
• API Reference
• Configuration
• Architecture
• Testing
• Contributing
• License

---

🚀 Features

🤖 AI-Powered Trading Signals

Feature	Description
Signal Generation	AI-generated buy/sell signals with confidence scores
Technical Analysis	RSI, MACD, SMA, EMA, Bollinger Bands
Pattern Recognition	Doji, Hammer, Engulfing, Morning Star
Support/Resistance	Automated level detection

📰 Fundamental News Analysis

• Multi-Source Aggregation: CryptoPanic, CoinGecko, CryptoCompare
• Sentiment Scoring: Bullish/Bearish classification (-1 to 1)
• Real-time Updates: Live news feed integration
• Impact Assessment: News importance scoring

📊 Backtesting Engine

• Historical Simulation: Test strategies on past data
• Performance Metrics: Sharpe Ratio, Win Rate, Max Drawdown
• Strategy Optimization: Parameter grid search
• Detailed Reports: Trade-by-trade analysis

💰 Paper Trading (Demo Mode)

• Risk-Free Testing: Practice without real money
• Real Market Prices: Live price simulation
• Portfolio Tracking: P&L monitoring
• Position Management: Stop-loss/Take-profit

🔗 Exchange Integration

• Bybit API: Full spot and futures support
• Testnet Mode: Safe testing environment
• Order Types: Market, Limit, Stop orders
• Position Management: Leverage, margin, risk controls

---

🎬 Demo

📷 View Screenshots

Dashboard Overview

Signal Generation

Paper Trading

---

⚡ Quick Start

# Clone the repository
git clone https://github.com/roman-ryzenadvanced/mantle-ai-trader.git
cd mantle-ai-trader

# Install dependencies
bun install

# Setup database
bun run db:push

# Start the application
bun run dev

Open http://localhost:3000 to access the dashboard.

---

🛠 Installation

Prerequisites

Requirement	Version	Notes
Node.js	18+	or Bun runtime
SQLite	Included	Default database
Bybit API	Optional	For live trading

Step-by-Step Setup

# 1. Clone repository
git clone https://github.com/roman-ryzenadvanced/mantle-ai-trader.git

# 2. Navigate to project
cd mantle-ai-trader

# 3. Install dependencies
bun install

# 4. Configure environment
cp .env.example .env
# Edit .env with your API keys (optional)

# 5. Initialize database
bun run db:push

# 6. Start development server
bun run dev

# 7. (Optional) Start WebSocket service
bun run trading-service

Docker Installation (Coming Soon)

docker-compose up -d

---

📈 Usage

Web Dashboard

Tab	Function
Signals	Generate and view AI trading signals
Positions	Manage open positions and portfolio
Backtest	Run strategy simulations
News	View market news with sentiment

Supported Trading Pairs

• BTCUSDT, ETHUSDT, SOLUSDT, BNBUSDT, XRPUSDT
• And 100+ more via Bybit API

Signal Example

{
  "symbol": "BTCUSDT",
  "action": "BUY",
  "confidence": 0.85,
  "reasoning": "Bullish trend with strong support at $44,000. RSI oversold recovery.",
  "stopLoss": 43500,
  "takeProfit": 46500,
  "technicalScore": 0.78,
  "sentimentScore": 0.65
}

---

🔌 API Reference

Base URL

http://localhost:3000/api/trading

Endpoints

Generate Signal

POST /signals
Content-Type: application/json

{
  "symbol": "BTCUSDT",
  "timeframe": "1h"
}

Get Portfolio

GET /demo?action=portfolio

Place Demo Order

POST /demo
Content-Type: application/json

{
  "action": "place_order",
  "symbol": "BTCUSDT",
  "side": "BUY",
  "quantity": 0.01,
  "type": "MARKET"
}

Run Backtest

POST /backtest
Content-Type: application/json

{
  "symbol": "BTCUSDT",
  "startDate": "2024-01-01",
  "endDate": "2024-06-01",
  "initialCapital": 10000
}

Get News

GET /news?symbol=BTC&limit=20

---

🔧 Configuration

Environment Variables

# Bybit Exchange (Optional)
BYBIT_API_KEY=your_api_key
BYBIT_API_SECRET=your_api_secret
BYBIT_TESTNET=true

# News APIs (Optional)
CRYPTOPANIC_API_KEY=your_key
CRYPTOCOMPARE_API_KEY=your_key

# Vector Database (Optional)
CHROMADB_URL=http://localhost:8000

# Database
DATABASE_URL="file:./prisma/data/mantle-trader.db"

Risk Management Settings

Setting	Default	Description
Risk Level	MODERATE	CONSERVATIVE, MODERATE, AGGRESSIVE
Max Position	$1,000	Maximum position size
Max Leverage	5x	Maximum leverage multiplier
Auto Trading	Disabled	Automatic signal execution

---

📊 Architecture

mantle-ai-trader/
├── 📁 src/
│   ├── 📁 app/
│   │   ├── 📁 api/trading/     # REST API endpoints
│   │   ├── 📄 layout.tsx       # Root layout with SEO
│   │   └── 📄 page.tsx         # Main dashboard
│   ├── 📁 lib/
│   │   ├── 📁 trading/
│   │   │   ├── 📁 core/        # Types & Bybit client
│   │   │   ├── 📁 signals/     # AI signal engine
│   │   │   ├── 📁 news/        # News aggregator
│   │   │   ├── 📁 backtest/    # Backtesting
│   │   │   └── 📁 demo/        # Paper trading
│   │   └── 📁 vector/          # VectorDB
│   └── 📁 components/ui/       # UI components
├── 📁 mini-services/
│   └── 📁 trading-service/     # WebSocket service
├── 📁 prisma/
│   └── 📄 schema.prisma        # Database schema
├── 📁 public/                  # Static assets
└── 📁 tests/                   # Test files

Tech Stack

Category	Technology
Framework	Next.js 16, TypeScript 5
Styling	Tailwind CSS 4, shadcn/ui
Database	Prisma ORM, SQLite
AI/ML	z-ai-web-dev-sdk
Exchange	Bybit API v5
Real-time	Socket.io
Charts	Recharts
State	Zustand, TanStack Query

---

🧪 Testing

# Run all tests
bun test

# Run unit tests
bun test tests/unit/

# Run integration tests
bun test tests/integration/

# Run with coverage
bun test --coverage

Test Coverage

Module	Coverage
Signal Engine	85%
Demo Trader	90%
News Aggregator	75%

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)
3. 💾 Commit your changes (git commit -m 'Add amazing feature')
4. 📤 Push to the branch (git push origin feature/amazing-feature)
5. 🔃 Open a Pull Request

Code of Conduct

• Be respectful and inclusive
• Write clean, documented code
• Add tests for new features
• Update documentation

---

📜 License

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

MIT License - Free to use, modify, and distribute

---

🏆 Mantle Turing Test Hackathon

This project is built for the Mantle Turing Test Hackathon:

Info	Details
Prize Pool	$120,000 cash + $103,000 API credits
Tracks	AI Trading, AI Alpha & Data
Registration	mantle.to/Hackathon
Chat	Telegram

Competition Tracks

• ✅ AI Trading - Trading bots, strategy automation, Bybit API
• ✅ AI Alpha & Data - Onchain analytics, anomaly detection

---

🌟 Star History

---

📞 Support & Community

Platform	Link
GitHub Issues	Report a Bug
Discussions	GitHub Discussions
Telegram	Mantle Hackathon Chat
Twitter	@rommarkdev

---

⭐ Star us on GitHub • 🐛 Report Bug • 💡 Request Feature

Keywords: AI trading bot, cryptocurrency trading, crypto signals, Bybit API, trading automation, sentiment analysis, backtesting, paper trading, Mantle hackathon, open source trading bot, TypeScript, Next.js, algorithmic trading, DeFi, Web3