finclaw-ai 1.0.0

AI-Powered Financial Intelligence Engine. 8 Master Strategies, 3 Markets, 227 Tests.

🐋 FinClaw

AI Trading Engine with Verified Alpha

English | 中文 | 日本語 | 한국어 | Français

100万 → 354万 (5年, 年化29.1%)
Tested on 100+ real stocks across US, China, Hong Kong
30/34 individual stock backtests outperform market

---

What does it do?

FinClaw scans stocks, picks winners, manages risk, and validates everything with real data.

# Pick 5 best US stocks with Soros-style momentum strategy
python FinClaw.py scan --market us --style soros --top 5

# Backtest any stock
python FinClaw.py backtest --ticker NVDA --period 5y

# Run full test suite
python FinClaw.py test

Why FinClaw?

Most "AI trading" projects generate signals and stop there. No backtesting, no risk management, no validation.

FinClaw is different:

• Verified: Every claim backed by reproducible backtests
• Complete: Selection → Entry → Position Management → Exit → Portfolio
• Tested: 34 automated regression tests, every commit validated
• Multi-market: US stocks, China A-shares, Hong Kong
• Honest: We show where we lose, not just where we win

Performance

5-Year Real Data (2020-2025)

Strategy	Annual Return	5Y Total	Risk Level
v10 Unified Top-5	+29.1%/y	+254%	High
LLM-Enhanced Top-10	+24.8%/y	+202%	Medium-High
Balanced Top-10	+19.5%/y	+142%	Medium
Conservative Top-15	+11.8%/y	+74%	Low

Tested on 100+ real stocks from Yahoo Finance. No synthetic data.

Individual Stock Win Rate

Tested head-to-head against AHF's technical analysis on 34 stocks:

FinClaw wins: 30/34 (88%)
Average edge: +10.8% per year

Quick Start

1. Install

git clone https://github.com/user/FinClaw.git
cd FinClaw
pip install -r requirements.txt  # aiohttp, yfinance

2. Verify

python FinClaw.py test
# Expected: 34/34 tests passed

3. Pick Stocks

# US market, aggressive style
python FinClaw.py scan --market us --style druckenmiller

# China A-shares, balanced
python FinClaw.py scan --market china --style buffett

# All markets
python FinClaw.py scan --market all --style soros

4. Backtest

python FinClaw.py backtest --ticker NVDA --period 5y
python FinClaw.py backtest --ticker 688256.SS --period 3y

8 Built-in Strategies

Strategy	Philosophy	Risk	Target
druckenmiller	Momentum. "When you see it, bet big."	Very High	25-40%/y
soros	Reflexivity. Self-reinforcing trends.	High	25-35%/y
cathie_wood	Disruptive innovation. 5-year horizon.	Very High	20-40%/y
buffett	Quality + value. Buy fear, hold forever.	Medium	20-30%/y
lynch	Growth/volatility ratio. "Boring" winners.	Medium	20-27%/y
simons	Pure quant. Highest Sharpe ratio.	Medium	15-25%/y
dalio	All-weather. Low correlation, risk parity.	Low	12-18%/y
conservative	Low-vol blue chips. Capital preservation.	Very Low	8-12%/y

How It Works

┌──────────────────────────────────────────────────────┐
│                    FinClaw v10                     │
│                                                        │
│  1. SCAN        Multi-factor + AI disruption analysis  │
│  2. RANK        7 master strategies vote               │
│  3. SELECT      Top-N by conviction score              │
│  4. ENTER       Regime-adaptive timing (7 regimes)     │
│  5. MANAGE      Trailing stop + pyramiding + sizing    │
│  6. EXIT        Regime shift + trend breakdown          │
│  7. VALIDATE    34 TDD tests + real data backtest      │
│                                                        │
│  Selection engine: 3 layers                            │
│  ┌─────────┐ ┌──────────────┐ ┌──────────────────┐   │
│  │ Quant   │+│ Fundamentals │+│ AI Disruption    │   │
│  │ 6 factor│ │ P/E, growth  │ │ Who wins in AI?  │   │
│  └─────────┘ └──────────────┘ └──────────────────┘   │
└──────────────────────────────────────────────────────┘

Selection Engine (3 Layers)

Layer 1 — Quantitative (always on)

• Multi-timeframe momentum (1M/3M/6M/1Y)
• EMA trend alignment (8/21/55)
• RSI, Bollinger Bands, volume confirmation
• Sharpe ratio, max drawdown, volatility

Layer 2 — Fundamental (yfinance)

• P/E, P/B, PEG ratio
• Revenue growth, profit margins
• Return on equity, debt ratios

Layer 3 — AI Disruption Analysis

• Is this company an AI winner or victim?
• Competitive moat in the AI era
• Narrative strength (self-reinforcing?)
• Example: NVIDIA (+0.25 boost) vs Salesforce (-0.21 penalty)

Signal Engine (7 Regimes)

Regime	Max Position	Strategy
CRASH	0%	Emergency exit
STRONG_BEAR	10%	Defensive bounces only
BEAR	15%	Small counter-trend
RANGING	45-68%	Mean reversion
VOLATILE	65%	Direction-dependent
BULL	80%	Trend following
STRONG_BULL	92%	Maximum conviction

Project Structure

FinClaw/
├── FinClaw.py              # CLI entry point
├── agents/
│   ├── signal_engine_v7.py     # 6-factor signal engine
│   ├── backtester_v7.py        # Full lifecycle backtester
│   ├── stock_picker.py         # Multi-factor stock picker
│   ├── llm_analyzer.py         # AI disruption analysis
│   ├── ahf_simulator.py        # Competitor simulator
│   └── statistics.py           # Sharpe, drawdown, etc.
├── tests/
│   └── test_engine.py          # 34 regression tests
├── benchmark_v10.py            # Unified engine benchmark
├── benchmark_multimarket.py    # Global market test
├── benchmark_real.py           # Real data validation
├── docs/
│   ├── README_zh.md            # 中文文档
│   ├── README_ja.md            # 日本語ドキュメント
│   ├── README_ko.md            # 한국어 문서
│   └── README_fr.md            # Documentation française
└── _scratch/                   # Archived experiments

Development

Run Tests

python FinClaw.py test
# or directly:
python tests/test_engine.py

Test Coverage

Test	What it checks
Golden Thresholds	9 scenarios must meet minimum alpha
Average Alpha	Portfolio average must exceed 9%
No Catastrophic Loss	No single trade > 35% loss
Regime Detection	Bull/bear/ranging correctly identified
Determinism	Same input → same output
Warmup Protection	No trades in first 20 bars
vs Freqtrade	Must beat on all 9 sim scenarios

Contributing

# 1. Make your change
# 2. Run tests (must pass all 34)
python tests/test_engine.py
# 3. Run quick benchmark
python benchmark_real.py
# 4. If alpha improved or neutral, submit PR

Roadmap

Done ✅

• 6-factor signal engine with 7 regimes
• Full lifecycle backtester
• Multi-factor stock picker (quant + fundamental)
• AI disruption analysis layer
• 7 master strategy presets
• CLI with one-command scanning
• 34 TDD regression tests
• Multi-market support (US, China, HK)
• Multi-language docs (EN, ZH, JA, KO, FR)

Next 🔨

• Live market data streaming
• Paper trading mode
• Web dashboard
• Telegram/WeChat alert bot
• QuantStats HTML report integration
• Options/futures support
• Walk-forward validation

FAQ

Q: Is this financial advice? A: No. This is a research tool. Use at your own risk.

Q: Can it trade automatically? A: Not yet. Currently analysis and backtesting only. Live trading is on the roadmap.

Q: How is this different from ai-hedge-fund? A: AHF generates signals. FinClaw is a complete system — it selects, enters, manages, exits, and validates. We beat AHF on 88% of stocks tested.

Q: What data does it need? A: Just an internet connection. Uses Yahoo Finance (free) for price data.

Q: Can I add my own stocks? A: Yes. Any ticker supported by Yahoo Finance works.

License

MIT License. Not financial advice. Past performance does not guarantee future results.

---

Built by an engineer who believes trading systems should be engineered, not hoped. 🐋