# bitcoin-risk-brief [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/akarazhev/bitcoin-risk-brief  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/bitcoin-risk-brief

## Description
Daily Bitcoin risk with freshness state on every response. Research context, not advice.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "bitcoin-risk-brief": {
    "command": "npx",
    "args": ["-y","bitcoin-risk-brief"]
  }
}
```

## Documentation & README

# Bitcoin Risk Brief

Bitcoin Risk Brief is a free, open-source product that turns canonical daily BTC/USD data into a transparent risk score, freshness state, and scenario price ladder. It is free permanently: no paid tier, no accounts, no SLA. The owned source code, documentation, and configuration are Apache-2.0; bundled third-party BTC/USD market data is not.

[![CI](https://github.com/akarazhev/bitcoin-risk-brief/actions/workflows/ci.yml/badge.svg)](https://github.com/akarazhev/bitcoin-risk-brief/actions/workflows/ci.yml) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE) [![Live site](https://img.shields.io/website?url=https%3A%2F%2Fbitcoinriskbrief.minihub.app%2F&label=live%20site)](https://bitcoinriskbrief.minihub.app/)

![Bitcoin Risk Brief first viewport with current risk and readiness](https://raw.githubusercontent.com/akarazhev/bitcoin-risk-brief/HEAD/docs/assets/bitcoin-risk-brief-first-viewport.png)

_First viewport captured on 2026-08-09; the values shown are a point-in-time example._

Live product: [bitcoinriskbrief.minihub.app](https://bitcoinriskbrief.minihub.app/)

Check readiness before using any current value:

```bash
curl --fail --silent --show-error https://bitcoinriskbrief.minihub.app/api/readiness
```

Response captured on 2026-08-09:

```json
{
  "status": "ready",
  "checks": {
    "risk_data_available": true,
    "validation_available": true,
    "risk_range_ok": true,
    "validation_has_rows": true,
    "latest_matches_validation_end": true,
    "source_is_canonical": true,
    "data_fresh": true
  },
  "data": {
    "latest_date": "2026-08-08",
    "covered_end": "2026-08-08",
    "data_age_days": 1,
    "max_age_days": 2,
    "source": "coinmarketcap_csv",
    "row_count": 5871,
    "methodology_version": "crypto-scout-canonical-v1.1"
  }
}
```

## What it does

- Computes a daily `0.0`–`1.0` Bitcoin risk metric from the canonical `collector/btc-csv/btc_usd_daily.csv` history.
- Shows the latest `low`, `neutral`, or `high` state alongside a two-year risk history chart.
- Displays completed-candle HLC3 model price context and a risk-level scenario ladder in `0.025` increments.
- Publishes a daily brief in English, Russian, Simplified Chinese, German, French, Spanish, and Arabic.
- Exposes read-only analytics endpoints and accepts email waitlist contacts server-side, never in browser storage; users should not submit sensitive information.

## What makes it different

- **Visible freshness and readiness.** The UI shows the latest completed day and validation state; `/api/readiness` returns HTTP 503 when freshness or validation checks fail.
- **Deterministic and reproducible.** A versioned methodology recomputes the metric from the same canonical daily history, with validation metadata recording each import.
- **Scenarios, not forecasts.** The price ladder runs hypothetical prices through the same model to show where risk levels would change; it is not a prediction or trading instruction.

## Current Status

Current operational status, evidence, and accepted limitations: [Production Readiness](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/docs/operations/production-readiness.md).

## For AI agents

Start with the repository [llms.txt](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/frontend/public/llms.txt). This branch defines the machine-readable [`/api/openapi.json`](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/backend/app/main.py) endpoint; deployment remains pending operator work. Use the [Agent Access Pack](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/docs/agents/agent-access-pack.md) for endpoint examples, cache semantics, and interpretation boundaries.

Agents must call `/api/readiness` first, bind reported values to its dates and freshness state, and preserve the analytics-not-advice framing.

## Architecture

| Service | Stack | Purpose |
| --- | --- | --- |
| `timescaledb` | TimescaleDB/PostgreSQL | BTC OHLCV, risk rows, validation state, brief snapshots, waitlist leads |
| `data-collector` | Python, asyncpg, APScheduler, httpx | Daily CSV refresh, full CSV import, risk recomputation |
| `backend` | FastAPI, asyncpg | API, readiness, waitlist storage, risk and brief reads |
| `frontend` | React, Vite, ECharts, nginx | Public seven-locale interface and API proxy |

```mermaid
flowchart LR
    Source[CoinMarketCap public download<br/>or optional API] --> CSV[Canonical BTC daily CSV]
    Schedule[Daily collector schedule] --> Collector[data-collector]
    CSV --> Collector
    Collector --> DB[(TimescaleDB)]
    DB --> API[FastAPI backend]
    API --> UI[React frontend]
    API --> Agents[AI agents and API clients]
```

The canonical CSV remains the durable source of truth; the collector refreshes and validates it, recomputes risk, and writes the daily snapshot consumed by the API.

## Quick Start

```bash
cp .env.example .env
./scripts/manage.sh validate
./scripts/manage.sh start
./scripts/manage.sh migrate
./scripts/manage.sh backfill
```

Open: `http://localhost:3001`

## Documentation

- [Documentation index](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/docs/index.md)
- [Product overview](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/docs/product/overview.md)
- [Risk methodology](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/docs/product/risk-methodology.md)
- [Architecture](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/docs/engineering/architecture.md)
- [API reference](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/docs/engineering/api-reference.md)
- [Freshness and validation](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/docs/engineering/freshness-and-validation.md)
- [Agent documentation](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/docs/agents/index.md)
- [Operations and production evidence](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/docs/operations/production-readiness.md)

## Disclaimer and licence

Bitcoin Risk Brief provides analytics and research context only. It is not financial advice, investment advice, a price forecast, or a trading recommendation.

Owned source code, documentation, and configuration are licensed under [Apache-2.0](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/LICENSE). Bundled third-party BTC/USD market data remains subject to source-provider terms; see [NOTICE](https://github.com/akarazhev/bitcoin-risk-brief/blob/HEAD/NOTICE).