Skip to content

StackSats Documentation

Strategy-first Bitcoin DCA toolkit

Build, validate, and emit agent-consumable Bitcoin dollar cost averaging (DCA) decisions with a sealed allocation framework.

StackSats, developed by Hypertrial, is a Python package for strategy-first Bitcoin dollar cost averaging (DCA) research and execution. Learn more at www.stackingsats.org.

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