DCA — Dollar Cost Averaging for Stacks DeFi
Automate recurring token purchases (or sales) on Stacks mainnet via direct Bitflow swaps.
The agent executes each order on schedule — no third-party contracts required.
How It Works
- creates a local plan file with the full schedule
- is called by the agent on each schedule tick (via cron or heartbeat)
- Each checks if an order is due, fetches a live quote, and returns until
- On confirm: executes the swap on-chain, logs the tx hash, advances the schedule
- shows progress: avg entry price, total spent/received, remaining orders
Quick Start
bash
# 1. Install dependencies
bun run dca/dca.ts install-packs --pack all
# 2. Health check
bun run dca/dca.ts doctor
# 3. Create a plan: DCA 50 STX into sBTC over 5 daily orders
bun run dca/dca.ts setup \
--token-in STX --token-out sBTC \
--total 50 --orders 5 --frequency daily --slippage 3
# 4. Preview the schedule
bun run dca/dca.ts plan --plan <planId>
# 5. Execute next order (--confirm required)
# Preferred: use env var (doesn't appear in ps aux or shell history)
export AIBTC_WALLET_PASSWORD="your-password"
bun run dca/dca.ts run --plan <planId>
# Review the quote, then:
bun run dca/dca.ts run --plan <planId> --confirm
# 6. Monitor progress
bun run dca/dca.ts status --plan <planId>
# 7. Cancel remaining orders
bun run dca/dca.ts cancel --plan <planId>
Commands
System health check — verifies Bitflow API, wallet file, and Stacks mainnet connectivity.
One-time setup: installs required packages. Run once during initial setup — not during normal execution.
Note: runs
and modifies
. This is a one-time setup step — do not call it during regular agent operation or in shared environments where multiple processes may be active.
Dependencies
If not using
, add these to your project manually:
bash
bun add @bitflowlabs/core-sdk @stacks/transactions @stacks/network @stacks/wallet-sdk @stacks/encryption commander tslib
| Flag | Required | Description |
|---|
| ✅ | Input token symbol (e.g. ) |
| ✅ | Output token symbol (e.g. , , ) |
| ✅ | Total amount in human units (e.g. = 50 STX) |
| ✅ | Number of orders (2..100) |
| ✅ | · · · |
| ❌ | Slippage % (default , hard max ) |
| ❌ | Hours before first order (default ) |
Validates the token pair against live Bitflow routes before saving.
Preview the full DCA schedule with per-order timing and current quote estimates.
run --plan <id> [--confirm] [--wallet-password <pw>]
Execute the next pending order. Cron-friendly — returns
if called before the next order is due.
- Without : Returns live quote preview. Safe to inspect.
- With : Executes the swap on-chain, logs tx hash, advances schedule.
Security: Prefer
env var over
flag. CLI flags appear in
output and shell history — a real risk in long-lived agent processes. Use
only as a fallback.
bash
# Preferred (env var — not visible in ps aux)
export AIBTC_WALLET_PASSWORD="your-password"
bun run dca/dca.ts run --plan <planId> --confirm
# Fallback only (flag — visible in process list)
bun run dca/dca.ts run --plan <planId> --confirm --wallet-password "your-password"
/
Progress: orders complete, total spent, total received, avg entry price, next order ETA.
Cancel a plan. Stops all future
calls for this plan.
List all local DCA plan files with status.
Token Amounts
Pass
in
human-readable units (not microunits):
| Token | Example | Meaning |
|---|
| STX | | 50 STX |
| sBTC | | 0.001 sBTC |
| ALEX | | 100 ALEX |
Environment Variables
| Variable | Description |
|---|
| Wallet password (alternative to ) |
| Direct private key for testing (bypasses wallet file) |
| Simulate all writes — no transactions broadcast |
Output Format
All commands emit strict JSON to stdout:
json
{
"status": "success | error | blocked",
"action": "Human-readable next step",
"data": {
"telegram": "📊 Emoji-rich Telegram-friendly summary",
"...": "command-specific fields"
},
"error": null
}
Safety Guardrails (enforced in code)
| Guardrail | Limit | Enforcement |
|---|
| Max slippage | 10% | Hard error |
| Max orders | 100 | Hard error |
| Min order size | > 0 | Hard error |
| Spend confirmation | Always | without |
| Frequency enforcement | Per-plan | if called too early |
| Balance check | STX pre-execution | Error |
| Cancelled/completed plans | Blocked | Error / |
| Private key exposure | Never | Zero-exposure in all output |
| Dry run mode | | Simulates without broadcasting |
Scheduling
The
command is designed to be called by cron or heartbeat:
bash
# Cron: execute DCA daily at 9am
0 9 * * * AIBTC_WALLET_PASSWORD=xxx bun run /path/to/dca/dca.ts run --plan <id> --confirm
Frequency is enforced by the skill — early calls return
with time remaining. Safe to call frequently.
State Files
Plans stored at
~/.aibtc/dca/<plan-id>.json
. Contains full plan config, every tx hash, per-order execution log, and running avg cost.
Wallet Support
Three wallet sources (checked in order):
- env var (direct, for testing)
- AIBTC MCP wallet ( + keystore — AES-256-GCM + scrypt)
- Legacy (older format)
Known Constraints
- Mainnet only
- Requires funded wallet (STX for gas + swap input token)
- Bitflow API must be reachable (500 req/min rate limit)
- Not all token pairs have routes — validates before saving
Origin
Winner of AIBTC x Bitflow Skills Pay the Bills competition.
Original author: @k9dreamermacmini-coder
Competition PR:
https://github.com/BitflowFinance/bff-skills/pull/31