Harvest

April 22, 2026 · View on GitHub

License: MIT Python 3.10+ Status Built on ARC-Core

Automated crypto trading research platform focused on short-biased multi-timeframe strategies (15m / 1h / 4h) over BTCUSDT and ETHUSDT. Features freshness-gated data (no trading on stale data), 90-day grid-search strategy discovery (~121k combinations per run), blockchain-verified OHLCV, MetaMask wallet CLI, and a production-readiness audit trail.

Why you might read this repo

  • Operational discipline, not hype: pre-trading checks, seed validation, production audit reports, paper-trading gates, data-freshness enforcement.
  • Strategy engine: grid-search finds two best strategies per timeframe; fallback strategies saved automatically.
  • Everything documented: user manual, math primer, TRON integration plan, paper-trading guide, validation reports, CHANGELOG.
  • Safety: 2:1 minimum R/R, profit-locking, conservative 25× leverage cap, refusal to trade on data > 30 days old.

Part of the ARC ecosystem

Harvest is the "heavy-artillery" cousin of BrokeBot and Charm. Emit decisions into the ARC-Core spine for receipt-based trade audit and replay:

Keywords

crypto trading system · multi-timeframe backtest · grid search strategies · quantitative finance python · metamask cli · btc eth trading bot · algorithmic trading · production-grade backtester · data freshness gate · seed validation · blockchain-verified ohlcv

📖 Official docs

Open the rendered official docs → https://garebear99.github.io/Harvest/official/docs_home.html

Also available under docs/official/ in-tree, and through the Pages landing at https://garebear99.github.io/Harvest/.

Cryptocurrency Trading System

Version 2.0+ | Production Ready | December 26, 2024

🚀 Quick Start

# 1. Validate system and ensure data is fresh
python pre_trading_check.py

# 2. Run backtest to verify everything works
python backtest_90_complete.py

# 3. Check system health anytime
python pre_trading_check.py --check-only

That's it! The system will guide you through any needed setup.

📚 Documentation

Start Here

QUICK_START.md - Get started immediately
USER_TESTING_GUIDE.md - Pre-live testing guide
USER_MANUAL.md - Complete system guide

  • What the system does and how it works
  • How to use every feature
  • Troubleshooting guide
  • Command reference
  • FAQ

Paper Trading

docs/PAPER_TRADING_READY.md - Paper trading readiness
docs/PAPER_TRADING_TEST_GUIDE.md - How to run paper trading
docs/WALLET_CONNECT_GUIDE.md - Wallet connection guide

Mathematics

docs/MATHEMATICS.md - Math explained in simple terms

  • Win rate, P&L, position sizing
  • Leverage, risk/reward ratios
  • All indicators explained with real examples
  • Complete trade walkthrough

Future Plans

docs/TRON_INTEGRATION.md - Tron blockchain integration

  • Why Tron? (speed, cost, throughput)
  • Technical architecture
  • Implementation timeline
  • Economic analysis

System Status

COMPREHENSIVE_SYSTEM_REVIEW_DEC26_2024.md - Full system analysis
SEED_VALIDATION_SYSTEM_COMPLETE.md - Seed system completion report
PRODUCTION_READINESS_CHECKLIST.md - Production status checklist
PRODUCTION_AUDIT_REPORT_DEC26_2024.md - Complete audit findings
CHANGELOG.md - Recent improvements

Dec 26, 2024 Updates:

  • ✅ Seed Validation System Complete - 4-layer tracking operational, all confusion eliminated
  • ✅ MetaMask Connection Persistence - Wallet connection now persists through dashboard refreshes
  • ✅ Strategy Configuration Logging - Real SHA-256 seeds displayed (1829669, 5659348, etc.)
  • ✅ Documentation Cleanup - Organized docs, added historical notices to 6 files
  • ✅ Production Audit Complete - Comprehensive code and documentation audit passed

🎯 What This System Does

This is an automated cryptocurrency trading system that:

  • Makes money by predicting when crypto prices will drop (shorting)
  • Trades safely with strict risk management and profit locking
  • Trades multiple timeframes (15-minute, 1-hour, 4-hour) for 3-5+ trades per day
  • Learns and adapts to find the best strategies

Target: 90%+ win rate (9 out of 10 trades profitable)

✅ Key Features

Automated Workflow

  • ✅ Checks data freshness before every trading session
  • ✅ Auto-downloads fresh 90-day data if stale (>30 days)
  • ✅ Runs grid search to find 2 best strategies per timeframe
  • ✅ Saves fallback strategies automatically
  • ✅ Never trades on stale data

Trading Capabilities

  • ✅ Multi-timeframe trading (15m, 1h, 4h simultaneously)
  • ✅ High win rate strategies (85-95% in backtests)
  • ✅ Strict risk management (2:1 reward/risk minimum)
  • ✅ Profit locking system
  • ✅ Leverage scaling (25× conservative)

Data Management

  • ✅ 90-day OHLCV data (ETHUSDT, BTCUSDT)
  • ✅ Blockchain verification and auto-correction
  • ✅ Automatic freshness checking
  • ✅ Data integrity 100% validated

Strategy System

  • ✅ BASE_STRATEGY (always available, immutable)
  • ✅ Fallback strategies (data-driven, auto-generated)
  • ✅ Proven strategies (real-world tested)
  • ✅ 121,500 combinations tested per optimization

🏗️ System Architecture

Pre-Trading Check
       ↓
Data Validation (<30 days)
       ↓
If Stale → Download + Grid Search → Save Fallbacks
       ↓
System Ready
       ↓
Backtest/Trade with Fresh Data

📊 Trading Pairs

Currently supported:

  • ETHUSDT (Ethereum vs. USDT)
  • BTCUSDT (Bitcoin vs. USDT)

Want to add more pairs?

  1. Edit trading_pairs_config.py
  2. Add pair to ACTIVE_PAIRS
  3. Run python pre_trading_check.py --force

🎓 For New Users

  1. Quick start: Open QUICK_START.md
  2. Read the manual: Check docs/USER_MANUAL.md
  3. Understand the math: Review docs/MATHEMATICS.md
  4. Run validation: python pre_trading_check.py
  5. Test the system: python backtest_90_complete.py
  6. Paper trading: Follow USER_TESTING_GUIDE.md
  7. You're ready!

🛠️ Command Reference

System Validation

# Full validation with interactive prompts
python pre_trading_check.py

# Check health only (no updates)
python pre_trading_check.py --check-only

# Auto-update without prompts
python pre_trading_check.py --non-interactive

# Force update all data
python pre_trading_check.py --force

Backtesting

# Normal run with pre-flight validation
python backtest_90_complete.py

# Skip validation (for testing only)
python backtest_90_complete.py --skip-check

# Auto-update stale data
python backtest_90_complete.py --non-interactive

Strategy Updates

# Check data freshness only
python auto_strategy_updater.py --check

# Force update all strategies
python auto_strategy_updater.py --force

# Normal auto-update
python auto_strategy_updater.py

Data Management

# Download fresh 90-day data
python download_90day_data.py

# Verify data integrity
python blockchain_verifier.py

# Audit specific file
python audit_blockchain_data.py

Wallet Connection

# Connect to MetaMask wallet and test
python cli.py wallet connect

# Connect with specific RPC URL
python cli.py wallet connect --rpc-url https://mainnet.infura.io/v3/YOUR-KEY

# Connect to testnet
python cli.py wallet connect --testnet

# Check wallet balance
python cli.py wallet balance

# View gas prices
python cli.py wallet gas

# Full wallet info
python cli.py wallet info

Documentation

# Generate HTML documentation package
./generate_docs.sh

# Result: documentation_package/ folder with HTML files
# Open documentation_package/index.html in browser

📦 Project Structure

harvest/
├── README.md                    # This file
├── USER_MANUAL.md               # Complete user guide
├── MATHEMATICS.md               # Math explained simply
├── TRON_INTEGRATION.md          # Future plans
├── SYSTEM_COMPLETE_2024.md      # Delivery report
│
├── pre_trading_check.py         # Central validation
├── auto_strategy_updater.py     # Auto strategy updates
├── backtest_90_complete.py      # Enhanced backtest
├── generate_docs.sh             # Doc generator
│
├── data/                        # 90-day OHLCV data
│   ├── eth_90days.json
│   └── btc_90days.json
│
├── ml/                          # Strategy configs
│   ├── base_strategy.py
│   ├── fallback_strategies.json
│   └── ml_config.json
│
├── documentation_package/       # HTML docs
│   ├── index.html
│   └── [all documentation]
│
└── docs/
    └── archive/                 # Historical docs
        └── README.md

🔍 Troubleshooting

Problem: "Data is stale"

python auto_strategy_updater.py

Problem: "No fallback strategies"

python pre_trading_check.py

Problem: Backtest shows 0 trades

Check data integrity:

python blockchain_verifier.py

More Help

See USER_MANUAL.md Troubleshooting section

🚀 Future Enhancements

Coming in Q1-Q2 2025: Tron Network Integration

  • Ultra-fast transactions (<3 seconds vs 15 min Ethereum)
  • Near-zero fees (~$0.01 vs $20+ Ethereum)
  • Annual savings: $215,000+ in transaction fees
  • DEX integration: JustSwap, SunSwap
  • Smart contracts: Automated on-chain trading

See TRON_INTEGRATION.md for complete roadmap

📈 Performance

Backtested Results

  • Win Rate: 85-95% (target: 90%+)
  • Trades/Day: 3-5
  • Data Coverage: 90 days
  • Risk/Reward: Minimum 2:1
  • Strategy Combinations Tested: 121,500

System Reliability

  • Data Integrity: 100% verified
  • Blockchain Verification: Complete
  • Error Handling: Comprehensive
  • Documentation: Complete
  • Production Status: Ready

⚠️ Important Notes

Risk Warning

Cryptocurrency trading is highly risky. Only trade with money you can afford to lose. This system is a tool, not a guarantee of profit.

System Safety

  • Never trade on stale data (system enforces this)
  • Always run pre-flight checks before trading
  • Start with small amounts to test
  • Monitor performance regularly

Data Freshness

  • System requires data <30 days old
  • Automatic checks before each session
  • Auto-download and strategy updates available
  • Never skip validation in production

💡 Best Practices

Daily Routine

  1. Check system health: python pre_trading_check.py --check-only
  2. Update if needed: python pre_trading_check.py
  3. Run backtest: python backtest_90_complete.py

Weekly Maintenance

# Force refresh all data and strategies
python pre_trading_check.py --force

# Run comprehensive backtest
python backtest_90_complete.py

# Review strategy performance
# Check ml/fallback_strategies.json

Before Going Live

  1. ✅ Run backtest on 90 days
  2. ✅ Verify 90%+ win rate
  3. ✅ Understand all commands
  4. ✅ Read USER_MANUAL.md completely
  5. ✅ Start with minimal capital

📞 Support

System Health Check

python pre_trading_check.py --check-only

Getting Help

  1. Check USER_MANUAL.md first
  2. Review error messages (they're descriptive)
  3. Run validation: python pre_trading_check.py
  4. Check MATHEMATICS.md for calculation questions

Updating System

git pull origin main
python pre_trading_check.py --force

🏆 System Status

Version: 2.0
Status: ✅ Production Ready
Last Updated: December 17, 2024

All Success Criteria Met ✅

  • Automatic data freshness validation
  • Auto-download when data is stale
  • Grid search finds 2 best strategies per timeframe
  • Fallback strategies saved automatically
  • Never trades on stale data
  • Comprehensive documentation in layman's terms
  • Mathematical explanations with real examples
  • Future enhancement plans documented

The system is complete, tested, documented, and ready to use.

📄 License

See LICENSE file for details.

Ready to start? Read USER_MANUAL.md and run python pre_trading_check.py

Trade safely! 🚀

🧭 ARC Trading Fleet

Six sibling repositories. Same ARC event-and-receipt doctrine. Each has its own live GitHub Pages docs site, source, and README.

RepoOne-linerSourceDocs site
BrokeBotTRON Funding-Rate Arbitrage (CEX, Python)sourcehttps://garebear99.github.io/BrokeBot/
CharmUniswap v3 Spot Bot on Base (Node.js)sourcehttps://garebear99.github.io/Charm/
Harvest (you are here)Multi-Timeframe Crypto Research Platform (Python)sourcehttps://garebear99.github.io/Harvest/
One-Shot-Multi-ShotBinary-Options 3-Hearts Engine (JS)sourcehttps://garebear99.github.io/One-Shot-Multi-Shot/
DecaGridCapital-Ladder Grid Trading Docs Packsourcehttps://garebear99.github.io/DecaGrid/
EdgeStack CurrencyEvent-Sourced Multi-Currency Execution Specsourcehttps://garebear99.github.io/EdgeStack_Currency/

Upstream + meta

  • ARC-Core — governed event + receipt spine the fleet plugs into.
  • omnibinary-runtime + Arc-RAR — any-OS portability for deployment.
  • Portfolio — full project index (audio plugins, games, simulators, AI runtimes, robotics, trading).

💖 Support the fleet

If this repo helps you, the maintainer runs the entire ARC ecosystem solo. Any of the following keep the lights on:

Sponsor Buy Me a Coffee Ko-fi

Every dollar funds hardening across ARC-Core + the 15 consumer repos + the four roadmap repos. One author, one funding pool.