Market Candlestick & AI Pattern Scanner (yfinance-ta-patterns)

High-performance Python library, CLI, and Native MCP Server (yfinance-ta-mcp) that downloads multi-asset market data via yfinance, detects TA-Lib candlestick patterns, and enriches raw signals using an AI/Quant Confluence Engine to generate multi-factor confluence scores (deterministic quantitative confluence heuristic, not uncalibrated win-rate probability), trade setups, and LLM-ready market briefs.

Universal runtime compatibility across CPython 3.8 to 3.16, free-threaded No-GIL 3.13t to 3.16t, PyPy 3.8 to 3.12 with high-speed JIT tracing, and legacy Windows 7+ support, installed directly from PyPI with zero compilation required.

Key Features

• Multi-Asset Data Loader: Universal fetching and candle normalization for stocks (AAPL, NVDA), crypto (BTC-USD), commodities (GC=F), indices (^GSPC), and forex pairs (EURUSD). Supports custom date ranges (start, end), timezone conversion, UTC-anchored 4h resampling, and raw OHLC integrity validation.
• TA-Lib Pattern Detection: Full recognition engine across all 61 canonical TA-Lib candlestick patterns via native C TA-Lib OR built-in pure-Python / NumPy fallback engine (all 61 patterns supported in both modes!).
• AI Pattern Confluence Scorer: Multi-factor confluence score ($0.0 - 1.0$) evaluating quantitative confluence (deterministic heuristic, not win-rate probability):
  • Multi-EMA trend alignment (20, 50, 200 EMA) with safe warm-up handling
  • Zero-lookahead Relative Volume surge (RVOL)
  • Canonical Wilder's RSI (14) momentum exhaustion & divergence
  • Canonical Wilder's ATR (14) volatility expansion & candle body dominance
• Automated Trade Setups: Computes entry price, ATR-based invalidation stop-loss, and multi-tier take-profit targets (1.5x / 3.0x risk/reward).
• AI Market Analyst & LLM Integration: Generates executive markdown briefs, JSON payloads, and engineered prompts tailored for external AI agents (GPT-4o, Claude 3.5, Gemini, Ollama).
• Quantitative Pattern Ranking & Backtesting: Unbiased next-open execution (Open[i+1]), symmetric Long/Short trading, universal FX quote-currency conversion, transaction cost modeling (commissions & slippage), overfitting filters (min_signals), and periodic Sharpe ratio accounting for non-trading hold periods.

🧩 Universal Compatibility Matrix

Quick start

1. Installation

yfinance-ta-patterns installs in seconds with zero C build requirements by default, using an internal vectorized pure-Python/NumPy engine for candlestick pattern recognition.

🚀 Quick Installation by Platform

Option A: Using uv (Fastest & Recommended)

# 1. Full institutional setup with all extras (TA-Lib + Scikit-Learn repair + AI):
uv add "yfinance-ta-patterns[all]"

# 2. Standard install (pure-Python fallback, zero C compiler required):
uv add yfinance-ta-patterns

# 3. Instant execution without installing into environment:
uvx --from yfinance-ta-patterns yftp --all-patterns --symbol AAPL --timeframe 1h --ai

Option B: Using Standard pip

# Standard install (pure-Python fallback by default):
pip install yfinance-ta-patterns

# Optional: With native C TA-Lib acceleration (requires ta-lib C headers):
pip install "yfinance-ta-patterns[talib]"

Option C: Native C TA-Lib on Linux & macOS (Optional)

• macOS (Homebrew):

  brew install ta-lib
  export TA_INCLUDE_PATH="$(brew --prefix)/include"
  export TA_LIBRARY_PATH="$(brew --prefix)/lib"
  uv pip install ta-lib
  

• Linux (Ubuntu / Debian / Arch):

  # Ubuntu / Debian:
  sudo apt-get update && sudo apt-get install -y libta-lib0 libta-lib-dev
  # Arch Linux:
  yay -S ta-lib
  
  # Then install the python wrapper:
  uv pip install ta-lib
  

🐍 Python Version Compatibility Matrix

🤖 Native MCP (Model Context Protocol) Server

Connect yfinance-ta-patterns directly to Claude Code, Antigravity, Claude Desktop, Cursor, or Windsurf via the built-in yfinance-ta-mcp JSON-RPC 2.0 server (ta_scan_symbol, ta_scan_watchlist, ta_backtest_patterns, ta_list_patterns, ta_get_economic_calendar):

• Latest Protocol Spec (2025-11-25): Full MCP lifecycle version negotiation supporting 2024-11-05, 2025-03-26, 2025-06-18, and 2025-11-25.
• Institutional Tool Metadata: Includes human-readable title, annotations (readOnlyHint: true, openWorldHint), and detailed JSON outputSchema for every tool.
• Token-Optimized Output: Emits raw UTF-8 without token-wasting \uXXXX escaping for Cyrillic and currency symbols (€, £, ¥). ta_scan_watchlist features compact: true by default to comfortably remain below Claude Code's 10,000-token tool output threshold.
• Verified Macro Calendar: ta_get_economic_calendar retrieves live macroeconomic events mapped to asset currencies with explicit UTC timestamps, returning clean source: "unavailable" when feeds are offline (zero mock/hallucinated macroeconomic data).

Option 1: Claude Code CLI

# Recommended: install once as a global tool (~0.4s instant startup, avoids uvx cold timeouts)
uv tool install yfinance-ta-patterns
claude mcp add yfinance-ta -- yfinance-ta-mcp

# Or zero-install execution via uvx (pinned version recommended for reproducibility):
claude mcp add yfinance-ta -- uvx --from "yfinance-ta-patterns>=0.3.49" yfinance-ta-mcp

Option 2: Antigravity / Claude Desktop / Cursor / Windsurf (mcp_config.json)

{
  "mcpServers": {
    "yfinance-ta": {
      "command": "yfinance-ta-mcp"
    }
  }
}

Or zero-install via uvx:

{
  "mcpServers": {
    "yfinance-ta": {
      "command": "uvx",
      "args": ["--from", "yfinance-ta-patterns", "yfinance-ta-mcp"]
    }
  }
}

🚀 Ready-to-Use Examples (examples/)

The repository includes production-ready backtesting and real-time scanning scripts in the examples/ directory:

1. Multi-Pair Historical Backtesting (examples/multi_pair_backtest.py)

A rigorous multi-pair portfolio backtest across 6 major and cross Forex pairs (EURUSD, GBPUSD, USDJPY, AUDUSD, EURGBP, EURJPY) over 2 years on hourly (1h) candles.

Key capabilities demonstrated:

• Unbiased Execution: Fills trades at Open[i+1] (next candle open) to eliminate lookahead bias.
• Fixed Holding Period (holding_period=5): Automatically closes trades after 5 bars. Essential for single-direction candlestick patterns (Hammer, Inverted Hammer, 3 White Soldiers) which otherwise hold positions indefinitely without reverse exit signals.
• Universal Forex PnL & Position Sizing: Automatic base-currency normalization for USD-base pairs (USDJPY) and cross-rates (EURGBP), applying commissions in account currency ($0.05 ECN micro-lot).
• Composite Scoring: Ranks combinations by combining Win Rate, Profit Factor, Sharpe Ratio, and logarithmic trade volume.

# Run with Python:
python examples/multi_pair_backtest.py

# Or run with uv:
uv run examples/multi_pair_backtest.py

Sample Output:

==================================================================================================
 TOP-10 BEST COMBINATIONS (PAIR + PATTERN) OVER 2y:
==================================================================================================
  Pair        Pattern  Signals WinRate TotalPnL  ProfitFactor  Sharpe  MaxDD MaxDD_%
EURJPY INVERTEDHAMMER       82   63.0%  $+55.34          2.55    0.38  $7.11   0.07%
EURJPY    MORNINGSTAR       46   63.0%  $+21.49          2.66    0.34  $2.87   0.03%
EURUSD         INNECK       12   75.0%   $+6.31          3.81    0.25  $1.14   0.01%
EURUSD STALLEDPATTERN       26   65.4%  $+23.44          3.09    0.29  $5.17   0.05%
EURUSD  STICKSANDWICH        8   62.5%   $+8.13          5.01    0.22  $1.00   0.01%
EURUSD         ONNECK       11   63.6%  $+11.53          4.44    0.17  $1.97   0.02%
USDJPY    MATCHINGLOW      195   55.6%  $+50.36          1.40    0.24 $15.09   0.15%
EURJPY GRAVESTONEDOJI      226   52.4%  $+58.74          1.44    0.24 $20.81   0.21%
EURJPY        HIKKAKE     1604   52.7%  $+50.97          1.06    0.09 $75.80   0.76%
USDJPY       BELTHOLD     1596   47.7%  $+78.87          1.09    0.13 $83.89   0.84%

Full ranked report saved to: all_pairs_ranked.csv

2. Live Multi-Asset Signal Scanner (examples/live_signals_scanner.py)

Scans a 12-asset watchlist across Forex and Cryptocurrencies (BTC-USD, ETH-USD) for active candlestick patterns over recent candles, scoring each opportunity with the AI Confluence Engine.

Key capabilities demonstrated:

• AI Confluence Scoring: Quantifies trend alignment (EMA 20/50/200), volume expansion, and Wilder RSI (14) momentum into a 0–100% confidence score.
• Automated Trade Setups: Calculates exact Entry Price, ATR-based Stop Loss, and Take Profit targets (1:1.5 Risk/Reward ratio).
• Automated Opportunity Ranking: Sorts all live setups and highlights the TOP-1 Highest Confidence Trade Setup.

# Run with Python:
python examples/live_signals_scanner.py

# Or run with uv:
uv run examples/live_signals_scanner.py

Sample Output:

=========================================================================================================
 SIGNALS FOUND: 26 (Ranked by AI Confluence / Quality)
=========================================================================================================
       Time  Symbol Direction        Pattern Confluence     Grade        Entry     StopLoss  TakeProfit_1 Risk_Reward          Trend
08.09 19:00 ETH-USD       BUY 3WHITESOLDIERS   80.0/100 EXCELLENT  2499.389893  2483.227621   2523.633300       1:1.5        BULLISH
08.09 17:00  EURUSD       BUY 3WHITESOLDIERS   70.0/100    STRONG     1.163332     1.162101      1.165178       1:1.5 STRONG_BULLISH
08.09 17:00  USDCAD      SELL     HANGINGMAN   70.0/100    STRONG     1.377840     1.378940      1.376190       1:1.5 STRONG_BEARISH

**********************************************************
 TOP-1 SIGNAL: ETH-USD — BUY (3WHITESOLDIERS)
 Candle Time: 08.09 19:00 | Confluence: 80.0/100 [EXCELLENT] (deterministic heuristic, not win probability)
 Market Trend: BULLISH | RSI: 56.3
 Entry Price: 2499.39
 Stop Loss:   2483.23
 Take Profit: 2523.63 (R:R 1:1.5)
**********************************************************

2. Run CLI

# 1. Multi-Currency Portfolio Scanner (automatically scans all 56 Forex pairs without specifying --symbol):
yftp --timeframe 5m --period 30d --all-patterns --ai-analyst

# 2. Or explicitly scan all 56 pairs with custom confluence threshold:
yftp --all-pairs --timeframe 1h --period 60d --ai --min-confidence 0.60

# 3. Scan a custom comma-separated portfolio of symbols:
yftp --symbol EURUSD,GBPUSD,USDJPY --timeframe 15m --ai

# 4. Single symbol AI-scored analysis with Executive Brief:
yftp --symbol GBPUSD --timeframe 5m --period 30d --all-patterns --ai-analyst

# 5. Detect a single pattern with classic output:
yftp --pattern HAMMER --symbol AAPL --timeframe 1h --period 60d

# 6. Generate an LLM-ready prompt template for GPT-4o / Claude:
yftp --all-patterns --symbol EURUSD --timeframe 1h --period 60d --prompt

CLI Reference

yfinance-ta-patterns [-h] [-v] (--pattern PATTERN | --all-patterns)
                     [--symbol SYMBOL] [--period PERIOD] [--timeframe TIMEFRAME]
                     [--date YYYY-MM-DD] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD]
                     [--execution {next_open,close}] [--min-signals MIN_SIGNALS]
                     [--commission COMMISSION] [--slippage SLIPPAGE] [--auto-adjust]
                     [--ai] [--min-confidence MIN_CONFIDENCE]
                     [--ai-analyst] [--prompt] [--format {text,json,markdown}]

Options

Python API

1. Universal Multi-Asset Data Loader (MarketDataLoader)

Fetches and normalizes OHLC data across equities, crypto, forex, and commodities:

from yfinance_ta_patterns import MarketDataLoader

# Stocks
loader = MarketDataLoader(symbol="NVDA", period="60d", interval="1h")
df = loader.get_data()

# Crypto
crypto_loader = MarketDataLoader(symbol="BTC-USD", period="30d", interval="15m")
crypto_df = crypto_loader.get_data()

# Forex (ForexDataLoader is fully compatible alias)
from yfinance_ta_patterns import ForexDataLoader

forex_loader = ForexDataLoader(symbol="EURUSD", period="60d", interval="1h")
forex_df = forex_loader.get_data()

2. AI Pattern Confidence Scorer (AIPatternScorer)

Evaluates technical confluence (trend, momentum, volume, volatility) and builds complete risk-managed trade setups:

from yfinance_ta_patterns import MarketDataLoader, AIPatternScorer

# Use period="2y" (or >= 200 daily candles) to ensure complete EMA200 indicator warm-up
data = MarketDataLoader("AAPL", period="2y", interval="1d").get_data()

scorer = AIPatternScorer(data)
scored_signals = scorer.score_all_active(min_confidence=0.60)

for sig in scored_signals:
    print(f"Pattern: {sig.pattern_name}")
    print(f"Confidence: {sig.confidence * 100:.1f}% ({sig.grade.value})")
    print(f"Action: {sig.action}")
    if sig.setup:
        print(f"Entry: {sig.setup.entry_price:.2f}")
        print(f"Stop Loss: {sig.setup.stop_loss:.2f}")
        print(f"Target 1: {sig.setup.take_profit_1:.2f} (R:R {sig.setup.risk_reward_ratio:.1f})")
    print("Confluences:", ", ".join(sig.confluences))
    print("-" * 40)

3. AI Market Analyst & LLM Prompting (AIMarketAnalyst)

Generates structured briefs and prompt templates for external LLM reasoning agents:

from yfinance_ta_patterns import MarketDataLoader, AIMarketAnalyst

data = MarketDataLoader("BTC-USD", period="30d", interval="4h").get_data()

analyst = AIMarketAnalyst(data, symbol="BTC-USD")
results = analyst.analyze(min_confidence=0.65)

# 1. Executive Markdown Brief
brief = analyst.generate_brief(results)
print(brief)

# 2. Prompt for GPT-4o / Claude / Local LLM
llm_prompt = analyst.to_llm_prompt(results)

# 3. JSON Payload for APIs / Microservices
json_data = analyst.to_json(results)

4. Quantitative Backtesting & Pattern Ranking (PatternRankingTester)

Tests all candlestick patterns and ranks them by quantitative performance metrics:

from yfinance_ta_patterns import MarketDataLoader, PatternRankingTester

data = MarketDataLoader("EURUSD", period="60d", interval="1h").get_data()

tester = PatternRankingTester(
    data,
    symbol="EURUSD",
    initial_capital=10000.0,
    position_size=1000.0,
    execution="next_open",  # Unbiased: enters on Open of bar i+1
    allow_short=True,  # Full symmetric short trades on bearish signals
    commission=1.50,  # Transaction fee per trade
    slippage=0.0001,  # Execution slippage in price units
    min_signals=5,  # Exclude patterns with < 5 signals (reduces overfitting)
    sharpe_mode="periodic",  # Accounts for 0% returns during idle hold periods
)
results = tester.test_all_patterns(min_signals=5)

top_patterns = tester.get_top_patterns(5)
for r in top_patterns:
    print(
        f"{r.pattern_name}: Win Rate={r.win_rate:.1f}%, PnL=${r.total_pnl:.2f}, "
        f"Periodic Sharpe={r.periodic_sharpe:.2f}, MaxDD=${r.max_drawdown:.2f}, "
        f"Strength={r.avg_strength:.0f}"
    )

# Export comparison report across news filters
report_df = tester.get_comparison_report()
print(report_df)

Development & Testing

Run the test suite and quality checks:

# Run pytest across full test suite (429 tests)
uv run --extra dev pytest -v
# or with standard pytest
pytest -v

# Linter and formatting check
uv run --extra dev ruff check .
uv run --extra dev ruff format --check .

# Static type check
uv run --extra dev mypy yfinance_ta_patterns

# Build source distribution and binary wheel
uv build

All 435 tests pass with 100% success rate across Python 3.8 through 3.16 (including No-GIL free-threaded 3.13t–3.16t) and PyPy 3.8 through 3.12.

🌐 High-Performance Systems Ecosystem

yfinance-ta-patterns is developed by @eminsk as part of an open-source engineering ecosystem:

• ⚡ NanoVector — Bare-metal C99/AVX2 vector search & episodic memory engine (~120KB) with Native MCP Server (pip install nanovector).
• 🧠 AgentJIT — Just-In-Time Compiler for AI Agent Trajectories with speculative de-optimization guards (pip install agentjit).
• ⚡ NanoGEMM — Minimalist, bare-metal AVX2+FMA SIMD matrix multiplication engine in ~100KB for sub-microsecond CPU neural network inference (pip install nanogemm).
• 🖥️ NanoRecall — 100% Private, offline desktop memory & semantic screen search engine powered by NanoVector (pip install nanorecall).
• 🛒 avito-sdk — Headless Avito scraping & data extraction SDK with price drop tracking, Playwright cookies, Telegram/VK bots, and Native MCP Server (pip install avito-sdk).
• 📊 xlsx_vievers — Headless Excel formula engine (129+ functions), desktop spreadsheet processor, SIMD SSE2 math engine, and Native MCP Server (pip install xlsx-viewer-pro).
• 🎥 screenvideo — Lightweight desktop screen recorder with WASAPI audio and a standalone pure x64 Flat Assembler (FASM) native edition.

License

MIT License. See LICENSE for details.