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

工作原理

```
setup
```
creates a local plan file with the full schedule
```
run
```
is called by the agent on each schedule tick (via cron or heartbeat)
Each
```
run
```
checks if an order is due, fetches a live quote, and returns
```
blocked
```
until
```
--confirm
```
On confirm: executes the swap on-chain, logs the tx hash, advances the schedule
```
status
```
shows progress: avg entry price, total spent/received, remaining orders

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

Quick Start

快速开始

bash

undefined

bash

undefined

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>

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

Flag	Required	Description
`--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):

Token	Example	Meaning
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

环境变量

Variable	Description
`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)

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

Guardrail	Limit	Enforcement
Max slippage	10%	Hard error `SLIPPAGE_LIMIT`
Max orders	100	Hard error `ORDERS_LIMIT`
Min order size	> 0	Hard error `ORDER_TOO_SMALL`
Spend confirmation	Always	`blocked` without `--confirm`
Frequency enforcement	Per-plan	`blocked` if called too early
Balance check	STX pre-execution	Error `INSUFFICIENT_BALANCE`
Cancelled/completed plans	Blocked	Error `PLAN_CANCELLED` / `PLAN_COMPLETE`
Private key exposure	Never	Zero-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):

```
STACKS_PRIVATE_KEY
```
env var (direct, for testing)
AIBTC MCP wallet (
```
~/.aibtc/wallets.json
```
+ keystore — AES-256-GCM + scrypt)
Legacy
```
~/.aibtc/wallet.json
```
(older format)

三种钱包来源（按优先级检查）：

```
STACKS_PRIVATE_KEY
```
环境变量（直接调用，用于测试）
AIBTC MCP钱包（
```
~/.aibtc/wallets.json
```
+ 密钥库 — AES-256-GCM + scrypt加密）
旧版
```
~/.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

dca

Original

Translation

DCA — Dollar Cost Averaging for Stacks DeFi

DCA — 适用于Stacks DeFi的美元成本平均策略

How It Works

工作原理

Quick Start

快速开始

1. Install dependencies

1. Install dependencies

2. Health check

2. Health check

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

4. Preview the schedule

4. Preview the schedule

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)

Review the quote, then:

Review the quote, then:

6. Monitor progress

6. Monitor progress

7. Cancel remaining orders

7. Cancel remaining orders

Commands

命令说明

doctor

doctor

install-packs --pack all

install-packs --pack all

Dependencies

依赖说明

setup

setup

plan --plan <id>

plan --plan <id>

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

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

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

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

cancel --plan <id>

cancel --plan <id>

list

list

Token Amounts

代币金额说明

Environment Variables

环境变量

Output Format

输出格式

Safety Guardrails (enforced in code)

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

Scheduling

调度方式

Cron: execute DCA daily at 9am

Cron: 每天上午9点执行DCA

State Files

状态文件

Wallet Support

钱包支持

Known Constraints

已知限制

Origin

来源

`doctor`

`doctor`

`install-packs --pack all`

`install-packs --pack all`

`setup`

`setup`

`plan --plan <id>`

`plan --plan <id>`

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

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

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

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

`cancel --plan <id>`

`cancel --plan <id>`

`list`

`list`