ポリシーリファレンス

spendctl.yaml は起動時に検証され、知らないキーはエラーになります。金額は USD の文字列（"0.05"、"$0.05"）、期間は "30s"、"10m"、"24h"、"7d" の形式です。

version: 1
signer: { type: cdp }            # mock | cdp | private-key
server: { host: 127.0.0.1, port: 8402, connect: tunnel, upstreamTimeout: 30s }
agentAuth: header                # header（ローカル開発向け） | token（`spendctl token <agent>` で発行）
defaultAgent: researcher         # 任意: エージェント名が無いリクエストに使う
approvals:
  timeout: 10m
  hold: true                     # false にすると承認 ID を返し、X-Spendctl-Approval を付けた再送を待つ
  webhooks: [{ url: https://…, format: slack, secretEnv: SPENDCTL_WEBHOOK_SECRET }]
  publicUrl: https://spendctl.internal.example   # 確認リンクのベース URL
circuitBreaker: { failures: 3, cooldown: 5m }
idempotencyWindow: 10m
assets: []                       # 価格を付けられる資産の追加（MPP のトークン通貨など）
defaults: { … エージェント用のキー … }   # 全エージェントにマージされる（deny は累積）
agents:
  <name>: { … エージェント用のキー … }

エージェント用のキー

キー	意味
mode	enforce（既定）または dry-run
budget.perRequest	1回の支払いの上限
budget.hourly / daily / weekly / monthly	予約済み・決済済み・結果不明の合計に対するローリング期間（1時間・24時間・7日・30日）
onBudgetExceeded	deny（既定）または approve（人間の判断を待つ）
requireApprovalAbove	この額以上の支払いは必ず人間が確認
allow	支払ってよいホスト／パスのパターン。省略するとすべて
deny	支払ってはいけないパターン（最初に判定）
payTo	ホストのパターン → 許可する受取アドレスの対応
protocols	["x402", "mpp"] の部分集合
networks	CAIP-2 の ID。ワイルドカード可：["eip155:84532"]、["eip155:*"]
assets	シンボルまたはアドレス。例：["USDC"]
maxChainDepth	エージェント間の連鎖の最大段数（baggage: spend.depth から読む）
firstPaymentMax	初めての（ホスト、受取先）への支払いがこれを超えたら人間が確認
priceJumpFactor	同じエンドポイントの前回価格の N 倍を超えたら人間が確認
maxTimeoutSeconds	署名してよい認可の最長有効期間（既定 900 秒）

パターンの書き方

api.example.com          そのホストの全パス（ポートは問わない）
api.example.com:8443     そのポートだけ
*.example.com            サブドメイン（apex は含まない）
api.example.com/v1/*     パスの前方一致
*                        すべて

判定の順序

未登録のエージェント → 連鎖の深さ → サーキットブレーカ → deny → allow → 選択肢ごとの絞り込み（プロトコル、署名できるスキーム、ネットワーク、資産、価格の有無、payTo、有効期間）→ 条件を満たす最安の選択肢 → 1回あたりの上限 → 期間予算 → 承認しきい値 → 初回支払い → 価格の急変。deny は常に approve より優先され、人間が免除できるのは approve 理由だけです。