Skip to content

StackSats Documentation

Python library for dynamic Bitcoin DCA models

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

StackSats, developed by Hypertrial, turns research signals and feature pipelines into validated BTC weight schedules, backtests them against uniform DCA, and emits operational daily decisions. It is not a brokerage or generic trading bot. Learn more at www.stackingsats.org.

The Stacking Sats Problem

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?

Uniform DCA means equal daily allocation across the same budget and horizon. StackSats measures the dynamic model's edge as sats per dollar (SPD): robustly acquiring more BTC for the same dollars, not short-term USD ROI or CAGR. The framework keeps that comparison honest by enforcing fixed-budget allocation, a fixed horizon that defaults to 365 days, no forward-looking data, locked historical allocations, and a clean boundary where brokerage execution stays outside the library.

See Framework Boundary for the allocation contract and Backtest Runtime for how strategy-vs-uniform outcomes are scored.

Start in 2 Clicks

Use this page when you want the fastest path into the hosted docs and need to choose the right next workflow.

Canonical first run:

  1. pip install stacksats
  2. stacksats demo backtest
  3. Inspect output/<strategy_id>/<version>/<run_id>/

Next steps:

What's new

Agent-Native Flow

The primary production flow is:

  1. StackSats computes a validated daily BTC accumulation decision.
  2. An external AI agent reads the structured decision payload.
  3. Brokerage-specific execution happens outside StackSats.

Use Task Hub for the shortest path into decide-daily or the Python API.

Canonical Dataset

StackSats is anchored on the canonical Bitcoin Research Kit (BRK) merged_metrics*.parquet dataset. StackSats supports BRK at the project and data-workflow level and documents BRK as the upstream project. See bitcoinresearchkit/brk, brk on crates.io, and brk on docs.rs.

This does not mean StackSats embeds the Rust BRK crates or promises crate-level API compatibility. StackSats remains a Python package that consumes documented BRK-derived data artifacts.

Current coverage and scale are documented in the dataset-specific reference pages:

Core Objects

StackSats is built around three fundamental runtime objects:

  • FeatureTimeSeries: Validated input to a strategy (feature time series with schema and time-series validation).
  • Strategy: User-defined logic for feature engineering, signals, and allocation intent.
  • WeightTimeSeries: Framework-validated output data containing normalized weights and prices.

Choose Your Path

  • I'm New to StackSats

    Start with the offline packaged demo and expected outputs.

    Quickstart

  • I Know the Outcome I Want

    Jump directly to the workflow you need.

    Task Hub

  • I'm Building a Strategy

    Build custom hooks and run validate/backtest/export.

    First Strategy Run

  • I Need Full BRK Data

    Fetch canonical source data and prepare the managed runtime parquet.

    Full Data Setup

Core Concepts

  • System Overview sketches BRK data through strategy hooks to weights and artifacts.
  • Framework Boundary explains framework-owned invariants versus user-owned strategy logic.
  • Strategies documents stable built-ins and experimental reference strategies.
  • Command Index is the canonical CLI reference for the stable stacksats command groups.
  • Migration Guide maps old names and pre-v1 paths to the current 1.x contract.

Feedback