Dollar Cost Averaging Calculator — Bitcoin

Project Background

Dollar Cost Averaging (DCA) is an investment strategy where an investor divides up the total amount to be invested across periodic purchases of a target asset, to reduce the impact of volatility on the overall purchase. This project replays that strategy against real historical Bitcoin prices, so you can see what a fixed schedule of purchases would actually have produced in a highly volatile asset.

Live Tool

₿itcoin DCA Calculator — a browser-based simulator. Set a start date, contribution frequency and dollar amount, and your total return, portfolio growth chart, and full purchase history update live as you go.

The S&P 500 / 401(k) calculator is a separate project: https://project401k.netlify.app/

Data Source & Workflow

The calculator is driven by pre-baked static JSON committed to this repo.

	Bitcoin
Source	Kaggle mczielinski — minute-level Bitstamp, aggregated to daily closes
Coverage	2012-01-01 → today (5,300+ closes)
Schedule	Daily, 08:00 UTC
Credentials	Requires KAGGLE_USERNAME + KAGGLE_KEY
Script	scripts/fetch_btc_prices.py
Output	data/btc-prices.json

Kaggle downloads require authentication, so add KAGGLE_USERNAME and KAGGLE_KEY under Settings → Secrets and variables → Actions. Generate them from your Kaggle account under Settings → API → Create New Token. Expired Kaggle credentials are the most likely cause of stale data — the job fails, commits nothing, and the site keeps serving the last good file.

The scheduled Action writes the JSON, commits it, and Netlify auto-deploys. This means:

• No client-side API calls — price data is pre-baked and served from the CDN
• No credentials in the browser — secrets are only ever read by the Actions runner
• No CORS or rate-limit issues — the browser only fetches a local static file
• One upstream dependency — the dataset is volunteer-maintained on Kaggle. If it stalls, the workflow commits nothing and the header chip turns amber once data is more than three days old

Project Structure

├── index.html                              # the calculator (single-page app)
├── netlify.toml                            # publish root + no-cache header for the data file
├── data/
│   └── btc-prices.json                     # auto-generated, daily
├── scripts/
│   └── fetch_btc_prices.py                 # Kaggle download → daily closes
├── tests/
│   ├── engine.test.mjs                     # simulate(), xirr(), the formatters
│   ├── timezone.test.mjs                   # same plan, three timezones
│   ├── harness.mjs                         # pulls the inline <script> into a vm
│   └── fixtures/
│       └── prices.json                     # committed synthetic price series
└── .github/
    └── workflows/
        ├── update-btc-data.yml             # daily cron
        └── test.yml                        # node --test on push and PR

netlify.toml is load-bearing twice: publish = "." is what makes the page's absolute /data/btc-prices.json request resolve, and the must-revalidate header on that path is what stops the CDN serving yesterday's prices.

Running it locally

The page fetches /data/btc-prices.json by absolute path, and browsers block fetch() on file:// outright — so opening index.html by double-clicking it will always fail with the "no price data" error. Serve the directory instead:

python3 -m http.server 8000

Then open http://localhost:8000. Any static server works; it just has to serve the repo root so /data/… resolves. No build step, no dependencies, no API keys — the price file is committed, so the calculator works offline once served.

Rebuilding price data is only needed for fresher numbers than the committed file, and that part does need Kaggle credentials:

pip install kaggle && KAGGLE_USERNAME=you KAGGLE_KEY=xxxx python3 scripts/fetch_btc_prices.py

Data file format

data/btc-prices.json is a standalone, reusable artifact (~175 KB):

{
  "generated": "2026-08-01T09:54:16Z",   // UTC build time
  "source":    "Kaggle/mczielinski — minute-level Bitstamp data aggregated to daily closes",
  "count":     5327,
  "prices":    [ { "ts": 1325376000, "price": 5.0 } ]   // ts = UNIX SECONDS (UTC), ascending
}

Tests

No dependencies and no install step — the engine is exercised straight out of index.html:

node --test tests/*.test.mjs

tests/harness.mjs extracts the inline <script>, evaluates it in a node:vm context against a minimal DOM stub, and hands back the pure functions. The boot code at the end of the script is cut off, so nothing fetches or renders.

This is the beginning of the README. Read the rest at the original. Read the full README ↗