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

1. setup

   creates a local plan file with the full schedule

2. run

   is called by the agent on each schedule tick (via cron or heartbeat)
3. Each

   run

   checks if an order is due, fetches a live quote, and returns

   blocked

   until

   --confirm

4. On confirm: executes the swap on-chain, logs the tx hash, advances the schedule

5. status

   shows progress: avg entry price, total spent/received, remaining orders

Quick Start

# 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

doctor

System health check — verifies Bitflow API, wallet file, and Stacks mainnet connectivity.

install-packs --pack all

One-time setup: installs required packages. Run once during initial setup — not during normal execution.

Installs:

@bitflowlabs/core-sdk

@stacks/transactions

@stacks/network

@stacks/wallet-sdk

@stacks/encryption

commander

tslib

Note:

install-packs

runs

bun add

and modifies

package.json

. 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

install-packs

bun add @bitflowlabs/core-sdk @stacks/transactions @stacks/network @stacks/wallet-sdk @stacks/encryption commander tslib

setup

--token-in

STX

--token-out

sBTC

WELSH

ALEX

--total

50

--orders

--frequency

hourly

daily

weekly

biweekly

--slippage

3

10

--start-delay-hours

0

Validates the token pair against live Bitflow routes before saving.

plan --plan <id>

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

blocked

• Without

  --confirm

  : Returns live quote preview. Safe to inspect.
• With

  --confirm

  : Executes the swap on-chain, logs tx hash, advances schedule.

Security: Prefer

AIBTC_WALLET_PASSWORD

env var over

--wallet-password

flag. CLI flags appear in

ps aux

output and shell history — a real risk in long-lived agent processes. Use

--wallet-password

only as a fallback.

# 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"

status --plan <id>

/

status --all

Progress: orders complete, total spent, total received, avg entry price, next order ETA.

cancel --plan <id>

Cancel a plan. Stops all future

run

list

List all local DCA plan files with status.

Token Amounts

Pass

--total

--total 50

--total 0.001

--total 100

Environment Variables

AIBTC_WALLET_PASSWORD

--wallet-password

STACKS_PRIVATE_KEY

AIBTC_DRY_RUN=1

Output Format

All commands emit strict JSON to stdout:

{
  "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)

SLIPPAGE_LIMIT

ORDERS_LIMIT

ORDER_TOO_SMALL

blocked

--confirm

blocked

INSUFFICIENT_BALANCE

PLAN_CANCELLED

PLAN_COMPLETE

AIBTC_DRY_RUN=1

Scheduling

The

run

# 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

blocked

State Files

Plans stored at

~/.aibtc/dca/<plan-id>.json

Wallet Support

Three wallet sources (checked in order):

1. STACKS_PRIVATE_KEY

   env var (direct, for testing)
2. AIBTC MCP wallet (

   ~/.aibtc/wallets.json

   + keystore — AES-256-GCM + scrypt)
3. Legacy

   ~/.aibtc/wallet.json

   (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 —

  setup

  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