English | 中文 | 한국어 | 日本語

Quick Start

pip install finclaw-ai
finclaw evolve --quick            # See results in ~2 minutes
finclaw evolve --market crypto    # Full evolution (deeper search)

No API keys. No exchange accounts. No config files. From install to first evolved strategy in under 2 minutes.

$ finclaw evolve --quick

  ⚡ Quick mode — small dataset, fast iterations
     Results in ~2 minutes. Use without --quick for full evolution.

============================================================
 FinClaw Auto Evolution Engine
============================================================
  [factors] loaded 480 dynamic factors
  Population: 15 | Elite: 3 | Mutation rate: 0.5
  ------------------------------------------------------------
  Gen    0 | fitness=   -1.00 | return=   0.0% | sharpe=-0.74 | trades=   0 | 28s
  Gen    5 | fitness=    1.23 | return=  12.4% | sharpe= 0.85 | trades=  14 | 25s
  Gen   10 | fitness=    3.60 | return=  18.7% | sharpe= 1.40 | trades=  23 | 27s

  ═══════════════════════════════════════════
  🏆 Best Strategy Found
  ═══════════════════════════════════════════
  Generation:    10
  Fitness:       3.60
  Annual Return: 18.7%
  Sharpe Ratio:  1.40
  Max Drawdown:  12.3%

  Walk-Forward OOS Results:
    Window 0: +6.4%  (6 trades) ✅
    Window 1: -2.1%  (17 trades) ❌
    Window 2: +17.2%  (14 trades) ✅
    Profitable: 2/3 windows

  Top Factors:
    crypto_bollinger_fast                    0.0226 ████
    momentum_3d                              0.0187 ███
    previous_low_test                        0.0252 █████

  👉 Ready for more? Run full evolution:
     finclaw evolve --market crypto

Why FinClaw?

Other tools: Write a strategy → Code → Backtest → Tweak → Repeat
FinClaw: Define the search space → GA evolves strategies → Walk-forward filters survivors

Most quant tools expect you to write the strategy. FinClaw skips that — a genetic algorithm breeds strategies from 484 factors, then walk-forward tests them on unseen data. You get strategies that survived out-of-sample, not just curve-fitted backtests.

How Evolution Works

   Seed population (random factor weights)
         │
         ▼
   ┌─────────────┐
   │  Backtest    │  Walk-forward: multi-window OOS validation
   │  each DNA    │  Slippage modeled, position caps, real fees
   └──────┬──────┘
          │
          ▼
   Select top performers (Sharpe × Return / MaxDrawdown)
          │
          ▼
   ┌─────────────────────────────────────────┐
   │  Cross-sectional neutralization (P0-2)  │
   │  Correlation-aware selection    (P0-1)  │
   │  Factor diversity bonus         (P0-3)  │
   │  Turnover cost penalty          (P0-4)  │
   └──────┬──────────────────────────────────┘
          │
          ▼
   Mutate + Crossover → next generation
          │
          ▼
        Repeat

System architecture: data ingestion → factor computation → genetic evolution → walk-forward validation

Every DNA is a weight vector across 484 factors plus advanced risk/position parameters — all evolvable:

The GA tries combinations you wouldn't think of. Anti-overfitting is built in: Arena mode runs multiple strategies simultaneously and penalizes crowded signals.

finclaw evolve --market crypto --generations 50
finclaw evolve --pareto --market crypto     # Multi-objective (NSGA-III)
finclaw evolve --logic-guided               # Semantically guided mutations

Anti-Overfitting

FinClaw doesn't just backtest — it tries to break your strategy:

• Arena Mode — Multiple strategies compete in the same simulated market. Crowded signals get penalized.
• Monte Carlo — 1,000 iterations, p-value < 0.05
• Walk-Forward — Multi-window OOS validation with bootstrap confidence intervals
• Cross-Sectional Neutralization — Z-score normalize scores to filter market-wide noise
• Correlation Guard — Rejects highly correlated stock picks (>0.85 Pearson)
• Factor Diversity — HHI-based bonus rewards diversified factor usage, penalizes concentration
• Bias Detection — Look-ahead, snooping, survivorship checks
• Factor Orthogonality — Auto-removes redundant factors
• Turnover Penalty — Excessive trading gets penalized in fitness (modeled as real cost)

MCP Server

Expose FinClaw as tools for Claude, Cursor, VS Code, or any MCP client:

{
  "mcpServers": {
    "finclaw": {
      "command": "finclaw",
      "args": ["mcp", "serve"]
    }
  }
}

10 tools: get_quote, get_history, list_exchanges, run_backtest, analyze_portfolio, get_indicators, screen_stocks, get_sentiment, compare_strategies, get_funding_rates.

Key Commands

70+ commands total — run finclaw --help for the full list.

Data Sources

Dashboard

The web dashboard (dashboard/) provides 7 pages: market overview, backtesting, strategy comparison, evolution monitoring, portfolio management, stock screening, and individual stock analysis with technical indicators.

cd dashboard && npm install && npm run dev

Note: Dashboard screenshots are from development builds and may show placeholder data. Run the dashboard locally to see live results from your own evolution runs.

Demo

Watch: How FinClaw's Evolution Engine Works (2 min)

Roadmap

• 484-factor evolution engine
• Walk-forward + Monte Carlo + Arena mode
• Bias detection suite
• MCP server for AI agents
• Multi-objective Pareto evolution (NSGA-III)
• Market Logic Layer (semantically guided mutations)
• Paper trading infrastructure
• Evolution visualization (CLI ASCII tree + interactive HTML dashboard)
• Advanced position sizing (signal-strength weighted)
• Trailing stop loss (evolvable activation + trail %)
• Market regime adaptation (auto-reduce in bear markets)
• Cross-sectional score neutralization
• Portfolio correlation guard
• Factor diversity optimization (HHI-based)
• Swing trading support (hold periods up to 60 days, dynamic trend exits)
• DEX execution (Uniswap V3 / Arbitrum)
• Multi-timeframe strategy evolution (1h / 4h / 1d)
• Multi-strategy ensemble (regime-switching)
• Short selling for crypto
• Factor decay detection (rolling IC monitoring)
• Foundation model for price sequences
• Web dashboard with live P&L tracking
• QuantConnect-style cloud execution (SaaS)
• Mobile alerts via Telegram/Discord
• Community strategy marketplace

Disclaimer

This project is for educational and research purposes only. Not financial advice. Past performance does not guarantee future results. Always paper trade first.

Also Check Out

Contributing

Want to contribute? Here's the quick path:

1. Pick an issue — good first issue is a good starting point
2. Fork & clone

   git clone https://github.com/NeuZhou/finclaw.git
   cd finclaw && pip install -e ".[dev]" && pytest
   

3. Submit a PR — we'll review it

CONTRIBUTING.md · Discord · Report Bug · Request Feature

If this is useful, a ⭐ helps others find it.

License

AGPL-3.0

Star History

Honest Disclosure

Previous versions reported inflated backtest returns caused by look-ahead bias and short validation windows. This has been fixed — scoring uses previous-period data, position sizes are capped, slippage is modeled, and walk-forward validation uses year-long OOS windows with OOS return gates (strategies that lose money out-of-sample get zero or negative fitness regardless of in-sample performance). Use finclaw check-backtest to verify results.