Skip to content

xcode4tux/claude-code-framework

BranchesTags

Repository files navigation

📊 Copy Trading Bot — User Guide

AI-powered copy trading that tracks smart money and trades automatically. Built from Samin Yasar's "Claude's New Trading Agent Is Insane!" tutorial.

Table of Contents

  1. Overview
  2. Quick Start
  3. Installation
  4. Desktop Shortcuts
  5. Web Dashboard
  6. API Keys & Data Sources
  7. Trading Modes
  8. Copy Trading Strategies
  9. CLI Commands
  10. Configuration
  11. Troubleshooting
  12. Security & Best Practices

🎯 Overview

The Copy Trading Bot has three levels of operation:

Level Name Description
1 📡 Data Sources Connect to real market data, insider trades, web signals
2 📋 Copy Trading Automatically copy trades from insiders, politicians, top traders
3 🌐 Any Source Monitor Discord, newsletters, or any web page for trade signals

Architecture

┌─────────────────────────────────────────────────────┐
│                  Web Dashboard (port 8420)           │
│   FastAPI + Alpine.js + Chart.js + SSE real-time    │
├─────────────────────────────────────────────────────┤
│  Sources                   │  Execution             │
│  ├─ Market Data (Binance)  │  ├─ Paper Trading      │
│  ├─ Quiver Quant (insider) │  └─ Live Trading       │
│  ├─ FireCrawl (web scrape) │                        │
│  └─ TraderDev (backtest)   │  Portfolio + Approval  │
└─────────────────────────────────────────────────────┘

🚀 Quick Start

# 1. Start the dashboard
cd ~/copy-trading-bot
./scripts/start-web.sh

# 2. Open your browser to http://localhost:8420

# 3. Click "🧪 Demo" to see simulated trades
# 4. Click "▶ Start Bot" to begin monitoring

What happens: The bot checks every 30 minutes for new insider trades, scrapes monitored web pages for signals, and copies trades into your paper trading portfolio (no real money at risk).

📦 Installation

Prerequisites

  • Python 3.11+ and pip
  • Git (optional, for updates)

Setup

# Clone the repository
git clone https://github.com/xcode4tux/copy-trading-bot.git
cd copy-trading-bot

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install
pip install -e .
pip install -r web/requirements.txt

# Configure API keys (optional but recommended)
cp config.example.yaml config.yaml
nano .env  # Add your API keys (see API Keys section)

Verify Installation

source .venv/bin/activate
ctb demo          # Run demo with simulated trades
ctb status        # Show portfolio status

🖥️ Desktop Shortcuts

Three shortcuts are available on your Desktop:

Shortcut Icon Action
Start Copy Trading Bot 🟢 Green play button Launches web server + bot engine + opens dashboard
Dashboard 🔵 Blue grid icon Starts server (or reuses existing) + opens dashboard
Stop Copy Trading Bot 🔴 Red stop button Gracefully shuts down bot + web server

Tip: Double-clicking Start when already running just opens the dashboard — no duplicates.

🌐 Web Dashboard

Open http://localhost:8420 in your browser.

Top Bar

  • Status indicator: Green pulsing dot = bot is running. Gray = idle.
  • ▶ Start Bot: Launches the monitoring loop (checks every 30 min)
  • ⏹ Stop Bot: Gracefully stops the bot
  • ↻ Check Now: Runs one immediate check cycle
  • 🧪 Demo: Injects 3 simulated insider trades for instant results

Live Ticker Bar

A scrolling bar across the top shows real-time prices for all watched assets with 24-hour percentage changes — green for up, red for down. Auto-refreshes every 30 seconds.

Tabs

📊 Positions

Shows your current portfolio holdings with entry price, current price, P&L, and unrealized P&L percentage. Empty state shows when no positions are open.

✅ Approvals

When approval mode is on (default), every trade requires your sign-off before execution. Each pending trade shows:

  • Ticker and direction (BUY/SELL)
  • Notional value
  • Who it's copied from (trader name or signal source)
  • Approve/Reject buttons

📈 Markets

  • Market Overview: Global crypto market cap, BTC dominance, 24h volume
  • Live Price Grid: Real-time prices with 24h changes for all watched assets
  • 🔥 Trending: Top 8 trending coins on CoinGecko

📡 Signal Feed

Live feed of trading signals detected from monitored sources (FireCrawl web scraping, Quiver Quant insider data). Each signal shows the ticker, action, source, and raw text context.

⚙ Settings

Configure the bot at runtime:

  • Check Interval: How often to scan for new trades (5-240 minutes)
  • Trading Mode: Paper Trading (safe) or Live Trading (real money)
  • Approval Required: Yes (review every trade) or No (auto-execute)
  • Tracked Traders: Comma-separated list of trader names to copy
  • Monitored URLs: Web pages to scrape for trading signals (one per line)

Equity Chart

Interactive line chart showing portfolio value over time. Updates in real-time via SSE. Shows the full history of your portfolio's performance.

🔑 API Keys & Data Sources

Free (No Key Required)

Source What It Provides Status
Binance Public API Live crypto prices, 24h stats ✅ Active
CoinGecko API Global market cap, trending coins ✅ Active
Paper Trading Simulated stock prices with realistic drift ✅ Active

Optional (Requires API Key)

FireCrawl — Web Scraping & Monitoring

# Get key: https://firecrawl.link/samin-yasar (free tier available)
echo 'FIRECRAWL_API_KEY=fc-your-key-here' >> .env

Enables monitoring any web page for trading signals — Discord channels, newsletters, TradingView ideas.

TraderDev — Backtesting & Strategy Optimization

Already configured via MCP. Use the login URL to authenticate:

https://mcp-api.trader.dev/login

Provides: strategy search, backtesting, parameter optimization, live alerts.

Quiver Quant — Insider Trading Data

# Get key: https://api.quiverquant.com/mcp-server (starts at $30/month)
echo 'QUIVER_API_KEY=your-key-here' >> .env

Tracks: congressional trades, corporate insider filings, SEC Form 4 data, government contracts.

Co-Invest / Liquid Trade — Live Trade Execution

Sign up at https://coinvest.liquid.trade and add as a Claude Code connector to execute real trades from the bot.

💰 Trading Modes

Paper Trading (Default — Safe)

  • No real money is ever at risk
  • Prices simulated with Ornstein-Uhlenbeck mean-reverting drift
  • Realistic slippage and commission simulation
  • Perfect for testing strategies before going live

Live Trading

  • Requires Co-Invest / Liquid Trade connector
  • Real order execution on stocks, crypto, forex, commodities
  • Always start with small position sizes when going live

⚠️ WARNING: Only trade with money you can afford to lose. Past performance of tracked traders does not guarantee future results. Always do your own research.

📋 Copy Trading Strategies

How Copy Trading Works

  1. Track: The bot monitors specific traders (e.g., "Nancy Pelosi", "Ron Baron") via Quiver Quant
  2. Detect: When a tracked trader makes a new buy, the bot detects it
  3. Filter: Deduplication prevents copying the same trade twice
  4. Size: Position size calculated as % of portfolio (capped at max_position_pct, default 10%)
  5. Approve: If approval mode is on, you review and approve/reject each trade
  6. Execute: Approved trades are executed at market price with simulated slippage

Signal Monitoring (Level 3)

The bot can monitor any web page for trading signals:

  • Discord trading channels
  • Email newsletters (via web archive)
  • TradingView ideas pages
  • Blog posts with trade alerts

How it works: FireCrawl scrapes the page every N minutes, compares with the previous version, and parses new text for buy/sell patterns like:

  • "Buy AAPL at market open"
  • "Going long on TSLA"
  • "Sell all BTC"
  • "Closing our NVDA position"

🖥️ CLI Commands

ctb run         # Start continuous mode (runs until stopped)
ctb check       # Single check cycle (fetch → generate → execute)
ctb status      # Show portfolio and bot status
ctb demo        # Demo with simulated insider trades
ctb markets     # Show watched markets with prices

CLI Options

Flag Description Default
--track NAME Track a trader (repeatable) none
--monitor URL Monitor a URL (repeatable) none
--interval MIN Check interval in minutes 30
--capital AMT Initial capital $10,000
--dry-run Paper trading only true
--approval / --no-approval Require human approval true

Examples

# Track Nancy Pelosi and Ron Baron, check every 15 min
ctb run --track "Nancy Pelosi" --track "Ron Baron" --interval 15 --dry-run

# Monitor a Discord trading channel
ctb run --monitor "https://discord.com/channels/..." --dry-run

# Check once with auto-execution
ctb check --track "Tim Moore" --no-approval --dry-run

⚙️ Configuration

Via Environment Variables (.env)

FIRECRAWL_API_KEY=fc-your-key
QUIVER_API_KEY=your-key
COINVEST_API_KEY=your-key

Via YAML (config.yaml)

portfolio:
  initial_capital: 10000.0
  max_position_pct: 10.0      # Max % per position
  max_positions: 10           # Max concurrent positions
  require_approval: true      # Human-in-the-loop

scheduler:
  check_interval_minutes: 30
  trading_hours_only: true    # Only US market hours (9:30-4:00 ET)

tracked_traders:
  - "Nancy Pelosi"
  - "Ron Baron"
  - "Tim Moore"

monitored_sources:
  - "https://tradingview.com/ideas/"

Via Dashboard

All settings can be changed live from the ⚙ Settings tab — no restart required.

🔧 Troubleshooting

"Dashboard won't open" (port 8420)

# Check if port is in use
fuser 8420/tcp

# Kill the old process and restart
pkill -f "web.server"
~/copy-trading-bot/scripts/start-web.sh

"Start Bot button does nothing"

  • Make sure your API keys are set (at minimum, none are required for basic operation)
  • Open browser DevTools (F12 → Console) and check for red error messages
  • Verify the server is running: curl http://localhost:8420/health
  • Try clicking "🧪 Demo" first — if that works, the bot is functional

"No signals detected"

  • Add tracked traders in Settings or via --track CLI flag
  • Add monitored URLs in Settings or via --monitor CLI flag
  • Run a manual check: click "↻ Check Now" in the dashboard

"Prices not updating"

  • Market data auto-refreshes every 30 seconds
  • Click "↻ Refresh" in the Markets tab to force an update
  • Binance and CoinGecko APIs may be rate-limited — wait 30 seconds

Resetting Everything

pkill -f "web.server"
rm -f ~/copy-trading-bot/.bot.pid ~/copy-trading-bot/.web.pid
~/copy-trading-bot/scripts/start-web.sh

🔒 Security & Best Practices

API Keys

  • Never commit .env to git (it's in .gitignore)
  • Store API keys only in .env or environment variables
  • Rotate keys regularly
  • Use read-only API keys when possible

Trading Safely

  1. Always start with paper trading — test for at least 2-4 weeks
  2. Start small — when going live, use 1-5% of portfolio per trade
  3. Keep approval on — human review catches bad signals
  4. Diversify sources — don't copy just one trader
  5. Set stop-losses — the paper trading engine simulates them, live trading relies on the exchange

Network

  • The dashboard binds to 127.0.0.1 (localhost only) — not accessible from other machines
  • All API calls are local — no data leaves your machine except to data source APIs
  • SSE stream uses local EventSource — no external push services

📚 Further Reading

  • TraderDev MCP: Backtesting and strategy optimization at https://mcp.trader.dev
  • Quiver Quant: Insider trading data at https://api.quiverquant.com
  • FireCrawl: Web scraping at https://firecrawl.dev
  • Liquid Trade: Multi-market trading at https://liquid.trade

🤝 Support

  • Issues: File a bug report on the GitHub repo
  • API questions: Refer to the respective service's documentation
  • Strategy help: Use the TraderDev MCP to search leaderboard strategies for inspiration

Built with ❤️ using FastAPI, Alpine.js, Chart.js, and real market data APIs.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages