finclaw-ai 5.6.1

AI-native quantitative finance engine with genetic algorithm strategy evolution

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

FinClaw

Genetic algorithms evolve trading strategies so you don't have to write them.

Vibe Evolving — Stop writing strategies. Let them evolve.

484 factors · Genetic evolution · Walk-forward validated · No API keys needed

_{⬆️ Real evolution run: 9 crypto assets × 600 generations. Fitness climbs from random (-0.95) to optimized (37.5) — 33% annual return, 6.06 Sharpe, 5.6% max drawdown.}

Quick Start · Why FinClaw? · How It Works · MCP Server · Discord

---

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.

What does it look like? (click to expand)

$ 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.

	FinClaw	Freqtrade	FinRL / Qlib
Strategy creation	GA evolves 484-dim DNA	You write rules	DRL trains agent
Continuous evolution	✅ Strategies keep evolving	❌ Strategy fixed	❌ Training offline
Walk-forward validation	✅ Multi-window + Monte Carlo	❌ Plugin needed	⚠️ Partial
Trailing stop	✅ Evolvable (activation + trail %)	✅ Manual config	❌
Position sizing	✅ Signal-strength weighted	⚠️ Fixed or stake_amount	❌
Market regime adaptation	✅ Auto-reduce in bear market	❌	❌
Portfolio correlation guard	✅ Rejects correlated picks	❌	⚠️ Partial
Zero API keys to start	✅	❌ Needs exchange keys	❌ Needs data setup
Markets	Crypto + A-shares + US	Crypto only	A-shares (Qlib)
MCP server for AI agents	✅	❌	❌

---

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:

Parameter	What it controls
hold_days	Hold period per trade (2–60 days — day trades to swing trades)
capital_utilization	Fraction of capital deployed (0.3–1.0)
position_sizing_power	Signal strength → allocation weight (0=equal, 2=quadratic)
trailing_stop	Lock in profits: trail N% below peak price
trend_exit_enabled	Exit on MA crossover — cut losses before stop-loss
market_regime_sensitivity	Auto-reduce exposure in bear markets
profit_target_scaling	Scale take-profit by signal confidence
time_decay_exit	Tighten stop-loss as hold period extends
scale_in_tranches	Split entry into 1-3 tranches
sector_max_pct	Cap sector concentration (diversification)
kelly_fraction	Kelly criterion position sizing based on recent win rate

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

---

📊 484 Factors — 284 general + 200 crypto-native (click to expand)

All normalized to [0, 1]:

Category	Count	Examples
Crypto-Native	200	Funding rate, session effects, whale detection, liquidation cascade
Momentum	14	ROC, acceleration, trend strength
Volume & Flow	13	OBV, smart money, Wyckoff VSA
Volatility	13	ATR, Bollinger squeeze, vol-of-vol
Mean Reversion	12	Z-score, Keltner channel position
Trend Following	14	ADX, EMA golden cross, MA fan
Qlib Alpha158	11	KMID, KSFT, CNTD (Microsoft Qlib compatible)
Risk Warning	11	Consecutive losses, death cross, gap-down
Quality Filter	11	Earnings momentum, relative strength
Price Structure	10	Candlestick patterns, support/resistance
Sentiment	2	EN/ZH keyword sentiment + momentum
DRL Signal (experimental)	2	Q-learning buy probability + state value

Weights are determined by the evolution engine — no manual tuning.

---

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

Command	What it does
finclaw demo	See all features in action
finclaw quote AAPL	Real-time US stock quote
finclaw quote BTC/USDT	Crypto quote via ccxt
finclaw evolve --market crypto	Run genetic evolution
finclaw evolve --pareto	Multi-objective Pareto evolution
finclaw backtest -t AAPL	Backtest a strategy
finclaw check-backtest	Verify backtest integrity
finclaw analyze TSLA	Technical analysis
finclaw copilot	AI financial assistant
finclaw mcp serve	Start MCP server
finclaw paper	Paper trading mode
python -m finclaw.viz.evolution_tree <log>	ASCII evolution timeline
python -m finclaw.viz.parse_evolution_log <log>	Parse evolution log → JSON

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

---

Data Sources

Market	Source	API Key?
Crypto	ccxt (100+ exchanges)	No
US Stocks	Yahoo Finance	No
A-Shares	AKShare + BaoStock	No
Sentiment	CryptoCompare + AKShare	No

---

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

Project	What it does
ClawGuard	AI Agent Immune System — 480+ threat patterns, zero dependencies
AgentProbe	Playwright for AI Agents — test, record, replay agent behaviors

---

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.