Claude Bitcoin Trader

Get Rich or Vibe Tryin'

An automated Bitcoin trading bot supporting Coinbase and Kraken exchanges with multi-indicator confluence strategy, AI-powered trade review, comprehensive safety systems, and paper trading mode.

Works with any trading pair (BTC-USD, BTC-EUR, ETH-USD, etc.).

Features

• Multi-Exchange: Supports Coinbase and Kraken with unified interface
• Multi-Indicator Strategy: Combines RSI, MACD, Bollinger Bands, EMA crossover, and ATR
• Multi-Agent AI Review: 3 reviewers (Pro/Neutral/Opposing) + judge for trade decisions
• Hourly Market Analysis: AI-powered analysis during volatile conditions
• Multi-Timeframe Confirmation: Daily + 4-hour trend alignment before trading
• Market Regime Adaptation: Fear & Greed Index, volatility, and trend-aware adjustments
• Whale Detection: Boosts signal confidence on high-volume institutional activity
• Trade Cooldown: Prevents rapid consecutive trades (falling knife protection)
• Live Dashboard: Real-time web dashboard with charts, signals, and trade history
• Safety Systems: Kill switch, circuit breaker, loss limits, order validation
• Paper Trading: Test strategies with virtual money using real market data
• Cramer Mode: Run inverse strategy alongside normal trading for performance comparison
• Telegram Notifications: Real-time alerts for trades, errors, and daily summaries
• State Persistence: SQLite database for trade history and recovery

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env with your credentials

3. Get Exchange API Keys

Coinbase

1. Go to https://portal.cdp.coinbase.com/
2. Create an API key with View and Trade permissions
3. Download the JSON key file or copy the key and secret to your .env file

Kraken

1. Go to https://www.kraken.com/u/security/api
2. Create an API key with Query Funds and Create & Modify Orders permissions
3. Copy the key and secret (base64-encoded) to your .env file

4. Set Up Telegram (Optional)

1. Message @BotFather on Telegram
2. Create a new bot and copy the token
3. Message @userinfobot to get your chat_id
4. Add both to your .env file

5. Run in Paper Mode

python -m src.main

The bot starts in paper trading mode by default. Monitor the logs to see how it performs.

Configuration

Edit .env to customize. See .env.example for all options with documentation.

Core Settings

| Variable | Default | Description | |----------|---------|-------------| | EXCHANGE | coinbase | coinbase or kraken | | TRADING_PAIR | BTC-USD | Trading pair (e.g., BTC-EUR, ETH-USD) | | TRADING_MODE | paper | paper or live | | POSITION_SIZE_PERCENT | 40 | Max position as % of portfolio | | SIGNAL_THRESHOLD | 60 | Minimum score to trade (0-100) | | CHECK_INTERVAL_SECONDS | 60 | Seconds between checks |

Risk Management

| Variable | Default | Description | |----------|---------|-------------| | MAX_DAILY_LOSS_PERCENT | 10 | Stop trading after this daily loss | | MAX_HOURLY_LOSS_PERCENT | 3 | Pause for 1 hour after this loss | | MAX_POSITION_PERCENT | 80 | Maximum position size allowed | | STOP_LOSS_ATR_MULTIPLIER | 1.5 | Stop loss distance (ATR multiples) | | TAKE_PROFIT_ATR_MULTIPLIER | 2.0 | Take profit distance (ATR multiples) |

Multi-Agent AI Trade Review (Optional)

Uses 3 reviewer agents with different stances (Pro, Neutral, Opposing) plus a judge for final decision.

| Variable | Default | Description | |----------|---------|-------------| | AI_REVIEW_ENABLED | false | Enable multi-agent AI review via OpenRouter | | OPENROUTER_API_KEY | - | API key from openrouter.ai | | REVIEWER_MODEL_1 | x-ai/grok-4-fast | First reviewer model | | REVIEWER_MODEL_2 | qwen/qwen3-next-80b-a3b-instruct | Second reviewer model | | REVIEWER_MODEL_3 | google/gemini-2.5-flash | Third reviewer model | | JUDGE_MODEL | deepseek/deepseek-chat-v3.1 | Judge model for final decision | | VETO_ACTION | info | skip, reduce, delay, or info | | AI_REVIEW_ALL | false | Review ALL decisions (debug mode) | | AI_FAILURE_MODE_BUY | safe | AI failure behavior for buys: safe (skip) or open (proceed) | | AI_FAILURE_MODE_SELL | open | AI failure behavior for sells: safe (skip) or open (proceed) | | AI_RECOMMENDATION_TTL_MINUTES | 20 | How long AI recs influence thresholds | | AI_MAX_TOKENS | 4000 | Max tokens for AI responses |

AI Recommendations: When the judge issues "accumulate", "reduce", or "wait" recommendations, they influence signal thresholds for AI_RECOMMENDATION_TTL_MINUTES. Effect decays linearly to zero over this period.

Hourly Market Analysis (Optional)

AI-powered market analysis with online research. Runs:

• Hourly during high/extreme volatility
• Once when volatility returns to normal (post-volatility analysis)

Uses the same multi-agent system as trade reviews (3 reviewers with bullish/neutral/bearish stances + judge). Fetches real-time data from CryptoCompare (news) and Blockchain.info (on-chain metrics). AI models can also search the web for additional context.

| Variable | Default | Description | |----------|---------|-------------| | HOURLY_ANALYSIS_ENABLED | true | Enable hourly AI analysis (uses reviewer models) | | MARKET_RESEARCH_ENABLED | true | Fetch news and on-chain data from free APIs | | AI_WEB_SEARCH_ENABLED | true | Allow AI to search web during analysis | | MARKET_RESEARCH_CACHE_MINUTES | 15 | Cache duration for research data |

Trading Strategy

The bot uses a confluence scoring system that combines multiple indicators with graduated signals (v1.7.0+):

| Indicator | Weight | Graduated Signal Range | |-----------|--------|------------------------| | RSI (14) | 25% | Dead zone 45-55, scaled ±0.3 to ±1.0 outside | | MACD (12/26/9) | 25% | Crossover + histogram momentum | | Bollinger Bands (20, 2σ) | 20% | %B based, dead zone 0.35-0.65 | | EMA Crossover (9/21) | 15% | Position + momentum, dead zone <0.3% gap | | Volume | 15% | Confirmation boost/penalty | | Trend Filter | - | Counter-trend penalty |

Trade when score ≥ threshold (default 60) or ≤ -threshold for sells

Signal Breakdown Example

Signal Score: 72/100
  📈 RSI: +18      (RSI at 38, moderate buy zone)
  📈 MACD: +15     (bullish crossover + histogram)
  📈 Bollinger: +12 (%B at 0.25, lower zone)
  📈 EMA: +10      (fast above slow, gap widening)
  📈 Volume: +7    (1.6x average volume boost)
  ➖ Trend Filter: 0

Market Protection Layers

The bot uses multiple complementary layers to protect against poor entries during extreme market conditions. These layers work together to provide defense-in-depth without being overly restrictive.

Fear & Greed Index Integration

The bot fetches the Bitcoin Fear & Greed Index every 15 minutes and applies it across five protection layers:

Categories: Extreme Fear (0-25), Fear (25-45), Neutral (45-55), Greed (55-75), Extreme Greed (75-100)

Protection Layer 1: Regime Threshold Adjustments

Modifies the score threshold required to trigger trades based on market sentiment and trend alignment:

• Extreme Fear + Bearish Trend + Buy Signal: threshold_mult: 0.0 - Neutralizes threshold reduction (fear justified, don't catch falling knife)
• Extreme Fear + Bullish Trend + Buy Signal: threshold_mult: 1.2 - Amplifies threshold reduction (contrarian opportunity)
• Extreme Greed + Bullish Trend + Sell Signal: threshold_mult: 1.5 - Amplifies threshold boost (sell into euphoria)

Default impact at scale=1.0: threshold adjusts ±10-15 points

Protection Layer 2: Regime Position Sizing

Adjusts position size based on market conditions:

• Extreme Fear + Bearish Trend + Buy: 30% position reduction (don't catch knife)
• Extreme Fear + Bullish Trend + Buy: 15% position increase (contrarian opportunity)
• Extreme Greed + Bullish Trend + Sell: 20% position increase (sell into strength)

Protection Layer 3: Extreme Fear MTF Override

When daily and 4H timeframes disagree during extreme fear, applies full counter-penalty instead of half:

• Without extreme fear: Daily disagrees with 4H → half penalty (-10 points)
• With extreme fear: Daily disagrees with 4H → full penalty (-20 points)

This prevents 4H neutral signals from neutralizing bearish daily trends during panic conditions.

Protection Layer 4: Dual-Extreme Blocking

Completely blocks buy orders when BOTH conditions exist:

• Sentiment = Extreme Fear (≤24/100)
• Volatility = Extreme (ATR-based)

These dual-extreme conditions create unfavorable risk/reward scenarios for new entries.

Protection Layer 5: Extreme Volatility Stop Widening

Widens stop losses during extreme volatility to prevent whipsaw exits:

• Normal volatility: 1.5x ATR stop distance
• Extreme volatility: 2.0x ATR stop distance

Prevents being stopped out by normal price fluctuations during high volatility.

Tuning Guide

Trade Frequency

Target trades/month depends on market conditions and your risk tolerance:

| Profile | Threshold | Expected Trades | Notes | |---------|-----------|-----------------|-------| | Conservative | 70 | 5-15/month | Fewer but higher conviction | | Moderate | 60 | 20-50/month | Balanced (default) | | Aggressive | 50 | 50-100/month | More signals, more noise |

Indicator Tuning

RSI (Momentum)

• RSI_OVERSOLD=35 / RSI_OVERBOUGHT=65 - Default thresholds
• Tighter (40/60): More signals, earlier entries
• Wider (30/70): Fewer signals, wait for extremes

EMA (Trend)

• EMA_FAST=9 / EMA_SLOW=21 - Default periods
• Shorter (5/13): More responsive, more whipsaws
• Longer (12/26): Smoother, slower to react

**Bollinger Bands (