StackSats

Build dynamic Bitcoin DCA models that robustly acquire more BTC than uniform DCA under fixed-budget, fixed-horizon constraints.

The Stacking Sats problem is simple to state and hard to solve: given a fixed Bitcoin accumulation budget and an allocation horizon longer than six months, can a dynamic dollar-cost averaging (DCA) model robustly acquire more BTC than uniform DCA?

StackSats is a Python library for building, validating, and operationalizing models for that problem. It turns research signals and feature pipelines into constrained BTC weight schedules, backtests them against uniform DCA, and emits daily allocation decisions.

The Stacking Sats Problem

Uniform DCA allocates the same amount every day across the same budget and horizon. A dynamic DCA model tries to reshape that schedule while keeping the budget fixed, the horizon fixed, and past allocations locked.

StackSats defines success as robustly acquiring more BTC for the same dollars, measured through sats per dollar (SPD), not short-term USD ROI or CAGR. The framework keeps each strategy inside the core constraints:

• fixed accumulation budget
• fixed allocation horizon, defaulting to 365 days
• product framing for horizons longer than six months
• no forward-looking data
• immutable historical allocations
• brokerage execution outside the library

Use StackSats when you want to:

• build dynamic Bitcoin DCA models in Python
• compare strategy behavior against uniform DCA on the same budget and horizon
• validate causal, budget, and allocation constraints before shipping a strategy
• emit daily BTC allocation decisions for agents or external execution systems

StackSats is library-first: the CLI, demo flows, and hosted agent API all sit on top of the same Python package surface.

Learn more at www.stackingsats.org.

Hosted documentation: https://hypertrial.github.io/stacksats/ — start from docs/index.md.

What StackSats is

StackSats is not a general crypto trading bot or brokerage wrapper. It is a research and decision engine for Bitcoin accumulation strategies:

• Python library: define strategies with BaseStrategy, run them with stable configs, and consume results from Python.
• Quantitative DCA toolkit: model how much BTC to accumulate over time instead of placing exchange-specific orders directly.
• Backtesting framework: compare strategies, validate constraints, and export artifact sets from repeatable runs.
• Execution boundary: StackSats computes decisions; brokerage execution stays outside the package unless you wire in an adapter intentionally.

Documentation map

• docs/start/quickstart.md — first install, demo run, and Python entry points
• docs/start/first-strategy-run.md — write your first custom Bitcoin DCA strategy
• docs/start/minimal-strategy-examples.md — copyable strategy templates
• docs/reference/public-api.md — stable 1.x Python library surface
• docs/start/system-overview.md — data flow and production paths
• docs/tasks.md — task-first workflows
• docs/commands.md — CLI index
• docs/run/compare.md — compare multiple strategies on one window (stacksats strategy compare, comparison_result.json)
• docs/data-source.md — Bitcoin Research Kit (BRK) dataset support, canonical source data, and manifests
• docs/troubleshooting.md — symptom-based links
• docs/migration.md — breaking-change mappings
• docs/release.md — maintainer releases

BRK compatibility

StackSats is a Python library with explicit compatibility for the Bitcoin Research Kit (BRK) project and BRK-derived canonical data workflows. We document BRK as the upstream project and link to the official BRK surfaces: bitcoinresearchkit/brk, brk on crates.io, and brk on docs.rs.

This is a project and data compatibility statement, not a promise that StackSats embeds BRK, re-exports Rust crates, or version-locks BRK crate APIs. StackSats remains a Python package with its own stable 1.x support boundary.

Framework principles

The framework owns budget math, iteration, feasibility clipping, and lock semantics; you own features, signals, hyperparameters, and daily intent (propose_weight or build_target_profile). The same sealed allocation kernel runs in local runs, backtests, and production. See docs/framework.md.

Primary production flow

1. StackSats computes a validated BTC accumulation decision.
2. An external agent or automation reads the decision payload.
3. Brokerage execution stays outside StackSats.

Use stacksats strategy decide-daily (or strategy.decide_daily(...)) for the agent-facing interface; docs/run/decide-daily.md covers payloads and sensitivity. Use stacksats serve agent-api for a hosted /v1 HTTP service (docs/run/agent-api.md, including token policy). Use stacksats strategy run-daily when StackSats should submit through a configured adapter (docs/run/run-daily.md).

Security: follow SECURITY.md for reporting; treat decision and API tokens as secrets.

Installation

Use case	Command
Use StackSats from PyPI	pip install stacksats
Editable install from a checkout	python -m pip install -c requirements/constraints-maintainer.txt -e ".[dev,all]"

Optional extras: pip install "stacksats[viz]" (animation/plots), [network] (HTTP BTC price helpers), [service] (agent API), [deploy] (Postgres/export helpers). The stacksats-plot-weights helper needs both [viz] and [deploy] plus a configured DATABASE_URL (it reads stored weight windows, then renders). Helper scripts are documented convenience tools, not part of the frozen stable 1.x CLI subset.

Development venv (from repo root):

python -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
pip install -c requirements/constraints-maintainer.txt -e ".[dev,all]"
pip install pre-commit
venv/bin/python -m pre_commit install -t pre-commit

Quick start

Install, import the stable 1.x surface, then run the packaged demo:

pip install stacksats

from stacksats import BaseStrategy, StrategyRunner, list_strategies

stacksats demo backtest

Artifacts: output/<strategy_id>/<version>/<run_id>/

If you want to build strategies in Python next, start with docs/start/first-strategy-run.md and docs/start/minimal-strategy-examples.md. For the full CLI, use docs/commands.md. For BRK data setup (stacksats data fetch|prepare|doctor), use docs/start/full-data-setup.md. For the support boundary, use docs/stability.md. stacksats strategy validate is strict by default; use --no-strict only when you intend the lighter path.

Public API

The stable 1.x contract covers top-level exports, documented artifacts, and the documented CLI/agent API subset. See docs/reference/public-api.md and docs/stability.md. load_data() uses strict BRK validation; for long-format merged metrics exploration, see docs/start/eda-quickstart.md.

Development

See CONTRIBUTING.md for the full local quality matrix (tests, docs gates, coverage, release checks). Typical fast loop:

venv/bin/python -m pytest -q
venv/bin/python -m ruff check .
bash scripts/check_docs_refs.sh
venv/bin/python scripts/check_docs_ux.py
venv/bin/python -m mkdocs build --strict

If the repo path changes locally, rerun bash scripts/install_hooks.sh to refresh git hook paths.