{"id":49351240,"url":"https://github.com/lukius/cryptodash","last_synced_at":"2026-05-04T07:06:24.450Z","repository":{"id":354097394,"uuid":"1222135126","full_name":"lukius/cryptodash","owner":"lukius","description":"Self-hosted personal crypto portfolio dashboard for Bitcoin and Kaspa — no accounts, no private keys, no cloud.","archived":false,"fork":false,"pushed_at":"2026-04-27T05:18:18.000Z","size":609,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-27T10:05:13.783Z","etag":null,"topics":["bitcoin","fastapi","kaspa","portfolio","self-hosted","vue3"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukius.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T04:34:27.000Z","updated_at":"2026-04-27T05:16:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lukius/cryptodash","commit_stats":null,"previous_names":["lukius/cryptodash"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lukius/cryptodash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukius%2Fcryptodash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukius%2Fcryptodash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukius%2Fcryptodash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukius%2Fcryptodash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukius","download_url":"https://codeload.github.com/lukius/cryptodash/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukius%2Fcryptodash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32597981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoin","fastapi","kaspa","portfolio","self-hosted","vue3"],"created_at":"2026-04-27T10:02:01.610Z","updated_at":"2026-05-04T07:06:24.259Z","avatar_url":"https://github.com/lukius.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"frontend/public/favicon.svg\" width=\"80\" alt=\"CryptoDash\"\u003e\n\u003c/p\u003e\n\n# CryptoDash\n\nA self-hosted personal cryptocurrency portfolio dashboard. Track wallet balances and portfolio value across Bitcoin and Kaspa — no account registration, no private keys, no third-party cloud required.\n\n## Features\n\n- **Multi-wallet tracking** — add any number of Bitcoin and Kaspa addresses; balances are fetched from public blockchain APIs\n- **HD wallet support** — add an extended public key (xpub / ypub / zpub) to track an entire hierarchical-deterministic wallet with per-address breakdown\n- **Portfolio dashboard** — total USD value, per-currency balances, composition pie chart, and historical value chart\n- **Price history** — BTC/USD and KAS/USD charts sourced from CoinGecko\n- **Wallet detail view** — per-wallet balance history and full transaction timeline\n- **Background refresh** — configurable auto-refresh interval (default 5 min); manual refresh on demand\n- **Real-time updates** — WebSocket push notifications when a refresh cycle completes\n- **Single-user mode** — first-run account setup with bcrypt-hashed password; no registration flow\n- **Portable storage** — single SQLite file; no external database\n\n## Tech Stack\n\n| Layer | Technology |\n|---|---|\n| Backend | Python 3.11+, FastAPI, SQLAlchemy (async), Alembic, httpx |\n| Frontend | TypeScript, Vue 3, Pinia, Vue Router, Chart.js, Tailwind CSS |\n| Database | SQLite (WAL mode) via aiosqlite |\n| Build / dev | Vite, Vitest, pytest, ruff |\n\nExternal data sources: [Mempool.space](https://mempool.space) (Bitcoin individual addresses), [Trezor Blockbook](https://trezor.io) (HD wallets / xpub), [api.kaspa.org](https://api.kaspa.org) (Kaspa), [CoinGecko](https://www.coingecko.com) (prices).\n\n## Quick Start (Docker)\n\nThe fastest way to run CryptoDash. Requires Docker.\n\n```bash\ndocker run -d \\\n  --name cryptodash \\\n  -p 8000:8000 \\\n  -v cryptodash-data:/app/data \\\n  ghcr.io/lukius/cryptodash:latest\n```\n\nOr with Docker Compose:\n\n```bash\ncurl -O https://raw.githubusercontent.com/lukius/cryptodash/master/docker-compose.yml\ndocker compose up -d\n```\n\nOpen [http://localhost:8000](http://localhost:8000) in your browser. On first run you will be prompted to create a username and password. Your data lives in the `cryptodash-data` named volume — your wallet list and history persist across container restarts and image upgrades.\n\nImages are published for `linux/amd64` and `linux/arm64` (e.g. Raspberry Pi 4/5).\n\n## Quick Start (from source)\n\n**Prerequisites:** Python 3.11+, Node.js 18+\n\n```bash\n# 1. Clone\ngit clone https://github.com/lukius/cryptodash.git\ncd cryptodash\n\n# 2. Backend — create and activate a virtualenv, then install deps\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n\n# 3. Frontend — build the production bundle\ncd frontend\nnpm install\nnpm run build\ncd ..\n\n# 4. Run\npython run.py\n```\n\nOpen [http://localhost:8000](http://localhost:8000) in your browser. On first run you will be prompted to create a username and password.\n\n### Development mode\n\nRun the backend and frontend dev server concurrently for hot-reload:\n\n```bash\n# Terminal 1 — backend\nsource .venv/bin/activate\npython run.py\n\n# Terminal 2 — frontend dev server (proxies /api to backend)\ncd frontend\nnpm run dev\n```\n\nFrontend dev server listens on [http://localhost:5173](http://localhost:5173).\n\n## Configuration\n\nAll settings are optional environment variables with sensible defaults:\n\n| Variable | Default | Description |\n|---|---|---|\n| `CRYPTODASH_DB_PATH` | `data/cryptodash.db` | Path to the SQLite database file |\n| `CRYPTODASH_HOST` | `0.0.0.0` | Bind address |\n| `CRYPTODASH_PORT` | `8000` | HTTP port |\n| `CRYPTODASH_LOG_LEVEL` | `info` | Uvicorn log level (`debug`, `info`, `warning`, `error`) |\n\nThe refresh interval is configured inside the app via the Settings page and persisted in the database.\n\nWhen running under Docker, pass these via `-e VAR=value` (or in the `environment:` block of `docker-compose.yml`). The default `CRYPTODASH_DB_PATH` inside the container is `/app/data/cryptodash.db` so the database lives in the mounted volume.\n\n### Reset password\n\nFrom source:\n\n```bash\npython run.py reset-password\n```\n\nIn Docker:\n\n```bash\ndocker exec -it cryptodash python run.py reset-password\n```\n\n## Project Structure\n\n```\ncryptodash/\n├── backend/\n│   ├── app.py              # FastAPI app factory + lifespan\n│   ├── config.py           # Environment-variable configuration\n│   ├── clients/            # External API clients (Bitcoin, Kaspa, CoinGecko, Blockbook)\n│   ├── core/               # Scheduler, WebSocket manager, security, DI\n│   ├── models/             # SQLAlchemy ORM models\n│   ├── repositories/       # Database access layer\n│   ├── routers/            # HTTP + WebSocket route handlers\n│   ├── schemas/            # Pydantic request/response types\n│   └── services/           # Business logic (auth, wallet, refresh, history, price)\n├── frontend/src/\n│   ├── components/         # Reusable Vue components (widgets, wallet, layout, common)\n│   ├── composables/        # useApi, useWebSocket\n│   ├── router/             # Vue Router routes + auth guards\n│   ├── stores/             # Pinia state stores (auth, dashboard, wallets, settings)\n│   ├── types/              # TypeScript interfaces\n│   ├── utils/              # Formatting and address validation helpers\n│   └── views/              # Page-level components\n├── backend/migrations/     # Alembic database migrations\n├── specs/                  # Functional spec, tech spec, UI mockups (source of truth)\n├── tests/                  # pytest (backend) + Vitest (frontend) test suites\n└── .claude/                # Claude Code agent team and custom skills\n```\n\n## API Overview\n\nThe REST API is available under `/api`. An interactive OpenAPI interface is served at `/docs` when the backend is running.\n\n| Method | Path | Description |\n|---|---|---|\n| GET | `/api/auth/status` | Auth status and account existence |\n| POST | `/api/auth/setup` | First-run account creation |\n| POST | `/api/auth/login` | Login |\n| POST | `/api/auth/logout` | Logout |\n| GET | `/api/wallets/` | List wallets with latest balances |\n| POST | `/api/wallets/` | Add wallet |\n| PATCH | `/api/wallets/{id}` | Update wallet tag |\n| DELETE | `/api/wallets/{id}` | Remove wallet |\n| GET | `/api/wallets/{id}/transactions` | Transaction timeline for a wallet |\n| POST | `/api/wallets/{id}/retry-history` | Retry failed history import |\n| GET | `/api/dashboard/summary` | Portfolio totals |\n| GET | `/api/dashboard/portfolio-history` | Historical portfolio value |\n| GET | `/api/dashboard/wallet-history/{id}` | Per-wallet balance history |\n| GET | `/api/dashboard/price-history` | BTC/USD and KAS/USD price history |\n| GET | `/api/dashboard/composition` | Portfolio composition breakdown |\n| POST | `/api/dashboard/refresh` | Trigger a manual refresh |\n| GET/PUT | `/api/settings/` | Read / update settings |\n| WS | `/api/ws` | Real-time refresh events |\n\n## Running Tests\n\n```bash\n# Backend (requires dev deps)\npip install -r requirements-dev.txt\npytest tests/backend/ -v\n\n# Backend lint + format check\nruff check backend/ tests/\nruff format --check backend/ tests/\n\n# Frontend\ncd frontend \u0026\u0026 npm run test\ncd frontend \u0026\u0026 npm run lint\n```\n\n## AI-Assisted Development\n\nCryptoDash is primarily developed with [Claude Code](https://claude.ai/code), though `CLAUDE.md` and the specs in `specs/` make the project approachable by any AI assistant.\n\n- **`CLAUDE.md`** — project context file: build commands, key design decisions, known gotchas. Any AI assistant can read this to get up to speed quickly.\n- **`.claude/agents/`** — a Claude Code agent team (project manager, developer, tech lead, QA analyst) for coordinated multi-step work\n- **`.claude/skills/`** — Claude Code custom workflows:\n  - `/develop-feature` — full agent-team flow: plan → TDD → code review → QA\n  - `/generate-func-spec` — generate a functional spec from a brief\n  - `/generate-tech-spec` — generate a technical spec from a functional spec\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on maintaining `CLAUDE.md` and using the agent workflow.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding conventions, testing requirements, and the pull-request process.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukius%2Fcryptodash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukius%2Fcryptodash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukius%2Fcryptodash/lists"}