Back to Details

dca

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DCA — Dollar Cost Averaging for Stacks DeFi

DCA — 适用于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.
通过Bitflow直接兑换在Stacks主网自动化定期代币买入（或卖出）。 Agent会按计划执行每笔订单 — 无需第三方合约。

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
  1. setup
    创建包含完整计划的本地配置文件
  2. run
    由Agent在每个计划时间点调用（通过cron或心跳机制）
  3. 每次
    run
    会检查是否有订单到期，获取实时报价，在未添加
    --confirm
    参数时返回
    blocked
    状态
  4. 确认后：在链上执行兑换，记录交易哈希，推进计划进度
  5. status
    展示进度：平均入场价、总支出/收入、剩余订单数

Quick Start

快速开始

bash
undefined
bash
undefined

1. Install dependencies

1. Install dependencies

bun run dca/dca.ts install-packs --pack all
bun run dca/dca.ts install-packs --pack all

2. Health check

2. Health check

bun run dca/dca.ts doctor
bun run dca/dca.ts doctor

3. Create a plan: DCA 50 STX into sBTC over 5 daily orders

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
bun run dca/dca.ts setup
--token-in STX --token-out sBTC
--total 50 --orders 5 --frequency daily --slippage 3

4. Preview the schedule

4. Preview the schedule

bun run dca/dca.ts plan --plan <planId>
bun run dca/dca.ts plan --plan <planId>

5. Execute next order (--confirm required)

5. Execute next order (--confirm required)

Preferred: use env var (doesn't appear in ps aux or shell history)

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>
export AIBTC_WALLET_PASSWORD="your-password" bun run dca/dca.ts run --plan <planId>

Review the quote, then:

Review the quote, then:

bun run dca/dca.ts run --plan <planId> --confirm
bun run dca/dca.ts run --plan <planId> --confirm

6. Monitor progress

6. Monitor progress

bun run dca/dca.ts status --plan <planId>
bun run dca/dca.ts status --plan <planId>

7. Cancel remaining orders

7. Cancel remaining orders

bun run dca/dca.ts cancel --plan <planId>
undefined
bun run dca/dca.ts cancel --plan <planId>
undefined

Commands

命令说明

doctor

doctor

System health check — verifies Bitflow API, wallet file, and Stacks mainnet connectivity.
系统健康检查 — 验证Bitflow API、钱包文件和Stacks主网连接状态。

install-packs --pack all

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.
一次性配置：安装所需依赖包。仅在初始设置时运行一次 — 正常执行期间无需调用。
安装内容： 
@bitflowlabs/core-sdk
, 
@stacks/transactions
, 
@stacks/network
, 
@stacks/wallet-sdk
, 
@stacks/encryption
, 
commander
, 
tslib
注意： 
install-packs
会执行 
bun add
并修改 
package.json
。这是一次性设置步骤 — 不要在常规Agent运行期间或多进程活跃的共享环境中调用。

Dependencies

依赖说明

If not using 
install-packs
, add these to your project manually:
bash
bun add @bitflowlabs/core-sdk @stacks/transactions @stacks/network @stacks/wallet-sdk @stacks/encryption commander tslib
如果不使用
install-packs
，请手动将以下依赖添加到项目中：
bash
bun add @bitflowlabs/core-sdk @stacks/transactions @stacks/network @stacks/wallet-sdk @stacks/encryption commander tslib

setup

setup

FlagRequiredDescription
--token-in
✅Input token symbol (e.g. 
STX
)
--token-out
✅Output token symbol (e.g. 
sBTC
, 
WELSH
, 
ALEX
)
--total
✅Total amount in human units (e.g. 
50
= 50 STX)
--orders
✅Number of orders (2..100)
--frequency
✅
hourly
· 
daily
· 
weekly
· 
biweekly
--slippage
❌Slippage % (default 
3
, hard max 
10
)
--start-delay-hours
❌Hours before first order (default 
0
)
Validates the token pair against live Bitflow routes before saving.
参数是否必填说明
--token-in
✅输入代币符号（例如 
STX
）
--token-out
✅输出代币符号（例如 
sBTC
, 
WELSH
, 
ALEX
）
--total
✅总金额（采用人类可读单位，例如 
50
= 50 STX）
--orders
✅订单数量（2..100）
--frequency
✅
hourly
（每小时）· 
daily
（每日）· 
weekly
（每周）· 
biweekly
（每两周）
--slippage
❌滑点百分比（默认值 
3
，最大限制 
10
）
--start-delay-hours
❌首次订单延迟小时数（默认值 
0
）
保存前会验证代币对是否存在有效的Bitflow路由。

plan --plan <id>

plan --plan <id>

Preview the full DCA schedule with per-order timing and current quote estimates.
预览完整DCA计划，包含每笔订单的时间安排和当前报价估算。

run --plan <id> [--confirm] [--wallet-password <pw>]

run --plan <id> [--confirm] [--wallet-password <pw>]

Execute the next pending order. Cron-friendly — returns 
blocked
if called before the next order is due.
  • 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.
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"
执行下一笔待处理订单。适配cron调度 — 如果在订单到期前调用，会返回
blocked
状态。
  • 未添加
    --confirm
    ：返回实时报价预览，可安全查看。
  • 添加
    --confirm
    ：在链上执行兑换，记录交易哈希，推进计划进度。
安全提示： 优先使用
AIBTC_WALLET_PASSWORD
环境变量，而非
--wallet-password
参数。CLI参数会出现在
ps aux
输出和shell历史中 — 在长期运行的Agent进程中存在安全风险。仅在万不得已时使用
--wallet-password
。
bash
# 推荐方式（环境变量 — 不会出现在ps aux中）
export AIBTC_WALLET_PASSWORD="your-password"
bun run dca/dca.ts run --plan <planId> --confirm

# 仅作为备选（参数 — 会出现在进程列表中）
bun run dca/dca.ts run --plan <planId> --confirm --wallet-password "your-password"

status --plan <id>
/ 
status --all

status --plan <id>
/ 
status --all

Progress: orders complete, total spent, total received, avg entry price, next order ETA.
展示进度：已完成订单数、总支出、总收入、平均入场价、下一笔订单预计时间。

cancel --plan <id>

cancel --plan <id>

Cancel a plan. Stops all future 
run
calls for this plan.
取消计划。停止该计划的所有后续
run
调用。

list

list

List all local DCA plan files with status.
列出所有本地DCA计划文件及其状态。

Token Amounts

代币金额说明

Pass 
--total
in human-readable units (not microunits):
TokenExampleMeaning
STX
--total 50
50 STX
sBTC
--total 0.001
0.001 sBTC
ALEX
--total 100
100 ALEX
--total
参数需传入人类可读单位（而非微单位）：
代币示例含义
STX
--total 50
50 STX
sBTC
--total 0.001
0.001 sBTC
ALEX
--total 100
100 ALEX

Environment Variables

环境变量

VariableDescription
AIBTC_WALLET_PASSWORD
Wallet password (alternative to 
--wallet-password
)
STACKS_PRIVATE_KEY
Direct private key for testing (bypasses wallet file)
AIBTC_DRY_RUN=1
Simulate all writes — no transactions broadcast
环境变量说明
AIBTC_WALLET_PASSWORD
钱包密码（替代
--wallet-password
参数）
STACKS_PRIVATE_KEY
用于测试的直接私钥（绕过钱包文件）
AIBTC_DRY_RUN=1
模拟所有写入操作 — 不会广播交易

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
}
所有命令会向标准输出输出严格的JSON格式：
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)

安全防护规则（代码强制执行）

GuardrailLimitEnforcement
Max slippage10%Hard error 
SLIPPAGE_LIMIT
Max orders100Hard error 
ORDERS_LIMIT
Min order size> 0Hard error 
ORDER_TOO_SMALL
Spend confirmationAlways
blocked
without 
--confirm
Frequency enforcementPer-plan
blocked
if called too early
Balance checkSTX pre-executionError 
INSUFFICIENT_BALANCE
Cancelled/completed plansBlockedError 
PLAN_CANCELLED
/ 
PLAN_COMPLETE
Private key exposureNeverZero-exposure in all output
Dry run mode
AIBTC_DRY_RUN=1
Simulates without broadcasting
安全防护规则限制值执行方式
最大滑点10%触发硬错误 
SLIPPAGE_LIMIT
最大订单数100触发硬错误 
ORDERS_LIMIT
最小订单金额> 0触发硬错误 
ORDER_TOO_SMALL
支出确认始终需要未添加
--confirm
时返回
blocked
频率校验按计划执行调用过早时返回
blocked
余额检查执行前校验STX余额触发错误 
INSUFFICIENT_BALANCE
已取消/完成的计划禁止执行触发错误 
PLAN_CANCELLED
/ 
PLAN_COMPLETE
私钥暴露绝对禁止所有输出中不会泄露私钥
模拟运行模式
AIBTC_DRY_RUN=1
模拟操作但不广播交易

Scheduling

调度方式

The 
run
command is designed to be called by cron or heartbeat:
bash
undefined
run
命令专为cron或心跳调度设计：
bash
undefined

Cron: execute DCA daily at 9am

Cron: 每天上午9点执行DCA

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` with time remaining. Safe to call frequently.
0 9 * * * AIBTC_WALLET_PASSWORD=xxx bun run /path/to/dca/dca.ts run --plan <id> --confirm

该工具会按计划频率执行 — 提前调用会返回`blocked`状态并显示剩余时间。可安全高频调用。

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.
计划存储在
~/.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)
三种钱包来源（按优先级检查）：
  1. STACKS_PRIVATE_KEY
    环境变量（直接调用，用于测试）
  2. AIBTC MCP钱包（
    ~/.aibtc/wallets.json
    + 密钥库 — AES-256-GCM + scrypt加密）
  3. 旧版
    ~/.aibtc/wallet.json
    （兼容旧格式）

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
  • 仅支持主网
  • 钱包需有余额（STX用于Gas费 + 兑换输入代币）
  • 需可访问Bitflow API（速率限制为500次请求/分钟）
  • 并非所有代币对都有可用路由 — 
    setup
    会在保存前验证

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
AIBTC x Bitflow Skills Pay the Bills竞赛获奖作品。 原作者：@k9dreamermacmini-coder 竞赛PR：https://github.com/BitflowFinance/bff-skills/pull/31