dca

DCA — Stacks DeFi 的定期定额投资

通过 直接 Bitflow 兑换，在 Stacks 主网上自动定期购买（或出售）代币。 Agent 会按计划执行每笔订单，无需第三方合约。

工作原理

1. setup 创建包含完整计划的本地文件
2. Agent 在每个计划时间点调用 run（通过 cron 或心跳）
3. 每次调用 run 都会检查是否到了下单时间、获取实时报价，并返回 blocked，直到使用 --confirm 确认
4. 确认后：在链上执行兑换、记录交易哈希并推进计划
5. status 显示进度：平均买入价、总支出/收入和剩余订单

快速开始

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

命令

doctor

系统健康检查——验证 Bitflow API、钱包文件和 Stacks 主网连接。

install-packs --pack all

一次性设置：安装所需的软件包。请在初始设置时运行一次，不要在正常执行期间运行。

安装： @bitflowlabs/core-sdk、@stacks/transactions、@stacks/network、@stacks/wallet-sdk、@stacks/encryption、commander、tslib

注意： install-packs 会运行 bun add 并修改 package.json。这是一次性设置步骤——请勿在常规 Agent 操作期间，或在可能有多个进程同时运行的共享环境中调用。

依赖项

如果不使用 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 = 50 STX）
--orders	✅	订单数量（2..100）
--frequency	✅	hourly · daily · weekly · biweekly
--slippage	❌	滑点百分比（默认值为 3，硬性上限为 10）
--start-delay-hours	❌	首笔订单前等待的小时数（默认值为 0）

保存前会根据 Bitflow 实时路由验证代币对。

plan --plan <id>

预览完整的 DCA 计划，包括每笔订单的时间安排和当前报价估算。

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

执行下一笔待处理订单。适合 cron 调用——如果尚未到下一笔订单的执行时间，则返回 blocked。

• 不使用 --confirm： 返回实时报价预览，可安全查看。
• 使用 --confirm： 在链上执行兑换、记录交易哈希并推进计划。

安全提示： 优先使用 AIBTC_WALLET_PASSWORD 环境变量，而非 --wallet-password 标志。CLI 标志会出现在 ps aux 输出和 shell 历史记录中——对于长期运行的 Agent 进程，这确实存在风险。仅在备用情况下使用 --wallet-password。

# 首选（环境变量——不会显示在 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

进度：已完成订单数、总支出、总收入、平均买入价、下一笔订单的预计执行时间。

cancel --plan <id>

取消计划。停止对此计划的所有后续 run 调用。

list

列出所有本地 DCA 计划文件及其状态。

代币金额

--total 请使用常规单位（而非微单位）：

代币	示例	含义
STX	--total 50	50 STX
sBTC	--total 0.001	0.001 sBTC
ALEX	--total 100	100 ALEX

环境变量

变量	描述
AIBTC_WALLET_PASSWORD	钱包密码（可替代 --wallet-password）
STACKS_PRIVATE_KEY	用于测试的直接私钥（绕过钱包文件）
AIBTC_DRY_RUN=1	模拟所有写入操作——不广播交易

输出格式

所有命令都会向 stdout 输出严格的 JSON：

{
  "status": "success | error | blocked",
  "action": "Human-readable next step",
  "data": {
    "telegram": "📊 Emoji-rich Telegram-friendly summary",
    "...": "command-specific fields"
  },
  "error": null
}

安全护栏（在代码中强制执行）

护栏	限制	执行方式
最大滑点	10%	硬错误 SLIPPAGE_LIMIT
最大订单数	100	硬错误 ORDERS_LIMIT
最小订单规模	> 0	硬错误 ORDER_TOO_SMALL
支出确认	始终需要	未使用 --confirm 时为 blocked
频率限制	按计划执行	调用过早时为 blocked
余额检查	执行前检查 STX	错误 INSUFFICIENT_BALANCE
已取消／已完成的计划	禁止执行	错误 PLAN_CANCELLED／PLAN_COMPLETE
私钥暴露	绝不允许	所有输出均为零暴露
演练模式	AIBTC_DRY_RUN=1	模拟执行，不广播交易

调度

run 命令旨在由 cron 或心跳机制调用：

# Cron: execute DCA daily at 9am
0 9 * * * AIBTC_WALLET_PASSWORD=xxx bun run /path/to/dca/dca.ts run --plan <id> --confirm

该技能会强制执行频率限制——过早调用时会返回 blocked，并显示剩余时间。可以安全地频繁调用。

状态文件

计划存储在 ~/.aibtc/dca/<plan-id>.json。其中包含完整的计划配置、每笔交易的哈希、每笔订单的执行日志，以及滚动平均成本。

钱包支持

三种钱包来源（按以下顺序检查）：

1. STACKS_PRIVATE_KEY 环境变量（直接使用，用于测试）
2. AIBTC MCP 钱包（~/.aibtc/wallets.json + 密钥库——AES-256-GCM + scrypt）
3. 旧版 ~/.aibtc/wallet.json（较早的格式）

已知限制

• 仅支持主网
• 需要已注资的钱包（用于支付 Gas 的 STX + 用作兑换输入的代币）
• Bitflow API 必须可访问（速率限制为 500 req/min）
• 并非所有代币对都有兑换路径——setup 会在保存前进行验证

来源

AIBTC x Bitflow Skills Pay the Bills 竞赛获胜项目。 原作者：@k9dreamermacmini-coder 竞赛 PR：https://github.com/BitflowFinance/bff-skills/pull/31

费用配置（2026-07-15 实地审计 F-14）

兑换费用为 DCA_FEE_USTX（环境变量），会进行验证（^\d+$，必须大于 0，上限为 1,000,000 µSTX = 1 STX），默认值为 50000 µSTX——此前费用硬编码为 5000 µSTX，比同类技能低 10–50 倍，存在费用过低导致 nonce 卡住的风险。STX 余额预检查会预留与交易实际支付金额相同的费用。若 DCA_FEE_USTX 为空或格式错误，会明确报错，而不是悄悄广播零费用交易。