agentpay

agentpay

AI エージェントによる決済のための、決済レール横断型の支出ポリシーゲートウェイです。エージェントと、エージェントに課金するあらゆるサービス（x402 形式の有料 API、Alipay／WeChat 形式のエージェント決済、今後登場するあらゆるもの）の間に位置し、決済を行うエージェントを導入するすべての企業が答えなければならない、次の問いに答えます。

「エージェントに、自分のウォレットを渡さずに、複数の決済レールを使ってお金を使わせるにはどうすればよいか？」

エージェントが決済認証情報を持つことはありません。有料リソースにはゲートウェイ経由でアクセスし、ゲートウェイは次の処理を行います。

1. 402 Payment Required のハンドシェイクを傍受し、加盟店が受け付けるすべての決済方法を取得します。
2. 1つの決済レールにルーティングします（エージェントの希望する決済レールを優先し、同順位の場合はポリシーの基準通貨で最も低コストの方法を選びます）。
3. そのエージェントの支出ポリシーに照らして決済を確認します。予算と上限額は1つの基準通貨で指定され、正確な為替換算を通じて、すべての決済レールと通貨で適用されます。
4. 承認された決済を、選択した決済レールで実行します。
5. 決済証明を付けてリクエストを再試行し、アクセス可能になったレスポンスを返します。
6. 拒否も含むすべての判断を、追記専用の監査ログに記録します。

                       ┌────────────────────────────────────────────────┐      ─▶ paid API (x402, USDC)
  agent ──HTTP──▶      │  gateway                                       │
  (no keys, no wallet) │  policy ─ fx ─ router ─ ledger ─ audit ─ rails │      ─▶ paid API (Alipay, CNY)
                       └────────────────────────────────────────────────┘      ─▶ ...

_{組み込みダッシュボード（GET /admin）— 現在の支出と予算、決済レール別の内訳、保留中の決済をワンクリックで承認／拒否できます。}

仕組みとその理由（設計原則、402 リクエストの全ライフサイクル、シンプルな部分の拡張方法）については、docs/ARCHITECTURE.mdをご覧ください。

どこに位置するか — 中立的なレイヤー

各プラットフォームはエージェントに支出させようと競い合い、それぞれがクローズドループを構築しています。Alipay の委任決済プロトコル ACT、ユーザーが設定した認証範囲と支出上限を備えた WeChat Pay の隔離された「AI カード」、暗号資産ネイティブの API 向けの x402 などです。どのプラットフォームも、エージェントに自社のウォレットで、自社の決済レールを使って支出させようとしています。そして、各社が収束しつつある設計（実際のアカウントから隔離されたウォレット、範囲を限定した認証、支出ごとの上限、高額決済の確認保留、完全な監査証跡）は、まさにこのプロジェクトが構築しようとしている制御面です。この見立ては、もはや憶測ではありません。大手各社が設備投資を向けている先なのです。

しかし、実際にエージェントを運用する企業は、1つのループだけで済ませることはできません。エージェントは USDC で x402 API に支払い、CNY でベンダーに支払い、次の四半期に登場するものにはその決済方法で支払います。そして、それらすべてを横断して、中立的な視点を提供するプラットフォームは存在しません。1つの基準通貨での予算、1つの監査証跡、1つのポリシー、そしてエージェントが決済認証情報を持たない1つの場所です。クローズドループの分断が進むほど、それらを横断するレイヤーがより必要になります。

そのレイヤーが agentpay です。x402、Alipay、WeChat、mock などの決済レールの上位に位置し、2つのメソッドからなるインターフェース（rails/rail.ts）を介して、予算、ポリシー、為替、ルーティング、監査を一度だけ実装し、その下に各決済レールを接続します。決済レールに依存せず、設計上セルフホスト可能です。その価値はまさに、自社独自のループを所有しようと競い合う各プラットフォームが、あなたのために構築することのない部分にあります。

クイックスタート

npx agentpay-gateway      # gateway on http://127.0.0.1:4020, dashboard at /admin (mock rails)

ソースから実行する場合：

npm install
npm test        # 110 tests: money, FX, policy, x402 v1+v2, MCP, persistence, approvals, security, e2e
npm run demo    # walkthrough: 2 rails, 2 currencies, 1 unified USD budget, human-in-the-loop
npm run dev     # start the gateway on :4020 (dashboard at http://localhost:4020/admin)

デモでは、USDC（x402 方式）またはCNY（Alipay 方式）を受け付ける加盟店が実行されます。決済手段の希望が異なる 2 つのエージェントには、それぞれ別の決済手段が割り当てられますが、どちらにも同じ USD 予算が適用されます。0.36 CNY の購入では、その予算から約 0.0504 USD が消費されます。トランザクションごとの上限、支払い先のブロックリスト、予算の枯渇、決済手段ごとの支出内訳、監査ログもすべて確認できます。

エージェントスキルとしてインストールする

skill/ にはすぐにインストールできるエージェントスキルが用意されています。AI アシスタント（Claude Code、OpenClaw、…）が手順に沿って agentpay をセットアップします。インストールとセルフテスト、デフォルトで拒否するポリシーの作成、ゲートウェイの起動、エージェントの有料リクエストの転送先を /proxy に変更し、支出、監査、承認、ポリシーのリアルタイム編集といった運用を行ったうえで、本番環境向けに強化します。ポリシーテンプレートとトラブルシューティングおよび API リファレンスも含まれています。アシスタントにskill/SKILL.mdを指定するか、スキルマーケットプレイスからインストールしてください。

Claude / Cursor から使用する（MCP）

上限を超過できない予算を MCP エージェントに設定できます。agentpay-mcp サーバーが保持するのはエージェントのゲートウェイ API キーだけです。ウォレットと上限はゲートウェイに保管されます。自己申告に頼る予算ツールとは異なり、エージェントが予算の確認を「求められる」ことはありません。上限を超える支払いは署名されません。

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "-p", "agentpay-gateway", "agentpay-mcp"],
      "env": { "AGENTPAY_URL": "http://127.0.0.1:4020", "AGENTPAY_API_KEY": "<key from POST /admin/keys>" }
    }
  }
}

ツール：paid_fetch(url, method?, body?) — 任意の URL にリクエストを送信します。ポリシーで許可されている場合、ゲートウェイが x402/402 に対する支払いを行います。拒否や承認待ちはツールエラーとして返され、モデルが説明できます。check_budget() — 今日／今月の支出額と上限を確認します（エージェントにスコープされた GET /v1/budget を使用するため、エージェント自身の数値のみが表示されます）。

ポリシー

ポリシーはデフォルトで拒否されます。ポリシーにエントリーがないエージェントは、いっさい支出できません。policies/example.json を参照してください。

{
  "fxRates": { "USDC:USD": "1", "CNY:USD": "0.14" },  // directional pairs, exact decimals
  "defaults": { "currency": "USD", "perTransactionMax": "1.00", "dailyBudget": "10.00" },
  "agents": [
    {
      "agentId": "research-bot",
      "enabled": true,
      "currency": "USD",                        // base currency for ALL limits below
      "railPreference": ["alipay-act", "x402"], // routing order when merchants accept several rails
      "perTransactionMax": "0.25",              // cap on any single payment, in base currency
      "dailyBudget": "0.15",                    // UTC calendar day, across all rails/currencies
      "monthlyBudget": "3.00",                  // UTC calendar month
      "maxTransactionsPerDay": 200,
      "requireApprovalOver": "0.50",            // hold payments >= this for human review (base ccy)
      "payeeBlocklist": ["merchant-shady"]
      // or "payeeAllowlist": [...] to whitelist instead
    }
  ]
}

すべての金額は正確な小数で扱われます（bigint のマイクロ単位、6 桁 — USDC の精度）。FX 換算は切り上げて、予算が保守的に適用されるようにします。金額の計算に浮動小数点数は一切使いません。基本通貨への為替レートが設定されていない通貨での支払いは拒否されます（no_fx_rate）。

API

エンドポイント	用途
ANY /proxy?url=<target>	リクエストをプロキシします。ポリシーで許可されている場合、ルーティングし、402 に対する支払いを行います。エージェントの識別には Authorization: Bearer <api key>（キーが設定されている場合）または X-Agent-Id を使用します。
GET /admin	Web ダッシュボード（単一の自己完結型ページ）です。支出のリアルタイム表示、保留中の承認（承認／拒否ボタン付き）、監査ログ、ポリシーのインライン編集を確認できます。
GET /admin/policy	現在有効なポリシー設定全体を取得します。
GET /admin/agents	設定済みのエージェントと、適用される上限を取得します。
PUT /admin/agents/:id	エージェントのポリシーを作成または置き換えます（検証あり）。次のリクエストから反映され、ポリシーファイルにも書き戻されます。
DELETE /admin/agents/:id	エージェントを削除します（デフォルトで拒否する状態に戻ります）。
GET /admin/keys · POST /admin/keys · DELETE /admin/keys/:id	マルチテナント API キーの一覧表示、発行（シークレットは一度だけ返されます）、取り消しを行います。
GET /admin/spend/:agentId	基本通貨での支出額と上限、および決済手段ごとの現地通貨での内訳を取得します。
GET /admin/audit?agent=&limit=	すべての許可／拒否／失敗／保留の監査ログを取得します。
GET /admin/approvals?status=	人による確認のため保留されている支払いの一覧を取得します（pending／approved／rejected で絞り込みます）。
POST /admin/approvals/:id	保留中の支払いを判断します。本文は { "decision": "approve" | "reject" } です。
GET /healthz	稼働状態を確認します。

支払いが成功したレスポンスには、X-Gateway-Payment-Id、X-Gateway-Rail、X-Gateway-Payment-Amount ヘッダーが含まれます。拒否された場合は、違反したルール ID（per_transaction_max、daily_budget、payee_blocklisted、no_fx_rate、approval_rejected、…）とともに 403 が返されるため、エージェントは理由を説明したり、処理を控えたりできます。

ヒューマン・イン・ザ・ループ承認

エージェントに requireApprovalOver を設定すると、その基準通貨額以上のポリシーで承認された支払いは実行されず、保留されます。プロキシは支払いの代わりに approvalId とともに 202 を返します。オペレーターは POST /admin/approvals/:id を使って承認または拒否できます。その後、エージェントが再試行すると、承認済みの場合は実行され、拒否済みの場合は approval_rejected で拒否されます。各承認は1回限りで、1件の支払いだけを許可します。再試行時の実行時点で、予算は再確認されます。

永続化

デフォルトでは、台帳、監査ログ、承認情報はメモリ上に保存されます。状態を再起動後も保持するには、いずれかをファイルに指定します。.sqlite はトランザクション対応の SQLite バックエンド（Node 組み込みの node:sqlite を使用し、追加の依存関係は不要）を選択し、それ以外は追記専用の JSONL になります。

LEDGER_FILE=./ledger.sqlite AUDIT_FILE=./audit.jsonl APPROVALS_FILE=./approvals.sqlite APIKEYS_FILE=./keys.sqlite npm run dev

ライブ FX レート

静的な通貨ペアには FixedRateProvider が適しています。CachingRateProvider は、TTL と厳格な有効期限を設定して、任意の非同期レートソース（RateFetcher。デフォルトの httpRateFetcher は exchangerate.host にアクセスします）をラップします。有効期限を過ぎると、キャッシュ済みのレートは拒否され（no_fx_rate）、使用されません。支払いが古いレートで換算されることはありません。ステーブルコインのペッグは pinned に設定すると、期限切れや取得が発生しなくなります。

ポリシーの編集（ライブ）

ポリシーは実行中に変更でき、再起動は不要です。PolicyManager がライブ設定を管理し、すべての判断はこの設定を参照するため、編集内容は次のリクエストから反映されます。変更方法は2つあり、どちらも同期されます。

• 管理 API／ダッシュボード — PUT／DELETE /admin/agents/:id（ダッシュボードの編集用鉛筆アイコンと「エージェントを追加」ボタンから操作できます）。各編集は検証され、policy_changed として監査ログに記録され、ポリシーファイルに書き戻されます。
• ファイル自体 — npm run dev はポリシーファイルを監視し、外部からの編集をホットリロードします。書き戻しと監視機能は競合しません。ファイルの内容がメモリ上の状態とバイト単位で一致する場合、reload() は何も行わないため、自身による書き込みがリロードループを引き起こすことはありません。（fxRates は起動時に一度だけ作成され、ホットリロードされません。）

マルチテナント API キー

エージェントは Authorization: Bearer <key> で認証します。キーはエージェントごとに POST /admin/keys またはダッシュボードから発行でき、1つのエージェントで複数のキーを保持してローテーションできます。プレーンテキストのシークレットが返されるのは一度だけです。保存されるのは SHA-256 ハッシュのみなので、保存データが漏えいしても使用可能な認証情報は含まれません。キーには有効期限を任意で設定でき、即座に失効させることもできます（DELETE /admin/keys/:id）。どちらの操作も監査ログに記録されます（apikey_created／apikey_revoked）。

デフォルトでは、有効な Bearer キーで認証でき、X-Agent-Id も引き続き使用できます（ローカル開発に便利です）。REQUIRE_API_KEY=1（または requireApiKey: true）を設定すると、X-Agent-Id は拒否され、有効なキーでのみ認証できるようになります。APIKEYS_FILE=./keys.sqlite を設定すると、再起動後もキーが保持されます。

決済レール

レールは単一のインターフェース（src/rails/rail.ts）を実装します：supports(network) と pay(ctx) -> receipt です。レールを追加しても、ポリシー、FX、ルーティングのコードには触れません。以下が含まれます。

• MockRail — プロセス内ですぐに決済します。複数のレールをインスタンス化して、マルチレール構成をシミュレートできます。
• X402Rail — Coinbase の x402 プロトコル向けのアダプターで、実際のクライアント側決済実装を備えています。createEip3009Signer は、Base／Base Sepolia 上の USDC 用に、署名済みの EIP-3009 transferWithAuthorization ペイロードを生成します。x402 v1 と v2 の両方に対応します。v1（X-PAYMENT、ボディ要件）と v2（PAYMENT-REQUIRED／PAYMENT-SIGNATURE／PAYMENT-RESPONSE ヘッダー、eip155:84532 のような CAIP-2 ネットワーク、アトミックな amount、選択された要件をそのまま返す accepted）をサポートします。Permit2 のみを要求する要件は、誤った署名を行わずに拒否します。署名は完全にオフラインで行われ、加盟店のファシリテーターがオンチェーンで決済します。検証は 2 つの方法で行っています。テストスイートでは署名を暗号学的に検証し、さらに、このレールで Base Sepolia 上の実際の決済をエンドツーエンドで完了しています（以下を参照）。
• AlipayActRail — Alipay のエージェント決済スタック（ACT 委任モデルに基づく AI付）に合わせたアダプターです。executePayment を通じて、加盟店側の連携処理を組み込めます。

認証情報は、提供するレールのコールバック内に保持されます。ゲートウェイのコアが鍵に触れることはありません。今後の予定：Google AP2。

Base Sepolia で実際の x402 リソースを購入する

これは実際に実行済みです。ゲートウェイは、ETH をまったく保有していないウォレットから、Coinbase がホストするテストネットファシリテーターを通じて、Base Sepolia 上で 0.01 USDC の決済を完了しました（ガス代はファシリテーターが支払うため、x402 では支払者にガス代がかかりません）。オンチェーンの証明：0x3108b5…54ff9d（x402 v1）。その後、x402 v2 でも同じ方法で、Coinbase 公式の @x402/express 2.27 の加盟店に対する決済を完了しました：0x8c0256…f668c5。

再現するには — 公開テストネットのエンドポイントは利用できたりできなかったりするため、確実な方法はローカルの x402 加盟店を使うことです。

# 1. fund a throwaway wallet with testnet USDC: https://faucet.circle.com (Base Sepolia)

# 2. run a local x402 merchant settling on base-sepolia (official middleware + hosted facilitator)
mkdir x402-merchant && cd x402-merchant && npm init -y && npm i x402-express express
cat > server.mjs <<'JS'
import express from "express";
import { paymentMiddleware } from "x402-express";
const app = express();
app.use(paymentMiddleware("0xYourMerchantAddress", {       // any address — it just receives the USDC
  "/premium": { price: "$0.01", network: "base-sepolia", config: { description: "x402 test" } },
}));
app.get("/premium", (_q, r) => r.json({ message: "unlocked by a real on-chain payment" }));
app.listen(4021, () => console.log("merchant on http://localhost:4021/premium"));
JS
node server.mjs

# 3. buy it through the gateway (signs EIP-3009 offline, facilitator settles on-chain)
X402_PRIVATE_KEY=0x... TARGET_URL=http://localhost:4021/premium npx tsx demo/x402-live.ts

または、TARGET_URL を base-sepolia 上で決済を完了できる任意の稼働中の x402 リソースに設定してください。

セキュリティ

資金を扱うため、制御プレーンも計算処理だけでなく強化されています。

• 管理 API 認証 — ADMIN_TOKEN を設定すると、すべての /admin/* データ／変更エンドポイントで認証が必須になります（Authorization: Bearer または X-Admin-Token。定時間比較を使用）。未設定の場合、管理 API は公開状態となるため、CLI はデフォルトで 127.0.0.1 にバインドされ（HOST で変更可能）、起動時に警告します。ダッシュボードはトークンを保持します（/admin#token=… 経由で一度設定してください）。
• SSRF ガード — /proxy は、デフォルトでプライベート／ループバック／リンクローカル範囲に解決されるターゲットを拒否します（169.254.169.254 のクラウドメタデータ IP を含む）。ガードは固定した DNS ルックアップを介して接続時に実行され、リダイレクトの各ホップでも再適用されるため、DNS リバインディングや内部宛てへのリダイレクトをすり抜けることはできません。ローカルテストの場合に限り、allowPrivateTargets を有効にしてください。
• x402 アセットの許可リスト — 署名者は、ネットワークごとの許可リストにないトークンに対する EIP-3009 認証への署名を拒否します（デフォルトは正規の USDC）。これにより、悪意のある 402 がウォレットをだまして、別の、より価値の高いトークンの送金を認証させることはできません。認証の有効期間には上限が設けられます（maxAuthorizationSeconds）。
• 並行処理時の二重支払いを防止 — エージェントごとに判定→実行→記録の処理区間を直列化するため、記録前に複数の支払いが同時に予算チェックを通過することはありません。
• DoS 制限 — リクエストボディーは最大 1 MiB（413）、アップストリームのフェッチは 30 秒でタイムアウトし、アップストリームのレスポンスはストリーミングされます（全体をメモリにバッファーしません）。
• 資金の整合性 — 正確な bigint 演算（浮動小数点数は使用しません）、API キーは SHA-256 ハッシュのみを保存（生のシークレットは一度だけ表示）、アップストリームの Authorization ヘッダーは転送しません。

デプロイ時のチェックリスト： ADMIN_TOKEN を設定し、REQUIRE_API_KEY=1 を有効にし、allowPrivateTargets をオフのままにして、ゲートウェイを TLS の背後に配置してください。脅威モデル、強化項目の一覧、チェックリストの全文は docs/SECURITY.md を参照してください。

ステータスとロードマップ

これは MVP です。ポリシーエンジン、FX レイヤー、クロスレールルーター、台帳、監査ログ、承認、永続化、402 プロキシフローはテスト済みで、モックの決済レールに対するエンドツーエンドの動作が確認されています。x402 レールでは Base Sepolia 上で実際の支払いが決済されています。初回リリース以降に完了した項目：

• キャッシュと鮮度制限を備えたライブ FX レートプロバイダー（CachingRateProvider）
• JSONL を超える永続ストレージ — node:sqlite によるトランザクション対応 SQLite
• 人間が介在する承認（「$X を超える支払いをレビュー用に保留」）
• 支出、監査、承認、ポリシー編集用の Web ダッシュボード（GET /admin）
• ポリシーのホットリロードと、ポリシー編集用の管理 API
• マルチテナントの API キー管理（キーのハッシュ化、発行／失効、キーごとの有効期限）
• 公式 v2 マーチャントに対するエンドツーエンドの x402 v2 決済 — Base Sepolia 上で 0.01 USDC
• 稼働中のファシリテーターに対するエンドツーエンドの x402 決済 — Base Sepolia 上で 0.01 USDC を決済（再現方法：上記）

未実装：

• 実際の Alipay AI付／ACT 決済（加盟店登録が必要です）