dca

DCA — Stacks DeFi 向けドルコスト平均法

Bitflow で直接スワップして、Stacks メインネットでトークンの定期購入（または売却）を自動化します。 エージェントがスケジュールに従って各注文を実行します。サードパーティのコントラクトは不要です。

仕組み

1. setup が、スケジュール全体を含むローカルのプランファイルを作成します
2. run は各スケジュールのタイミングで、エージェントによって呼び出されます（cron またはハートビート経由）
3. 各 run は注文の実行時期を確認し、最新の見積もりを取得して、--confirm が指定されるまで blocked を返します
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 を変更します。これは一度限りのセットアップ手順です。通常のエージェント操作中や、複数のプロセスが稼働している可能性のある共有環境では呼び出さないでください。

依存関係

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 あり： オンチェーンでスワップを実行し、トランザクションハッシュを記録して、スケジュールを進めます。

セキュリティ： --wallet-password フラグよりも AIBTC_WALLET_PASSWORD 環境変数を使用してください。CLI フラグは ps aux の出力やシェルの履歴に表示されるため、長時間稼働するエージェントプロセスでは実際のリスクになります。--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 に保存されます。完全なプラン設定、すべての tx ハッシュ、注文ごとの実行ログ、実行中の平均コストが含まれます。

ウォレットのサポート

ウォレットのソースは3種類あります（以下の順に確認）：

1. STACKS_PRIVATE_KEY 環境変数（直接指定、テスト用）
2. AIBTC MCP ウォレット（~/.aibtc/wallets.json + キーストア — AES-256-GCM + scrypt）
3. レガシー形式の ~/.aibtc/wallet.json

既知の制約

• メインネットのみ
• 資金のあるウォレットが必要（ガス代用の STX + スワップ入力トークン）
• Bitflow API に接続できる必要があります（レート制限は毎分500リクエスト）
• すべてのトークンペアにルートがあるわけではありません。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分の1で、手数料の過少設定により nonce が停止するリスクがありました。STX 残高の事前チェックでは、トランザクションが支払うのと同じ額を確保します。DCA_FEE_USTX が空、または形式が不正な場合は、ゼロ手数料のトランザクションを黙ってブロードキャストせず、明示的にエラーになります。