FinClaw

<h1 align="center">🦀 FinClaw</h1>

<p align="center"> <strong>AI-powered quantitative finance in your terminal</strong> </p>

<p align="center"> <a href="https://pypi.org/project/finclaw-ai/"><img src="https://img.shields.io/pypi/v/finclaw-ai?color=blue" alt="PyPI"></a> <a href="https://github.com/NeuZhou/finclaw/actions/workflows/ci.yml"><img src="https://github.com/NeuZhou/finclaw/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python"></a> <a href="https://github.com/NeuZhou/finclaw/stargazers"><img src="https://img.shields.io/github/stars/NeuZhou/finclaw?style=social" alt="Stars"></a> </p>

<p align="center"> <img src="https://raw.githubusercontent.com/NeuZhou/finclaw/master/docs/demo.gif" alt="FinClaw Demo" width="700"> </p>

$ finclaw quote AAPL
  AAPL  $252.82  +2.31 +0.92%
  Bid: 252.82  Ask: 252.83  Vol: 30,091,880

$ finclaw analyze TSLA --indicators rsi,macd,bollinger
  🔬 Technical Analysis: TSLA
  Price: $175.21  |  52w High: $299.29  |  52w Low: $138.80

  RSI(14)        62.4  NEUTRAL     momentum balanced
  MACD          +4.82  BULLISH     histogram expanding
  Bollinger      72%B  NEUTRAL     upper half of band

$ finclaw backtest -t NVDA --start 2023-01-01
  🚀 NVDA | momentum
  Return: +142.3% (+55.2%/yr) | Alpha: +18.7%
  MaxDD: -12.1% | Sharpe: 1.85 | Trades: 47

---

Why FinClaw?

Most quant tools make you configure databases, install heavy dependencies, and write boilerplate before you see your first result. FinClaw gets you from zero to insight in one command. Zero API keys needed — it uses Yahoo Finance by default. A pure NumPy core means it installs in seconds, not minutes. And when you're ready for AI-powered strategy generation, MCP agent integration, or multi-exchange live trading — it's all built in.

---

Quick Start

pip install finclaw-ai
finclaw demo              # See all features — no API key needed
finclaw quote AAPL        # Real-time stock quote
finclaw copilot           # AI financial assistant

---

Feature Comparison

Feature	FinClaw	Backtrader	Zipline	Freqtrade
Zero-config install	✅	❌	❌	❌
CLI interface	✅	❌	❌	✅
AI strategy generation	✅	❌	❌	❌
Natural language copilot	✅	❌	❌	❌
MCP server (AI agents)	✅	❌	❌	❌
A2A protocol	✅	❌	❌	❌
Paper trading	✅	❌	✅	✅
Backtesting	✅	✅	✅	✅
Multi-exchange (12+)	✅	❌	❌	✅
Strategy plugins	✅	✅	❌	✅
No heavy deps (pure NumPy)	✅	❌	❌	❌
Crypto + Stocks + CN Stocks	✅	✅	❌	✅*
Terminal charts	✅	❌	❌	❌
YAML strategy DSL	✅	❌	❌	❌
BTC on-chain metrics	✅	❌	❌	❌
Funding rate dashboard	✅	❌	❌	✅
Lightning Network monitor	✅	❌	❌	❌

---

What You Can Do

📊 Quotes & Analysis

finclaw quote AAPL,MSFT,NVDA        # Multi-ticker quotes
finclaw analyze TSLA --indicators rsi,macd,bollinger,sma50
finclaw chart AAPL --type candle     # Terminal candlestick chart
finclaw news AAPL                    # Financial news
finclaw sentiment TSLA               # Sentiment analysis

🚀 Backtesting

finclaw backtest -t AAPL,MSFT --strategy momentum --start 2023-01-01
finclaw backtest -t NVDA --benchmark SPY    # Compare to benchmark
finclaw strategy list                        # 20+ built-in strategies
finclaw strategy backtest trend-following --symbol AAPL

📋 Paper Trading

finclaw paper start --balance 100000
finclaw paper buy AAPL 50
finclaw paper sell MSFT 20
finclaw paper dashboard
finclaw paper run-strategy golden-cross --symbols AAPL,MSFT

🤖 AI Features

# Generate strategies from plain English or 中文
finclaw generate-strategy "buy when RSI < 30 and MACD golden cross"
finclaw generate-strategy --market crypto --risk high "momentum on volume spike"

# Interactive AI assistant
finclaw copilot
> 分析特斯拉最近走势
> 帮我创建一个均值回归策略

# AI-optimize existing strategies
finclaw optimize-strategy my_strategy.py --data AAPL --period 1y

Supports: OpenAI, Anthropic, DeepSeek, Gemini, Ollama (local), Groq, Mistral, Moonshot.

⛓️ BTC Metrics & Crypto Tools

finclaw btc-metrics                  # On-chain dashboard (hashrate, MVRV, miner outflow)
finclaw funding-rates                # Multi-exchange funding rate comparison + arbitrage
finclaw fear-greed --history 7       # Fear & Greed Index with history

Features:

• BTC On-Chain Metrics — Hashrate, difficulty, mempool, MVRV ratio, miner outflow (via Blockchain.info)
• Multi-Exchange Funding Dashboard — Binance, Bybit, OKX funding rates with arbitrage detection
• Lightning Network Monitor — Network capacity, node count, channel stats (via 1ML.com)
• Fear & Greed Index — Current and historical data (via Alternative.me)
• Liquidation Tracker — Track liquidation events across exchanges
• On-Chain Analytics — Transaction volume, active addresses

🔌 MCP Server (for AI Agents)

Expose FinClaw as tools for Claude, Cursor, VS Code, or OpenClaw:

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

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

📈 Strategy Plugin Ecosystem

# Create a plugin in 5 minutes
finclaw init-strategy my_strategy
cd finclaw-strategy-my_strategy
pip install -e .
finclaw backtest --strategy plugin:my_strategy -t AAPL

# Or use YAML DSL
finclaw strategy create     # Interactive builder
finclaw strategy dsl-backtest my_strategy.yaml --symbol AAPL
finclaw strategy optimize my_strategy.yaml --param rsi_period:10:30:5

Compatible with Backtrader strategies, TA-Lib indicators, and basic Pine Script.

🌐 12+ Exchange Adapters

Crypto: Binance, Bybit, OKX, Coinbase, Kraken (with WebSocket for Binance/Bybit/OKX) US Stocks: Yahoo Finance, Alpaca, Polygon, Alpha Vantage CN Stocks: AkShare, BaoStock, Tushare

finclaw exchanges list               # See all adapters
finclaw exchanges compare yahoo binance alpaca
finclaw quote BTCUSDT --exchange binance
finclaw history ETHUSDT --exchange bybit --timeframe 1h --limit 50

🤝 A2A Protocol (Agent-to-Agent)

FinClaw implements the A2A protocol for inter-agent communication:

finclaw a2a serve --port 8081        # Start A2A server
finclaw a2a card                      # Print agent card

---

Python API

from finclaw import FinClaw

fc = FinClaw()

# Quote
quote = fc.quote("AAPL")
print(f"AAPL: ${quote['price']:.2f} ({quote['change_pct']:+.1f}%)")

# Backtest
result = fc.backtest(strategy="momentum", ticker="NVDA", start="2023-01-01")
print(f"Return: {result.total_return:.1%} | Sharpe: {result.sharpe_ratio:.2f}")

Full API documentation: docs/API.md

---

Architecture

┌──────────────────────────────────────────────────┐
│               User Interfaces                     │
│  CLI  │  MCP Server  │  A2A  │  Copilot  │  API  │
├──────────────────────────────────────────────────┤
│           AI Strategy Engine                      │
│  Generator │ Optimizer │ Copilot Chat │ Pine DSL  │
├──────────────────────────────────────────────────┤
│            Strategy Layer                         │
│   Built-in (20+)  │  Plugins  │  YAML DSL        │
├──────────────────────────────────────────────────┤
│   Backtester  │  Paper Trading  │  Risk Engine    │
├──────────────────────────────────────────────────┤
│              Data Layer                           │
│  Yahoo │ Binance WS │ 12+ Exchanges │  Cache      │
├──────────────────────────────────────────────────┤
│            Crypto Layer                           │
│  BTC Metrics │ Funding Rates │ Lightning │ DeFi   │
└──────────────────────────────────────────────────┘

---

Examples

See examples/ for runnable strategies:

• simple_momentum.py — SMA + RSI momentum strategy
• crypto_rsi.py — Crypto RSI oversold/overbought
• ai_generated.py — BB squeeze mean reversion (AI-generated)

python examples/simple_momentum.py AAPL
python examples/crypto_rsi.py BTC-USD
python examples/ai_generated.py TSLA

---

Contributing

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

See CONTRIBUTING.md for guidelines.

---

License

MIT — Built by Kang Zhou

🔗 NeuZhou Ecosystem

FinClaw is part of the NeuZhou open source toolkit for AI agents:

Project	What it does	Link
repo2skill	Convert any repo into an AI agent skill	GitHub
ClawGuard	Security scanner for AI agents	GitHub
AgentProbe	Behavioral testing framework for agents	GitHub
FinClaw	AI-powered financial intelligence engine	You are here

The workflow: Generate skills with repo2skill → Scan for vulnerabilities with ClawGuard → Test behavior with AgentProbe → See it in action with FinClaw.