Harvest — Multi-Timeframe Crypto Trading System

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:

ARC-Core
omnibinary-runtime + Arc-RAR — any-OS portability.
Portfolio — full project index.

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?

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

🎓 For New Users

Quick start: Open QUICK_START.md
Read the manual: Check docs/USER_MANUAL.md
Understand the math: Review docs/MATHEMATICS.md
Run validation: python pre_trading_check.py
Test the system: python backtest_90_complete.py
Paper trading: Follow USER_TESTING_GUIDE.md
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

Check system health: python pre_trading_check.py --check-only
Update if needed: python pre_trading_check.py
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

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

📞 Support

System Health Check

python pre_trading_check.py --check-only

Getting Help

Check USER_MANUAL.md first
Review error messages (they're descriptive)
Run validation: python pre_trading_check.py
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.

🎉 Quick Links

USER_MANUAL.md - Start here
MATHEMATICS.md - Understand the math
TRON_INTEGRATION.md - Future plans
SYSTEM_COMPLETE_2024.md - Delivery report
documentation_package/index.html - Browse HTML docs
docs/archive/ - Historical documentation

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.

Repo	One-liner	Source	Docs site
BrokeBot	TRON Funding-Rate Arbitrage (CEX, Python)	source	https://garebear99.github.io/BrokeBot/
Charm	Uniswap v3 Spot Bot on Base (Node.js)	source	https://garebear99.github.io/Charm/
Harvest (you are here)	Multi-Timeframe Crypto Research Platform (Python)	source	https://garebear99.github.io/Harvest/
One-Shot-Multi-Shot	Binary-Options 3-Hearts Engine (JS)	source	https://garebear99.github.io/One-Shot-Multi-Shot/
DecaGrid	Capital-Ladder Grid Trading Docs Pack	source	https://garebear99.github.io/DecaGrid/
EdgeStack Currency	Event-Sourced Multi-Currency Execution Spec	source	https://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:

GitHub Sponsors: https://github.com/sponsors/GareBear99
Buy Me a Coffee: https://www.buymeacoffee.com/garebear99
Ko-fi: https://ko-fi.com/garebear99

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

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
analysis		analysis
archive		archive
core		core
dashboard		dashboard
docs		docs
documentation_package		documentation_package
ml		ml
strategies		strategies
tests		tests
tron		tron
utils		utils
validation		validation
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
COMPREHENSIVE_SYSTEM_REVIEW_DEC26_2024.md		COMPREHENSIVE_SYSTEM_REVIEW_DEC26_2024.md
CONTRIBUTING.md		CONTRIBUTING.md
DASHBOARD_COMPREHENSIVE_REVIEW.md		DASHBOARD_COMPREHENSIVE_REVIEW.md
DASHBOARD_TESTING_GUIDE.md		DASHBOARD_TESTING_GUIDE.md
DASHBOARD_VALIDATION_REPORT.md		DASHBOARD_VALIDATION_REPORT.md
DEBUG_SYSTEM_QUICK_REFERENCE.md		DEBUG_SYSTEM_QUICK_REFERENCE.md
DIRECTORY_STRUCTURE.md		DIRECTORY_STRUCTURE.md
Dockerfile		Dockerfile
FIXES_AND_REMAINING_TASKS.md		FIXES_AND_REMAINING_TASKS.md
INPUT_SEED_AUDIT_DEC26.md		INPUT_SEED_AUDIT_DEC26.md
LICENSE		LICENSE
MASTER_SUMMARY_PRODUCTION_ROADMAP.md		MASTER_SUMMARY_PRODUCTION_ROADMAP.md
NEXT_STEPS.md		NEXT_STEPS.md
PAPER_TRADING_48H_FIX_SUMMARY.md		PAPER_TRADING_48H_FIX_SUMMARY.md
PAPER_TRADING_LIVE_ANALYSIS.md		PAPER_TRADING_LIVE_ANALYSIS.md
PHASE2_UNISON_COMPLETION_REPORT.md		PHASE2_UNISON_COMPLETION_REPORT.md
PRODUCTION_AUDIT_REPORT_DEC26_2024.md		PRODUCTION_AUDIT_REPORT_DEC26_2024.md
PRODUCTION_DEPLOYMENT_GUIDE.md		PRODUCTION_DEPLOYMENT_GUIDE.md
PRODUCTION_READINESS_CHECKLIST.md		PRODUCTION_READINESS_CHECKLIST.md
PRODUCTION_READINESS_DEBUG_SYSTEM.md		PRODUCTION_READINESS_DEBUG_SYSTEM.md
QUICK_START.md		QUICK_START.md
README.md		README.md
SECURITY.md		SECURITY.md
SEED_ALIGNMENT_VERIFICATION.md		SEED_ALIGNMENT_VERIFICATION.md
SEED_VALIDATION_PLAN_STATUS.md		SEED_VALIDATION_PLAN_STATUS.md
SEED_VALIDATION_SYSTEM_COMPLETE.md		SEED_VALIDATION_SYSTEM_COMPLETE.md
START_HERE_USER_TESTING.md		START_HERE_USER_TESTING.md
SYSTEMS_UNISON_REQUIREMENTS.md		SYSTEMS_UNISON_REQUIREMENTS.md
SYSTEM_ENHANCEMENT_PLAN.md		SYSTEM_ENHANCEMENT_PLAN.md
USER_TESTING_GUIDE.md		USER_TESTING_GUIDE.md
USER_TESTING_VERIFICATION_COMPLETE.md		USER_TESTING_VERIFICATION_COMPLETE.md
VALIDATION_REPORT_PRODUCTION_READY.md		VALIDATION_REPORT_PRODUCTION_READY.md
WALLET_REFRESH_FIX_SUMMARY.md		WALLET_REFRESH_FIX_SUMMARY.md
__init__.py		__init__.py
auto_strategy_updater.py		auto_strategy_updater.py
backtest_90_complete.py		backtest_90_complete.py
btc_test_results.json		btc_test_results.json
check_grid_progress.sh		check_grid_progress.sh
check_wallet_for_paper_trading.py		check_wallet_for_paper_trading.py
cli.py		cli.py
dashboard.py		dashboard.py
dashboard.sh		dashboard.sh
docker-compose.yml		docker-compose.yml
documentation_package.zip		documentation_package.zip
eth_simple_test.json		eth_simple_test.json
eth_test_results.json		eth_test_results.json
ethusdt_v1.1_results.json		ethusdt_v1.1_results.json
ethusdt_v1.3_results.json		ethusdt_v1.3_results.json
generate_docs.sh		generate_docs.sh
health_check.py		health_check.py
install.sh		install.sh
live_trader.py		live_trader.py
pre_trading_check.py		pre_trading_check.py
recent_december_2024_backtest.json		recent_december_2024_backtest.json
requirements.txt		requirements.txt
run_complete_grid_search.sh		run_complete_grid_search.sh
run_paper_trading.py		run_paper_trading.py
seed_registry_demo.csv		seed_registry_demo.csv
test_concurrent_access.py		test_concurrent_access.py
test_dashboard_integration.py		test_dashboard_integration.py
test_paper_trading_live.py		test_paper_trading_live.py
test_wallet_persistence_security.py		test_wallet_persistence_security.py
test_wallet_refresh_fix.py		test_wallet_refresh_fix.py
trading_pairs_config.py		trading_pairs_config.py
trading_system_documentation.tar.gz		trading_system_documentation.tar.gz
troubleshooting_demo.json		troubleshooting_demo.json
validate_dashboard_display.py		validate_dashboard_display.py
validate_paper_trading_ready.py		validate_paper_trading_ready.py
validation_report_20251216_132721.json		validation_report_20251216_132721.json
watch_progress.sh		watch_progress.sh

Folders and files

Latest commit

History

Repository files navigation

Harvest — Multi-Timeframe Crypto Trading System

Why you might read this repo

Part of the ARC ecosystem

Keywords

📖 Official docs

Cryptocurrency Trading System

🚀 Quick Start

📚 Documentation

Start Here

Paper Trading

Mathematics

Future Plans

System Status

🎯 What This System Does

✅ Key Features

Automated Workflow

Trading Capabilities

Data Management

Strategy System

🏗️ System Architecture

📊 Trading Pairs

🎓 For New Users

🛠️ Command Reference

System Validation

Backtesting

Strategy Updates

Data Management

Wallet Connection

Documentation

📦 Project Structure

🔍 Troubleshooting

Problem: "Data is stale"

Problem: "No fallback strategies"

Problem: Backtest shows 0 trades

More Help

🚀 Future Enhancements

Coming in Q1-Q2 2025: Tron Network Integration

📈 Performance

Backtested Results

System Reliability

⚠️ Important Notes

Risk Warning

System Safety

Data Freshness

💡 Best Practices

Daily Routine

Weekly Maintenance

Before Going Live

📞 Support

System Health Check

Getting Help

Updating System

🏆 System Status

All Success Criteria Met ✅

📄 License

🎉 Quick Links

🧭 ARC Trading Fleet

Upstream + meta

💖 Support the fleet

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages