Zentra — Bitcoin macro analysis

Full-stack app that scores Bitcoin macro conditions using live data (FRED, Yahoo Finance, news), a deterministic scoring engine, and optional LLM layers (classification, Fed tone, narrative). Not financial advice. Data and labels depend on third-party feeds and chosen time windows (for example MTD vs rolling month).

Stack

• Backend: Python 3.10+, FastAPI (main_v2), SQLite snapshots, RAG (Chroma + OpenAI embeddings)
• Frontend: Next.js 14, TypeScript, Tailwind

Prerequisites

• Python 3.10+ and Node.js 18+
• OpenAI API key (LLM + embeddings)
• FRED API key (free)
• NewsAPI key (optional; improves headline coverage)
• Alpha Vantage key (optional; PMI/news fallback)
• Finnhub key (optional; headline fallback)

Environment

backend/.env (create from scratch; do not commit):

OPENAI_API_KEY=
FRED_API_KEY=
NEWS_API_KEY=
ALPHAVANTAGE_API_KEY=
FINNHUB_API_KEY=
FMP_API_KEY=
EODHD_API_TOKEN=
TRADINGECONOMICS_API_KEY=
BACKEND_PORT=8000
CORS_ORIGINS=http://localhost:3000

Optional: OPENAI_BASE_URL, OPENAI_MODEL, OPENAI_EMBEDDING_MODEL.

Optional monthly performance:

• ENABLE_MONTHLY_METRIC_CACHE=1
• MONTHLY_SLOW_METRIC_CACHE_TTL_SECONDS=43200

Trusted market-provider keys are optional. When set, the backend can use Financial Modeling Prep, EODHD, and TradingEconomics as additional fallbacks for MOVE/VIX/S&P 500/EEM/BTC ETF volume paths.

frontend/.env.local (optional):

NEXT_PUBLIC_API_URL=http://localhost:8000

Quick start

Backend

cd backend
python -m venv venv
# Windows: venv\Scripts\activate
pip install -r requirements.txt
python -m rag.ingest   # builds the local Chroma index from knowledge_base/; re-run after editing those files
python -m main_v2

API base: http://localhost:8000
main_v2 is the supported entrypoint (dashboard uses /api/v2/*). main remains for legacy /api/analyze routes.

Frontend

cd frontend
npm install
npm run dev

App: http://localhost:3000

TradingView Cross-Check

After backend changes, run:

cd backend
python scripts/tradingview_crosscheck_report.py --timeframe month --fresh

It saves .json and .md comparison reports to backend/logs/.

Render Keep-Warm

Use .github/workflows/render-keepalive.yml with repository secret KEEPALIVE_URL pointing to your deployed /api/keepalive endpoint.

Windows

You can use start.bat / setup_and_run.bat in the repo root if you already use them; ensure backend/.env exists first.

Main API (v2)

Method	Path	Purpose
POST	/api/v2/analyze	Run analysis
GET	/api/v2/analyze/{timeframe}	Analysis for a timeframe
GET	/api/v2/analyze/compare	Compare runs
GET	/api/v2/history	List snapshots
GET	/api/v2/history/{snapshot_id}	One snapshot
GET	/api/v2/config	Effective config
GET	/api/health	Health

Project layout

backend/   FastAPI, agents, data_fetchers, scoring_engine, rag/, storage/
frontend/  Next.js app, components, lib/api.ts

SQLite snapshots live under backend/storage/ (see storage/db.py).

License

Educational / personal use unless you add your own terms.