Quick Start · Desktop App · CLI · Patterns · ML · Docs
Warning
Educational and research use only. CryptVault is not financial advice and must not be used for live trading decisions. Past performance does not guarantee future results. You are solely responsible for any investment outcomes.
CryptVault is a research-grade analysis platform for crypto and equities that combines:
- 🖥️ A native desktop terminal with candlestick charts, drawn pattern overlays, and ML predictions side-by-side.
- 🧠 A production ML ensemble (67+ engineered features, validation-weighted stacking) achieving 1.6–2.4% MAPE on major pairs.
- 🔍 50+ classical patterns across 7 categories — all drawn as actual geometric shapes, not just markers.
- 🤖 Reinforcement-learning agents (DQN, PPO, Transformer) for trading research.
- 🛠️ A clean Python API, CLI, and portfolio tools.
| Area | What's new |
|---|---|
| CI/CD | Ruff-first lint pipeline, zero-flake rules, faster parallel tests (pytest -n auto). |
| Code quality | Fixed latent F821 / F402 bugs; project is now ruff-clean. |
| README & docs | Scannable layout, badge row, pattern quick reference, one-page install. |
| Pattern rendering | Double Top/Bottom, H&S, Triangles, Wedges drawn as lines/necklines on chart. |
| Desktop UX | Analysis panel always visible; no stale tabs; cleaner indicator stack. |
Full history: docs/CHANGELOG.md.
git clone https://github.com/MeridianAlgo/Cryptvault.git
cd Cryptvault
pip install -r requirements.txtVerify:
python -c "import cryptvault; print(cryptvault.__version__)"Run the desktop terminal:
python launch_desktop.pyA dark-themed trading terminal with three synchronized surfaces — chart, patterns, and ML.
┌────────────────────────────────────────────────────────────────┐
│ CryptVault 6.1 [BTC-USD] [Analyze] 1D 5D 1M 3M 6M 1Y YTD │
├────────────┬──────────────────────────────────┬────────────────┤
│ │ │ ML PREDICTION │
│ Chart │ 📈 Candlestick + Patterns │ ──────────── │
│ │ 📊 Bollinger Bands │ │
│ Analysis │ 📉 Volume · RSI │ DETECTED │
│ │ │ PATTERNS │
│ History │ (pattern shapes drawn live) │ (scrollable) │
├────────────┴──────────────────────────────────┴────────────────┤
│ Status: connected · last fetch 2s · 120 candles · 12 patterns │
└────────────────────────────────────────────────────────────────┘
| Pattern | Rendered as |
|---|---|
| Double Top / Bottom | Peak-to-peak line + dashed neckline |
| Head & Shoulders | LS → Head → RS connectors + neckline |
| Triple Top / Bottom | Three-pivot polyline |
| Triangles (Sym/Asc/Desc) | Fitted upper + lower trendlines |
| Rising / Falling Wedge | Converging trendlines |
| Any pattern with target | Dotted horizontal target line |
| Candlestick | ▲ bullish / ▼ bearish marker |
See docs/DESKTOP_APP.md.
# Analyze Bitcoin with chart
python cryptvault_cli.py BTC 60 1d
# Save chart to file
python cryptvault_cli.py ETH 120 1d --save-chart eth.png
# Text-only analysis
python cryptvault_cli.py SOL 90 1d --no-chart
# Portfolio
python cryptvault_cli.py --portfolio BTC:0.5 ETH:10 SOL:50
# Compare assets
python cryptvault_cli.py --compare BTC ETH SOL
# Interactive REPL
python cryptvault_cli.py --interactivepython cryptvault_cli.py SYMBOL [DAYS] [INTERVAL] [OPTIONS]
| Option | Description |
|---|---|
--no-chart |
Text-only output |
--save-chart FILE |
Save chart as PNG |
--verbose |
Detailed diagnostics |
--desktop |
Launch desktop app |
--portfolio A:X B:Y ... |
Portfolio analysis |
--compare S1 S2 ... |
Side-by-side comparison |
--interactive |
REPL mode |
--status |
API & data source health |
--demo |
Run demonstration dataset |
--version / --help |
Info |
50+ classical patterns across 7 categories. Full reference: docs/PATTERNS.md.
Reversal (8) — Head & Shoulders, Inverse H&S, Double/Triple Top & Bottom, Rising/Falling Wedge
Detected via local pivot extraction, neckline fitting, and symmetry scoring. Drawn with the actual peak/trough connectors plus a dashed neckline and projected target.
Continuation — Triangles (Sym/Asc/Desc), Bull/Bear Flag, Pennants, Cup & Handle
Trendline regression on swing highs and swing lows; convergence and slope tests determine the sub-type. Targets projected from breakout range.
Candlestick — Doji (3 variants), Hammer, Hanging Man, Inverted Hammer, Shooting Star, Engulfing, Harami, Piercing, Dark Cloud, Morning/Evening Star, Three Soldiers/Crows
Body/wick ratio analysis with trend-context filters. Rendered as ▲ or ▼ above/below the candle.
Harmonic — Gartley, Butterfly, Bat, Crab, Shark, Cypher
Fibonacci ratio validation between swing points (XABCD structure) with per-pattern tolerance bands.
Divergence — RSI & MACD Bullish/Bearish
Peak/trough alignment between price and oscillator detects hidden and regular divergence.
Ensemble — each base learner weighted by rolling out-of-fold validation:
| Model | Role |
|---|---|
| Random Forest | Non-linear baseline, robust to noise |
| Gradient Boosting | Sequential residual refinement |
| SVR | Small-sample non-linear regression |
| Ridge / Lasso / ElasticNet | Stable linear anchors |
| ARIMA | Explicit time-series baseline |
| XGBoost / LightGBM (optional) | High-capacity boosting |
Stacked via a meta-learner on validation residuals.
| Metric | Range |
|---|---|
| Average MAPE | 1.6 – 2.4 % |
| Direction accuracy | 100 % on tested symbols |
| Predictions within ±2 % | 80 – 100 % |
| R² | 0.50 – 0.81 |
Tested on BTC, ETH, SOL, BNB — 120-day windows.
State-of-the-art RL agents for trading research (not for live trading):
- DQN — dueling, noisy nets, prioritized replay
- PPO — with GAE
- Transformer — multi-head attention policy
Cryptvault/
├── cryptvault/
│ ├── desktop/ # Native Tk GUI (app, panels, theme)
│ ├── patterns/ # 50+ pattern detectors (7 categories)
│ ├── ml/ # Ensemble + feature engineering
│ ├── rl/ # DQN / PPO / Transformer agents
│ ├── data/ # Market data fetch & caching
│ ├── visualization/ # Chart rendering
│ ├── portfolio/ # Multi-asset analytics
│ └── security/ # Input validation & sanitization
├── docs/ # Full documentation
├── tests/ # pytest suite (unit + integration)
├── cryptvault_cli.py # CLI entry point
├── launch_desktop.py # Desktop launcher
└── pyproject.toml # Tooling config (ruff, bandit, pytest)
| Minimum | Recommended | |
|---|---|---|
| Python | 3.9 | 3.11+ |
| RAM | 4 GB | 8 GB |
| Disk | 2 GB | 5 GB |
| Network | Required (data fetch) | — |
Platforms: Windows 10/11 · Ubuntu 20.04+ · macOS 10.15+ (including Apple Silicon).
# Install dev tooling
pip install -r requirements.txt
pip install ruff bandit pytest pytest-cov pytest-xdist
# Lint (same command CI uses)
ruff check cryptvault/ cryptvault_cli.py
ruff format cryptvault/ cryptvault_cli.py
# Security scan
bandit -c pyproject.toml -r cryptvault/ -ll
# Tests (parallel)
pytest tests/ -n auto --cov=cryptvault --cov-report=termThe project is ruff-clean as of v6.1.0 — CI blocks on ruff violations.
| Doc | About |
|---|---|
| Desktop App | Full GUI walkthrough |
| Patterns | Every detector, how it works |
| Architecture | System design & data flow |
| API Reference | Python API |
| Performance | Benchmarks & tuning |
| Deployment | Packaging & distribution |
| Troubleshooting | Common issues |
| Security | Disclosure policy |
| Changelog | Version history |
| Contributing | How to contribute |
- Fork and branch from
main. pip install -r requirements.txt- Write tests first (pytest).
ruff checkmust pass.- Open a PR with a clear description.
See docs/CONTRIBUTING.md and CODE_OF_CONDUCT.md.
MIT — see LICENSE.
Built with: scikit-learn · yfinance · NumPy · pandas · SciPy · Matplotlib · XGBoost · LightGBM.
Maintained by MeridianAlgo — a research organization focused on open-source financial ML. Not a licensed broker or financial advisor.
Version 6.1.0 · Last updated April 2026 · Built for researchers, by researchers.