Cryptocurrency price analysis relative to Bitcoin halving cycles.
Halvix analyzes cryptocurrency performance across BTC halving cycles (2nd through 5th), comparing each coin's price action against the TOTAL2 market index (volume-weighted index of top altcoins).
- 📊 Retrieve and analyze top 1200 cryptocurrencies by market cap
- 🔍 Filter out wrapped, staked, bridged tokens and stablecoins
- 📉 Volume-weighted TOTAL2 index with 21-day freeze period and price scaling
- 📈 Compare altcoin price performance across 2nd to 5th BTC halving cycles
- 🎯 Cycle pattern analysis with 4 projection methods (trendline, Fibonacci, diminishing returns, historical peak)
- 🏆 Composite ranking of altcoins by projected return with confidence scoring
- 🎨 Interactive Plotly charts with normalized values
- 🧩 Composition viewer to explore TOTAL2 makeup on any date
Halvix sources prices through a small provider abstraction: CoinGecko (full coin coverage + native market-cap ranking) is preferred, with CryptoCompare as an alternative, and the backend is auto-selected from whichever API key is set (a free CoinGecko Demo key is recommended). See docs/DATA_SOURCES.md for the full selection rules and provider comparison.
Local setup: copy .env.example to .env and paste your key — it is
gitignored and loaded automatically:
cp .env.example .env
# then edit .env: COINGECKO_API_KEY=your_demo_keyReal environment variables and GitHub Actions secrets take precedence over
.env, so CI is unaffected (set COINGECKO_API_KEY as a repo secret there).
# Install
poetry install
# Fetch and filter coins
poetry run python -m main list-coins
# Fetch price data (BTC and USD)
poetry run python -m main fetch-prices
# Calculate TOTAL2 index
poetry run python -m main calculate-total2
# Generate halving cycle charts
poetry run python -m main generate-cycle-charts
# Analyze cycle patterns
poetry run python -m main analyze-patterns
# Check status
poetry run python -m main status📖 See Tutorial for detailed step-by-step instructions.
- Charts Dashboard - Interactive halving cycle charts (BTC, TOTAL2)
- AI Agent Context - Full project specification for AI agents and developers
- Data Sources - Provider abstraction (CoinGecko default, CryptoCompare alternative), rate limits, caching, data pipeline
- TOTAL2 Calculation - How the TOTAL2 market index is calculated
- Identification Kernel - Segment-based cycle point detection algorithm
- Pattern Analysis - Cycle pattern analysis and price target projections
- Deployment - Charts generation and GitHub Pages deployment workflow
- Changelog - Version history and release notes