Skillget

finclaw

mcp
SUMMARY

Genetic algorithms evolve trading strategies from 484 factors. A-shares, US stocks, Crypto. 5500+ tests.

README.md

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

FinClaw

Self-Evolving Trading Intelligence — genetic algorithms discover strategies you never would.

PyPI CI codecov License Python 3.10+ 484 Factors 6000+ Tests Crypto + A-shares + US GitHub Stars

FinClaw — Self-Evolving Trading Intelligence

FinClaw Demo Video
▶️ Watch: How FinClaw's Self-Evolving Engine Works (2 min)

FinClaw doesn't need you to write strategies — its genetic algorithm discovers and evolves them autonomously across 484 factor dimensions, then validates them with walk-forward testing and Monte Carlo simulation.

Disclaimer

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

🚀 Quick Start

pip install finclaw-ai
finclaw demo          # See it in action
finclaw quote AAPL    # Real-time quotes
finclaw quote BTC/USDT # Crypto too

No API keys, no exchange accounts, no config files needed.

See it in action (click to expand) 
$ finclaw demo

=== Real-Time Quotes ===

Symbol        Price     Change        %
--------------------------------------------------------
AAPL         189.84    +2.31  +1.23%
NVDA         875.28   +15.67  +1.82%
BTC/USDT  66,458.10    -1.24  -0.53%

=== Strategy Evolution Engine ===

FinClaw's core: genetic algorithms evolve strategies autonomously.
Population: 30  |  484 factor dimensions  |  Walk-forward validated

  Gen    Return    Fitness   Sharpe  Progress
  ---    ------    -------   ------  --------
    1      3.2%       12.1     0.4   ##########
   10      8.7%       34.5     0.8   ##########
   25     18.4%       89.2     1.3   ##########
   50     31.6%      156.7     1.7   ##########
   75     42.3%      210.4     2.0   ##########
  100     48.5%      245.8     2.2   ##########

DNA evolved across 484 factors:
  Top weights: RSI 0.34, Momentum 0.25, MACD 0.18, Volume 0.12
  Walk-forward validated | Slippage modeled | Position caps

=== Backtest Results ===

Strategy:  +75.7%  (+32.5%/yr)    Buy&Hold:  +67.7%
Alpha:     +8.0%                  Sharpe:    1.85
MaxDD:     -8.3%                  Win Rate:  63%

=== Paper Trading Portfolio ===

Symbol     Shares   Avg Cost      Price         P&L
----------------------------------------------------
AAPL           50     178.50     189.84  +$5,650.00
NVDA           20     810.00     875.28  +$1,305.60
BTC/USDT    0.015  66,458.00  66,458.00      $0.00
----------------------------------------------------
TOTAL                                   +$6,955.60

=== AI Features ===

MCP Server   Expose FinClaw as tools for Claude, Cursor, VS Code
Copilot      Interactive AI financial assistant
Strategy AI  Natural language -> trading code

Try it yourself:
  finclaw evolve --market crypto    # Run strategy evolution
  finclaw quote BTC/USDT            # Live crypto quote
  finclaw analyze TSLA              # Technical analysis
  finclaw copilot                   # AI financial chat

Why FinClaw?

Most quant tools make you write the strategy. FinClaw evolves strategies for you.

FinClaw Freqtrade Jesse FinRL / Qlib
Strategy design GA evolves 484-dim DNA You write rules You write rules DRL trains agent
Continuous evolution Strategy itself evolves Bot runs, strategy fixed Bot runs, strategy fixed Training offline
Walk-forward validation ✅ Built-in (70/30 + Monte Carlo) ❌ Plugin needed ❌ Plugin needed ⚠️ Partial
Anti-overfitting Arena + bias detection Basic cross-validation Basic Varies
Zero API keys to start ✅ pip install && finclaw demo ❌ Needs exchange keys ❌ Needs keys ❌ Needs data setup
Market coverage Crypto + A-shares + US Crypto only Crypto only A-shares (Qlib)
MCP server (AI agents) ✅ Claude / Cursor / VS Code ❌ ❌ ❌
Factor library 484 factors, auto-weighted ~50 manual indicators Manual indicators Alpha158 (Qlib)
Multi-objective Pareto ✅ NSGA-III ❌ ❌ ❌

📊 484 Factor Dimensions

284 general factors + 200 crypto-native factors, organized by category:

Category Count Examples
Crypto-Native 200 Funding rate proxy, session effects, whale detection, liquidation cascade
Momentum 14 ROC, acceleration, trend strength, quality momentum
Volume & Flow 13 OBV, smart money, volume-price divergence, Wyckoff VSA
Volatility 13 ATR, Bollinger squeeze, regime detection, vol-of-vol
Mean Reversion 12 Z-score, rubber band, Keltner channel position
Trend Following 14 ADX, EMA golden cross, higher-highs/higher-lows, MA fan
Qlib Alpha158 11 KMID, KSFT, CNTD, CORD, SUMP (Microsoft Qlib compatible)
Quality Filter 11 Earnings momentum proxy, relative strength, resilience
Risk Warning 11 Consecutive losses, death cross, gap-down, limit-down
Top Escape 10 Distribution detection, climax volume, smart money exit
Price Structure 10 Candlestick patterns, support/resistance, pivot points
Davis Double Play 8 Revenue acceleration, tech moat, supply exhaustion
Gap Analysis 8 Gap fill, gap momentum, gap reversal
Market Breadth 5 Advance/decline, sector rotation, new highs/lows
News Sentiment 2 EN/ZH keyword sentiment score + momentum
DRL Signal 2 Q-learning buy probability + state value estimate

Design principle: Technical, sentiment, DRL, fundamental — all signals are unified as factors returning [0, 1]. Weights are determined by the evolution engine, eliminating human bias from signal synthesis.

🧬 Self-Evolution Engine

The genetic algorithm continuously discovers optimal strategies:

  1. Seed — Initialize population with diverse factor weight configurations
  2. Evaluate — Walk-forward backtest each DNA across all assets
  3. Select — Keep top performers by fitness (Sharpe × Return / MaxDrawdown)
  4. Mutate — Random weight perturbation, crossover, factor add/drop
  5. Repeat — Runs 7×24 on your machine
finclaw evolve --market crypto --generations 50   # Crypto (main use case)
finclaw evolve --market cn --generations 50       # A-shares
finclaw evolve --market crypto --population 50 --mutation-rate 0.2 --elite 10

🎯 Multi-Objective Pareto Evolution (NSGA-III)

Instead of collapsing all metrics into a single fitness score, Pareto mode optimizes multiple objectives simultaneously:

  • Annualized return (maximize)
  • Maximum drawdown (minimize)
  • Turnover rate (minimize)
  • Strategy complexity (minimize, optional — penalizes overfitting)

The result is a Pareto front — a set of strategies where no strategy is strictly better than another in all objectives. You pick the one that matches your risk/return preference.

finclaw evolve --pareto --market crypto --generations 50   # Multi-objective mode
finclaw evolve --pareto --pareto-complexity                # Include complexity objective
finclaw pareto-front                                        # View current Pareto front
finclaw pareto-front --format json                          # Export as JSON

Uses NSGA-III (Deb & Jain, IEEE TEVC 2014) via pymoo.

🧠 Market Logic Layer (Guided Factor Evolution)

Inspired by AlphaLogics (arXiv:2603.20247), the Market Logic Layer replaces blind random mutation with semantically guided evolution. Instead of mutating all 484 factors uniformly, it defines high-level trading hypotheses that bias mutations toward relevant factor groups:

Logic Description Preferred Factors
Momentum Following Ride price trends early ROC, trend strength, MA alignment
Mean Reversion Fade overextended moves RSI, Bollinger, Z-score, residual
Volatility Breakout Catch range expansions ATR, Bollinger squeeze, Donchian
Money Flow Follow institutional capital OBV, MFI, smart money, volume
Bottom Fishing Buy capitulation reversals KDJ, bottom candles, capitulation
Trend Following Stay with established trends ADX, MA fan, channel position
Value Investing Fundamental quality filters PE, PB, ROE, revenue growth
Market Sentiment Gauge crowd psychology Fear/greed, breadth, sector rotation

Key design: Logic is "guidance" not "restriction" — 30% of mutations remain purely random for serendipitous discovery. Auto-switches logic when stagnation is detected.

finclaw evolve --logic-guided                              # Enable guided mode (default: momentum_following)
finclaw evolve --logic-guided --logic mean_reversion       # Start with mean reversion logic
finclaw evolve --logic-guided --logic-exploration 0.5      # 50% random exploration

Evolution Results

Market Generation Annual Return Sharpe Max Drawdown
A-Shares Gen 89 re-evolving — —
Crypto Gen 19 re-evolving — —

Honest disclosure: Previous versions reported inflated backtest returns (2,756% / 16,066%) caused by look-ahead bias in the scoring function — the backtester was using current-period indicators to make decisions at the current period’s open price. This has been fixed: scoring now uses previous-period data, position sizes are capped, and slippage is modeled. The evolution engine needs to be re-run with the corrected backtester to produce valid results. Always use finclaw check-backtest to verify, and finclaw paper to paper trade before risking real capital.

🏟️ Arena Mode (Anti-Overfitting)

Traditional backtests evaluate each strategy in isolation — overfitted strategies look great on history but fail live. FinClaw's Arena Mode fixes this:

  • Multiple DNA strategies trade simultaneously in the same simulated market
  • Crowding penalty: When >50% of DNAs buy on the same signal, price impact kicks in
  • Overfitted strategies that only work in isolation get penalized in Arena rankings

✅ Quality Assurance

  • Walk-forward validation (70/30 train/test split)
  • Monte Carlo simulation (1,000 iterations, p-value < 0.05)
  • Bootstrap 95% confidence intervals
  • Arena competition (multi-DNA market simulation)
  • Bias detection (look-ahead, snooping, survivorship)
  • Factor IC/IR analysis with decay curves
  • Factor orthogonal matrix (auto-remove redundant factors)
  • Turnover penalty in fitness function
  • 4,900+ automated tests across 157 test files

💻 CLI Reference

FinClaw ships with 70+ CLI commands. Here are the essentials:

Command Description
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 algorithm evolution
finclaw backtest -t AAPL Backtest a strategy on a stock
finclaw check-backtest Verify backtest results
finclaw analyze TSLA Technical analysis
finclaw screen Stock screener
finclaw risk-report Portfolio risk report
finclaw sentiment Market sentiment
finclaw copilot AI financial assistant
finclaw generate-strategy Natural language → strategy code
finclaw mcp serve Start MCP server for AI agents
finclaw paper Paper trading mode
finclaw doctor Environment check

Run finclaw --help for the full list.

🤖 MCP Server (AI Agents)

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

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

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

📡 Data Sources

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

Architecture

┌──────────────────────────────────────────────────────┐
│             Evolution Engine (Core)                   │
│      Genetic Algorithm → Mutate → Backtest → Select   │
│                                                       │
│      Input: 484 factors × weights = DNA               │
│      Output: Walk-forward validated strategy           │
├──────────────────────────────────────────────────────┤
│   Technical(284) │ Sentiment │ DRL │ Davis │ Crypto(200)│
│       All → compute() → [0, 1]                        │
├──────────────────────────────────────────────────────┤
│   Arena Competition │ Bias Detection │ Monte Carlo     │
├──────────────────────────────────────────────────────┤
│   Paper Trading → Live Trading → 100+ Exchanges       │
└──────────────────────────────────────────────────────┘

Roadmap

  • 484-factor evolution engine
  • Walk-forward validation + Monte Carlo
  • Arena competition mode
  • Bias detection suite
  • News sentiment + DRL factors
  • Davis Double Play factors
  • Paper trading infrastructure
  • MCP server for AI agents
  • DEX execution (Uniswap V3 / Arbitrum)
  • Multi-timeframe support (1h/4h/1d)
  • Foundation model for price sequences

🌐 Ecosystem

FinClaw is part of the NeuZhou AI agent toolkit:

Project Description
FinClaw AI-native quantitative finance engine
ClawGuard AI Agent Immune System — 285+ threat patterns, zero dependencies
AgentProbe Playwright for AI Agents — test, record, replay agent behaviors

Contributing

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

See CONTRIBUTING.md for guidelines. Report bugs · Request features

License

AGPL-3.0

Star History

Star History

Yorumlar (0)

Sonuc bulunamadi