dca-bot

DCA Bot

按计划定期向操作员指定链上的某个代币投入固定金额，以美元成本平均法进行买入；还可选择设置价格条件，例如“仅当 ETH 低于某个阈值时买入”。

**运行时兼容性：**此技能会使用 AskUserQuestion 进行交互式提示（模式选择、逐笔交易确认）。如果运行时不支持 AskUserQuestion，请通过自然语言对话收集相同的参数和确认信息。

概述

这是一个轻量级策略层。它负责执行频率、幂等性、可选的条件检查和防护措施，但不负责执行操作。所有报价、授权、兑换和签名均委托给 swap-integration 和 viem-integration。此技能不会自行构建报价、授权、兑换或签名逻辑。

此技能不会运行调度器。宿主 Agent 的调度器（cron 条目或运行时的唤醒机制）会按计划调用此技能。每次调用都是一次独立、完整的运行：读取状态、判断是否采取行动、视情况执行操作，然后写入状态。

前置条件

• swap-integration（uniswap-trading）：唯一的执行途径。所有兑换都必须通过其 Trading API 流程（依次执行 check_approval、quote、swap，然后签名并广播）。请勿重新实现其中任何部分。
• viem-integration（uniswap-viem）：账户、客户端、签名、交易广播和收据等待。

执行操作前，请阅读以下插件参考资料，并将其视为准确信息来源：

• 所选目标链模板：链 ID、链名称、合约地址、可交易代币来源、资金限制、市场数据可用性和模板特定注意事项。Robinhood Chain 参考模板请参见 ../../references/robinhood-chain.md。
• ../../references/execution-model.md：Trading API 要求、执行模式、限制和免责声明规则。
• ../../references/strategy-state.md：共享状态文件和调度器模式。

模板输入

所选目标链模板必须提供：

• 链 ID、链名称、原生 Gas 代币以及 RPC／读取路径。
• 委托执行所需的已部署 Uniswap 路由器、Permit2 和报价器／状态读取器地址。
• 可交易代币的解析规则，包括任何代币列表或允许列表来源。
• 资金限制和市场数据可用性。
• 转账限制注意事项和市场时段指南。

工作流

步骤 1：读取状态

读取 Bot 的 JSON 状态文件（见状态）。如果文件不存在，则视为首次运行。

步骤 2：检查执行频率和幂等性

根据配置的执行频率计算当前周期（例如，定期 DCA 按 UTC 天计算）。如果状态文件显示当前周期已记录成功买入，则跳过并退出。这样一来，同一周期内重复唤醒也不会导致重复买入。

步骤 3：解析代币和金额

通过读取所选目标链模板及其代币来源，将目标代币解析为地址。从配置中读取固定买入金额。使用前验证二者（见输入验证）。请勿维护本地代币注册表；应复用模板提供的代币列表或解析器。

步骤 4：收集防护措施

读取已配置的防护措施。如果缺少单次运行支出上限或单周期支出上限，请使用 AskUserQuestion（或在不可用时使用自然语言）向操作员询问这些上限；还要说明用于比较的资金代币或计价单位。如果任一上限仍未设置，则不得进入 autonomous 模式。在 confirm 模式下，只能通过逐笔交易确认关卡继续操作，并告知操作员 autonomous 模式仍不可用。

步骤 5：可选条件检查

如果配置了条件（例如“仅当最后一根日线蜡烛为红色时”），请在买入前进行评估：

• 从 Uniswap 获取条件所需的价格：通过 swap-integration 使用 Trading API /quote。不要将特定交易场所的 API 或非 Uniswap 价格源用于执行数据；参见 ../../references/execution-model.md（数据与定价）。如果条件需要 Uniswap 未提供的市场数据，则应将该数据源视为不可用，而不是添加外部依赖。
• 评估谓词（例如 price < 3000 USDC）。
• 如果条件不满足，记录评估结果、跳过买入并退出。因条件不满足而跳过是正常结果，不是错误。

如实说明目前哪些条件可以满足。价格阈值条件（例如“仅当 ETH 低于 X 时买入”）开箱即用，因为当前价格来自 Trading API /quote。

步骤 6：护栏

在任何支出发生前，执行当前执行模式对应的护栏（参见执行模式）：单次运行和每个周期的支出上限、代币允许列表以及紧急停止开关。如果任何护栏阻止了买入，请停止并说明原因。

同时检查钱包是否有足够资金完成买入：钱包必须持有足够的资金代币（tokenIn）来支付买入金额，并持有足够的原生代币来支付 Gas 并广播交易。如果任一余额不足，请跳过买入并报告。遵循所选模板的资金限制；除非技能之外明确提供了相关行为，否则技能不会自动注资、跨链桥接或补足余额。

步骤 7：委托执行兑换

将执行交给 swap-integration Trading API 流程。传入目标链 ID，以及所选模板中该链的路由器／代币地址。技能绝不能自行构建报价、授权、兑换或签名逻辑；它只提供参数（swapper、tokenIn、tokenOut、amount、chain id），并读取返回结果。

如果所选模板对 RPC 或原始交易设有限制，应将其视为模板注意事项。无论链为何，技能始终通过 Trading API／路由器路径执行，因此与路由器兼容的限制不应阻止技能执行。

步骤 8：更新状态

广播成功后，将当前周期、时间戳和生成的交易哈希写入状态文件，以确保下一次唤醒时操作幂等。失败时，记录错误并保持周期未标记，以便后续唤醒时重试。

执行模式

运行该 Agent 的操作者会选择执行模式。完整模式说明请参见 ../../references/execution-model.md。

模式	行为
confirm（默认）	广播前通过 AskUserQuestion 请求用户批准交易，并显示代币、金额、链和预估 Gas。复用 swap-integration 的支出门控。
autonomous	无需逐笔交易提示即可执行，但仅限于护栏允许的范围内。

默认使用 confirm。autonomous 模式必须满足以下全部条件：设置单次运行和每个周期的支出上限、设置代币允许列表、先执行试运行，并设置紧急停止开关。缺少任一条件时，回退到 confirm。

状态

遵循 ../../references/strategy-state.md 中的共享模式。dca-bot 会保留一个小型 JSON 状态文件，以便运行时了解之前的运行情况。建议的结构：

• lastBuyPeriod 是幂等键：每个周期最多买入一次。执行操作前，将当前周期与 lastBuyPeriod 比较；只有在确认交易已广播后才更新它。
• lastAction 是上一次执行的操作：交换，或因防护规则或条件而跳过。记录操作类型、交易哈希和金额。

限制与免责声明

RWA 门控因模板而异，可能在代币层面实施（受转账限制的 ERC-20），因此即使路由器接受了交换，交易也可能在转账时回滚。请参阅 ../../references/execution-model.md。该技能必须：

1. 妥善处理转账限制导致的回滚，记录并报告，不得盲目重试。
2. 遵守所选模板关于股票市场交易时段的指导；某些 RWA 在非交易时段可能流动性受限，因此可能会跳过或延迟买入。
3. 向操作员展示仓库根目录中的财务免责声明 DISCLAIMER.md。

输入验证

在将任何用户提供的值或配置值插入命令、API 调用或生成的代码之前：

• 代币 / 钱包地址：必须匹配 ^0x[a-fA-F0-9]{40}$；否则拒绝。
• 金额：必须是非负数值，并匹配 ^[0-9]+\.?[0-9]*$。
• 链 ID：必须是操作员配置的目标链 ID，从所选模板中读取，不得硬编码。
• API 密钥：必须来自环境变量，不得硬编码。
• 拒绝任何包含 shell 元字符的输入：;、|、&、$、`、(、)、>、<、\、'、" 或换行符。