dca-bot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DCA Bot

DCA 机器人

Dollar-cost-average a fixed amount into a token on a schedule on the operator's target chain, optionally gated on a price condition such as "only buy when ETH is below a threshold".

Runtime Compatibility: This skill uses
AskUserQuestion
for interactive prompts (mode selection, per-transaction confirmation). If
AskUserQuestion
is not available in your runtime, collect the same parameters and confirmations through natural language conversation instead.

通过美元成本平均（Dollar-cost-average）策略，按计划在操作者的目标链上向指定代币投入固定金额，可选择设置价格条件（例如「仅当ETH低于阈值时才买入」）作为门槛。

运行时兼容性： 本Skill使用
AskUserQuestion
进行交互式提示（模式选择、逐笔交易确认）。如果你的运行时不支持
AskUserQuestion
，请通过自然语言对话收集相同的参数并完成确认。

Overview

概述

This is a thin strategy layer. It owns cadence, idempotency, the optional condition check, and guardrails. It does NOT own execution. Every quote, approval, swap, and signature is delegated to

swap-integration

and

viem-integration

. The skill never builds quote, approval, swap, or signing logic itself.

The skill does not run a scheduler. The host agent's scheduler (a cron entry or the runtime's wake mechanism) invokes the skill on a cadence. Each invocation is a single, self-contained run that reads state, decides whether to act, optionally acts, and writes state.

这是一个轻量策略层，负责管理执行周期、幂等性、可选条件检查以及风控规则，不负责实际执行。所有报价、授权、兑换和签名操作都委托给

swap-integration

和

viem-integration

处理。本Skill自身从不实现报价、授权、兑换或签名逻辑。

本Skill不运行调度器。宿主Agent的调度器（cron任务或运行时的唤醒机制）会按固定周期调用本Skill。每次调用都是一次独立完整的运行，流程包括：读取状态、判断是否执行、可选执行操作、写入状态。

Prerequisites

前置条件

swap-integration (uniswap-trading): the only execution path. All swaps go through its Trading API flow (
```
check_approval
```
then
```
quote
```
then
```
swap
```
, then sign and broadcast). Do not reimplement any of it.
viem-integration (uniswap-viem): accounts, clients, signing, transaction broadcast, and receipt waiting.

Read these plugin references before acting and treat them as ground truth:

selected target-chain template: chainId, chain name, contract addresses, tradable token source, funding constraints, market-data availability, and template-specific caveats. For the reference Robinhood Chain template, see
```
../../references/robinhood-chain.md
```
.
```
../../references/execution-model.md
```
: the Trading API requirement, execution modes, restrictions, and disclaimer rules.
```
../../references/strategy-state.md
```
: the shared state file and scheduler pattern.

swap-integration（uniswap-trading）：唯一的执行路径。所有兑换操作都通过其Trading API流程执行（
```
check_approval
```
→
```
quote
```
→
```
swap
```
，然后签名并广播）。请勿重新实现任何相关逻辑。
viem-integration（uniswap-viem）：负责账户、客户端、签名、交易广播以及交易回执等待。

执行操作前请阅读以下插件参考文档，并以其为准：

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

Template inputs

模板输入

The selected target-chain template must provide:

chain id, chain name, native gas token, and RPC / read path.
deployed Uniswap router, Permit2, and quoter / state-reader addresses needed by delegated execution.
tradable token resolution rules, including any token list or allowlist source.
funding constraints and market-data availability.
transfer-restriction caveats and market-hours guidance.

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

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

Workflow

工作流程

Step 1: Read state

步骤1：读取状态

Read the bot's JSON state file (see State). If it does not exist, treat this as the first run.

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

Step 2: Check cadence and idempotency

步骤2：检查执行周期与幂等性

Compute the current period from the configured cadence (for example the UTC day for a daily DCA). If the state file shows a successful buy already recorded for the current period, skip and exit. This makes repeated wakes within one period safe (no double buys).

根据配置的执行周期计算当前周期（例如每日DCA的话就是UTC日期）。如果状态文件显示当前周期已记录成功买入，则跳过并退出。这可以保证同一周期内多次唤醒都是安全的（不会重复买入）。

Step 3: Resolve token and amount

步骤3：解析代币与金额

Resolve the target token to an address by reading the selected target-chain template and its token source. Resolve the fixed buy amount from config. Validate both before use (see Input validation). Do not maintain a local token registry; reuse the template-provided token list or resolver.

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

Step 4: Collect guardrails

步骤4：获取风控规则

Read the configured guardrails. If the per-run spend cap or per-period spend cap is missing, ask the operator for those caps using

AskUserQuestion

(or natural language if unavailable); include the funding token or denomination used for comparison. If either cap remains unset, do not enter

autonomous

mode. In

confirm

mode, proceed only with the per-transaction confirmation gate and report that autonomous mode remains unavailable.

读取已配置的风控规则。如果缺少单次运行支出上限或单周期支出上限，请使用

AskUserQuestion

（如果不可用则用自然语言）向操作者询问这些上限；需说明用于对比的资金代币或计价单位。如果任一上限仍未设置，不得进入

autonomous

模式。在

confirm

模式下，仅通过逐笔交易确认门槛继续执行，并告知用户自主模式仍不可用。

Step 5: Optional condition check

步骤5：可选条件检查

If a condition is configured (for example "only when the last daily candle is red"), evaluate it before buying:

Fetch the price needed for the condition from Uniswap: the Trading API
```
/quote
```
(via
```
swap-integration
```
). Do not use venue-specific APIs or non-Uniswap price feeds for execution data; see
```
../../references/execution-model.md
```
(Data and pricing). If the condition needs market data Uniswap does not expose, treat that data source as unavailable rather than adding an external dependency.
Evaluate the predicate (for example
```
price < 3000 USDC
```
).
If the condition is not met, record the evaluation, skip the buy, and exit. Skipping for an unmet condition is a normal outcome, not an error.

Be honest about what is satisfiable today. A price-threshold condition (for example "only buy when ETH is below X") works out of the box, because the current price comes from the Trading API

/quote

如果配置了条件（例如「仅当最近一根日K线收跌时」），请在买入前进行评估：

从Uniswap获取条件所需的价格：通过
```
swap-integration
```
调用Trading API的
```
/quote
```
接口。执行数据请勿使用特定交易场所的API或非Uniswap价格预言机；参见
```
../../references/execution-model.md
```
（数据与定价）。如果条件所需的市场数据未被Uniswap暴露，应视为数据源不可用，而非添加外部依赖。
评估判断条件（例如
```
price < 3000 USDC
```
）。
如果条件不满足，记录评估结果，跳过买入并退出。因条件不满足而跳过是正常结果，并非错误。

请如实告知当前可实现的功能。价格阈值条件（例如「仅当ETH低于X时买入」）可以开箱即用，因为当前价格来自Trading API的

/quote

接口。

Step 6: Guardrails

步骤6：风控校验

Before any spend, enforce the guardrails for the active execution mode (see Execution mode): spend cap per run and per period, token allowlist, and the kill switch. If any guardrail blocks the buy, stop and report why.

Also check the wallet can cover the buy: it must hold enough of the funding token (

tokenIn

) for the buy amount and enough native gas to broadcast. If either is short, skip the buy and report it. Follow the selected template's funding constraints; the skill does not auto-fund, bridge, or top up unless that behavior is explicitly provided outside the skill.

任何支出操作前，需针对当前执行模式强制执行风控规则（参见执行模式）：单次运行支出上限、单周期支出上限、代币白名单以及紧急停止开关。如果任一风控规则阻止了买入，停止操作并说明原因。

同时需检查钱包是否足以支付买入费用：钱包必须持有足够的资金代币（

tokenIn

）以支付买入金额，以及足够的原生Gas以支付广播费用。如果任一不足，跳过买入并上报。请遵循所选模板的资金限制；本Skill不会自动注资、跨链桥接或充值，除非Skill外部明确提供了该功能。

Step 7: Delegate the swap

步骤7：委托兑换

Hand execution to the

swap-integration

Trading API flow. Pass the target chain id and that chain's router / token addresses from the selected template. The skill MUST NOT build quote, approval, swap, or signing logic of its own; it only supplies parameters (swapper, tokenIn, tokenOut, amount, chain id) and reads back the result.

If the selected template has RPC or raw-transaction constraints, treat them as template caveats. Skills always execute through the Trading API / router path regardless of chain, so router-compatible constraints should not block them.

将执行交给

swap-integration

的Trading API流程。传入目标链ID以及所选模板中该链的路由器 / 代币地址。本Skill严禁自行实现报价、授权、兑换或签名逻辑；它仅提供参数（兑换者、tokenIn、tokenOut、金额、链ID）并读取返回结果。

如果所选模板存在RPC或原始交易相关的限制，将其视为模板注意事项。无论在哪条链上，Skill始终通过Trading API / 路由器路径执行，因此兼容路由器的限制不会阻碍执行。

Step 8: Update state

步骤8：更新状态

On a successful broadcast, write the current period, timestamp, and the resulting transaction hash to the state file so the next wake is idempotent. On failure, record the error and leave the period unmarked so a later wake can retry.

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

Execution mode

执行模式

The operator who runs the agent chooses an execution mode. See

../../references/execution-model.md

for the full model.

Mode	Behavior
`confirm` (default)	Ask the user to approve the transaction before broadcast via `AskUserQuestion` , showing token, amount, chain, and estimated gas. Reuses the `swap-integration` spend gate.
`autonomous`	Execute without per-transaction prompts, only within guardrails.

Default to

confirm

autonomous

mode requires all of: a spend cap (per run and per period), a token allowlist, a dry-run first, and a kill switch. Without all four, fall back to

confirm

运行Agent的操作者可选择执行模式。完整模型请参见

../../references/execution-model.md

。

模式	行为描述
`confirm` （默认）	广播前通过 `AskUserQuestion` 请求用户批准交易，展示代币、金额、链以及预估Gas。复用 `swap-integration` 的支出门槛。
`autonomous`	无需逐笔交易提示，仅在风控规则范围内执行。

默认为

confirm

模式。

autonomous

模式需要同时满足以下所有条件：支出上限（单次运行与单周期）、代币白名单、首次空运行、紧急停止开关。缺少任意一项，都将回退到

confirm

模式。

State

状态

Follow the shared pattern in

../../references/strategy-state.md

. The dca-bot keeps a small JSON state file so a run knows what previous runs did. Suggested shape:

```
lastBuyPeriod
```
is the idempotency key: a run buys at most once per period. Compare the current period against
```
lastBuyPeriod
```
before acting, and update it only after a confirmed broadcast.
```
lastAction
```
is the last action taken: a swap, or a skip due to a guardrail or condition. Record the action type, transaction hash, and amount.

遵循

../../references/strategy-state.md

中的共享模式。DCA机器人会维护一个小型JSON状态文件，以便每次运行时了解之前的执行情况。建议的结构如下：

```
lastBuyPeriod
```
是幂等键：每个周期内最多执行一次买入。执行操作前将当前周期与
```
lastBuyPeriod
```
对比，仅在广播确认成功后更新该值。
```
lastAction
```
是最近一次执行的操作：一次兑换，或因风控规则/条件不满足而跳过。记录操作类型、交易哈希以及金额。

Restrictions and Disclaimers

限制与免责声明

RWA gating is template-specific and may be enforced at the token level (transfer-restricted ERC-20s), so a swap can revert at transfer time even when the router accepts it. See

../../references/execution-model.md

. The skill must:

Handle transfer-restriction reverts gracefully, record them, and report them rather than retrying blindly.
Respect the selected template's equity market-hours guidance; some RWAs may have off-hours liquidity limits, so a buy may be skipped or deferred outside hours.
Surface the financial disclaimers in the repo root
```
DISCLAIMER.md
```
to the operator.

RWA门槛是模板特定的，可能在代币层面强制执行（转账受限的ERC-20代币），因此即使路由器接受了兑换，转账时也可能回滚。参见

../../references/execution-model.md

。本Skill必须：

优雅处理转账限制导致的回滚，记录并上报问题，而非盲目重试。
遵守所选模板的股票市场交易时段指引；部分RWA在非交易时段可能存在流动性限制，因此非时段内的买入可能被跳过或推迟。
向操作者展示仓库根目录
```
DISCLAIMER.md
```
中的财务免责声明。

Input validation

输入校验

Before interpolating ANY user-provided or config value into a command, API call, or generated code:

Token / wallet addresses: MUST match
```
^0x[a-fA-F0-9]{40}$
```
; reject otherwise.
Amounts: MUST be non-negative numeric values matching
```
^[0-9]+\.?[0-9]*$
```
.
Chain id: MUST be the operator-configured target chain id, read from the selected template rather than hardcoded.
API keys: MUST come from environment variables, never hardcoded.
REJECT any input containing shell metacharacters:
```
;
```
,
```
|
```
,
```
&
```
,
```
$
```
,
```
`
```
,
```
(
```
,
```
)
```
,
```
>
```
,
```
<
```
,
```
\
```
,
```
'
```
,
```
"
```
, or newlines.

在将任何用户提供或配置的值插入命令、API调用或生成的代码之前，需满足以下要求：

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