Boundra — Payment Approval Gateway for AI Agents

Boundra · AI エージェント向け決済承認ゲートウェイ

Boundra (boundra.io) — エージェント決済に境界を。 エージェント決済の境界レイヤーです。資金が動く前に、「そもそもこの決済を実行すべきか？」に答えます。

私たちの考えはこうです。エージェント決済における機会は、「どう支払うか」（プロトコルで解決済み）ではなく、「支払うべきかどうか」です。

自然言語で記述したルールを1つ、ポリシーにコンパイルし、エージェントが試みるすべての決済を実際に評価します。結果は許可／人間に確認／拒否となり、完全な監査証跡が残ります。

2つの実行モードがあります。

• オフラインシミュレーション（demo.py）：標準ライブラリのみで完結する、モックの加盟店とウォレットを備えた構成です。依存関係もネットワーク接続も不要です。
• 実プロトコル（demo/demo_real.py）：標準の MCP サーバー、実際の x402 SDK、Base Sepolia テストネットを使用します。

データフロー

ポリシーとキーはユーザーの手元に残ります。ゲートウェイは読み取り専用で、オンチェーンに記録されるのはハッシュコミットメントのみです。取り消しは無料で、期限も例外もありません。

Boundra をエージェントに組み込みますか？ ホスト型 API、x402 SDK フック、テスト済みコードを含む MCP の利用方法については、 docs/INTEGRATION.md をご覧ください。

60秒で動作を確認

# 1. Hit the hosted evaluation API — a real, public x402 merchant
curl -X POST https://api.boundra.io/evaluate/basic \
  -H 'Content-Type: application/json' \
  -d '{"intent":{"amount":0.01,"recipient":"api.weather.com","purpose":"weather data"}}'
# → {"decision":"ALLOW",...}  ·  semantic layer: 100 free calls per agent,
#   then $0.003 via x402 — settled for real on Base mainnet (USDC)

# 2. Local end-to-end simulation — a data-procurement agent's day
.venv/bin/python demo/simulate_agent.py
# signed policy publish → ALLOW / DENY (limit) / ASK → user-signed approval token
# → prompt-injection blocked → audit trail, plus a dogfood call to api.boundra.io

# 3. One-line MCP install + 2-minute policy wizard
uvx --from git+https://github.com/gobeyondfj-cmd/boundra boundra-mcp     # stdio server
uvx --from git+https://github.com/gobeyondfj-cmd/boundra boundra-init    # wallet → template → sign → anchor
uvx --from git+https://github.com/gobeyondfj-cmd/boundra boundra-approve # sign an ASK challenge

完全なフローを順を追って説明

ゼロから署名済みの強制適用ポリシーを約10分で作成できます。アカウントもダッシュボードも不要です。ウォレットキーが本人確認に使われます。

0 · ホスト型 API を試す (30秒、インストール不要)

curl -X POST https://api.boundra.io/evaluate/basic \
  -H 'Content-Type: application/json' \
  -d '{"intent":{"amount":0.01,"recipient":"api.weather.com","purpose":"weather data"}}'

1 · ID を紐付ける — ウォレットがアカウントです

uvx --from git+https://github.com/gobeyondfj-cmd/boundra boundra-init

Base ウォレットを作成またはインポートします。登録もメールアドレスも不要です。秘密鍵がデバイスの外に出ることはなく、システム内のどこでもウォレットアドレスがあなたの ID になります。

2 · ポリシーを設定する

ウィザードでは、テンプレート（パーソナルアシスタント／旅行／開発用 API／調達）を選ぶことも、平易な英語で独自のルールを書くこともできます。その後、ルールがコンパイルされ、署名する前に、何がどのように強制適用されるかを正確に確認できます。

3 · 署名して公開する

ウォレットキーを使ってポリシー文書に署名します（EIP-191）。文書はバージョン付きで公開され、ハッシュコミットメントがオンチェーンに記録されます。この時点から、すべてのエージェントに対してゲートウェイは読み取り専用になります。あなたのキーなしでポリシーを変更することはできません。

4 · MCP サーバーをエージェントにマウントする

ホスト型（インストール不要、マルチテナント対応。署名済みポリシーを公開するまではデフォルトで拒否）：

{ "mcpServers": { "boundra": { "url": "https://api.boundra.io/mcp" } } }

またはセルフホスト型：

{ "mcpServers": { "boundra": { "command": "uvx",
  "args": ["--from", "git+https://github.com/gobeyondfj-cmd/boundra", "boundra-mcp"] } } }

5 · 署名の前に、すべての決済が判定される

エージェントが evaluate_payment を呼び出すと、5段階のパイプラインが ALLOW（署名して決済を確定）／DENY（署名前に中止され、オンチェーンの記録は一切なし）／ASK（この決済に紐付いたチャレンジ）を返します。

6 · エージェントから確認を求められたら、自分で判断する

uvx --from git+https://github.com/gobeyondfj-cmd/boundra boundra-approve

ASK チャレンジを貼り付け、デバイス上で署名します。エージェントは署名済みの承認トークンを使って再試行します。偽造、再紐付け、リプレイされたトークンは拒否されます。

7 · 状況を確認し、更新し、取り消す

get_spend_report ／ get_audit_trail ／ get_policy_versions を使って、日々の管理を続けられます。ポリシーを変更するたびに、新しい署名済みバージョンが作成されます（set_policy）。revoke_policy は即座にデフォルト拒否へ切り替わり、永久に無料です。

クイックスタート（ソースから）

cd boundra

# Mode 1: offline simulation (run this first — the full flow in 30 seconds)
python demo/demo.py

# Mode 2: real x402 + MCP
python -m venv .venv && .venv/bin/pip install \
    "x402[evm,httpx]" mcp eth-account fastapi uvicorn
.venv/bin/python tests/test_mcp_client.py    # MCP protocol-level tests
.venv/bin/python demo/setup_wallets.py       # generate Base Sepolia test wallets + faucet guide
.venv/bin/python demo/demo_real.py           # real protocol end-to-end (settles on-chain after funding)

アーキテクチャ：ゲートウェイの役割

Agent framework (Claude / custom)
   │  MCP protocol (stdio)
   ▼
mcp_server.py  ──→  policy.py 5-stage evaluation pipeline
(policy decision     semantic → whitelist → limit → approval → budget
 point)
   ▲
   │ on_before_payment_creation hook (x402 SDK v2 native interception point)
x402_buyer.py ──sign (EIP-3009)──→ x402 server ──→ facilitator ──→ Base Sepolia

主な発見：x402 SDK v2 は、on_before_payment_creation フックに加えて register_policy ／ set_spend_controls を標準で提供しています。ポリシーレイヤーは後付けではなく、公式プロトコルスタックが用意した枠組みです。これにより、この戦略の有効性が裏付けられます。

ファイル一覧

boundra/
├── policy.py                 intent compilation (NL→Policy, bilingual CN/EN) + 5-stage pipeline + platform red lines
├── signed_policy.py          ★ signed policy documents + version chain + revocation (keccak)
├── approval.py               ★ signed approval tokens (challenge → user signs → gateway verifies)
├── mandate.py                ★ task Mandates: single-use authorization, burned after use (pipeline layer 4)
├── templates.py              ★ policy template library (personal assistant / travel / dev API / procurement)
├── chain_anchor.py           ★ anchor backends: local simulation + real Base Sepolia (web3)
├── gateway.py                gateway core v3: 4-layer stacking + token verification + Mandate + revocation
├── rail_adapters.py          ★ rail adapter layer: evaluation core decoupled from settlement rails (x402 first)
├── mcp_server.py             ★ standard MCP server (11 tools, stdio)
├── boundra_cli.py            ★ boundra-init (policy wizard) + boundra-approve (challenge signer)
├── contracts/
│   └── PolicyAnchor.sol      ★ on-chain commitment contract (owner-write, anyone-read)
├── demo/
│   ├── simulate_agent.py     ★ end-to-end user journey simulation (MCP + hosted API dogfood)
│   ├── demo_policy.py        signed-policy demo (impersonation / unsigned / tampering attacks all blocked)
│   ├── demo_real.py          real-protocol end-to-end orchestration
│   ├── x402_resource_server.py  real x402 paywall server (FastAPI middleware)
│   ├── x402_buyer.py         real x402 buyer, evaluated by the MCP gateway before signing
│   ├── setup_wallets.py      Base Sepolia test wallet generation
│   └── demo.py / merchant.py / agent.py   offline simulation (zero dependencies)
├── tests/
│   ├── test_product.py       ★ product tests (22 assertions)
│   └── test_mcp_client.py    MCP protocol-level tests
├── docs/
│   ├── dataflow.png          data-flow diagram (English)
│   └── render_*.py           diagram renderers (architecture / flow / use-case / data flow)
└── state/audit.jsonl         audit trail (generated at runtime, gitignored)

署名付きポリシー：信頼の根幹はゲートウェイのデータベースではなく、ユーザーの鍵です（v2）

ポリシーはゲートウェイの設定にある行ではなく、ユーザーのウォレットで署名されたドキュメントです。

user private key signature ──→ PolicyDocument (NL rule + compiled artifact + prev_hash + version)
                      │  three checks: signer == owner, versions sequential, prev_hash unbroken
                      ▼
              PolicyStore (version chain) ──→ LocalAnchor (simulated commitment; production writes to contract)
                      │
                      ▼  check_integrity before every evaluation (signature + anchor)
              5-stage pipeline; audit records cite policy version + hash

• エージェントは読み取り専用：ユーザーの秘密鍵がなければ、set_policy は必ず失敗します。なりすまし、未署名、改ざんされた送信はすべてブロックされます（demo/demo_policy.py の7つのシナリオ）
• 2層のスコープ：ユーザーレベル（すべてのエージェントに適用するルール）× エージェントレベル（エージェントごとのルール）。最も厳しい判定が優先されます
• バージョンを更新するたびに署名が必要：v2ではv1のハッシュを参照する必要があります。過去のバージョンを改ざんすると、署名が無効になり、チェーンが破損します
• プライバシーの仕組み：オンチェーンに記録されるのはハッシュコミットメントのみです。ユーザーが開示を選択しない限り、ポリシーの平文がデバイスの外に出ることはありません

実行：.venv/bin/python demo/demo_policy.py

判定クレデンシャル：すべての決定に署名付きレシートが付属します（v4）

すべての evaluate_payment の応答には credential が含まれます。これはプラットフォーム鍵で署名された boundra.verdict/v1 レシート（EIP-191）です。「この支払い意図に対して、このポリシーのもとで、この ALLOW／DENY／ASK が実際に発生したことを、誰が証明できるのか？」に答えます。

• 支払い意図を紐付けます：intent_hash = 正規化された {amount, recipient, purpose} の sha256。クレデンシャルを別の支払いに付け替えることはできません
• ポリシーを紐付けます：policy_refs には使用したポリシーバージョンのハッシュが列挙され、オンチェーンアンカーと照合できます
• 監査ログを紐付けます：audit_id はサーバー側の監査エントリーにリンクします
• 誰でもオフラインで検証できます：proof を取り除き、ペイロードを正規化し（キーをソートし、区切り文字を詰め）、EIP-191の署名者を復元します。署名者は issuer およびプラットフォームアドレス 0xF30955B6Be768370Da13fca237A5f252F6081d1C と一致する必要があります（x402の収益を受け取るアドレスと同じで、署名と決済に同一のIDを使用します）。GET https://api.boundra.io/verdict-key で公開されています。

from verdict_credential import verify_credential
ok, why = verify_credential(verdict["credential"])   # offline, no API call

セルフホスト型ゲートウェイでは、BOUNDRA_VERDICT_KEY が設定されていない限りクレデンシャルは付与されません。署名なしモードは、引き続き完全な後方互換性を保ちます。

MCP サーバーのツール

ツール	目的	呼び出し元
evaluate_payment	支払い前の評価。ALLOWなら続行／DENYなら中止／ASKならユーザーが署名するチャレンジを返します。approval_token を付けて再試行します	エージェント
set_policy	特権操作：新しいポリシーバージョンを送信します。所有者のEIP-191署名が必要です	ユーザーのみ
revoke_policy	特権操作：ポリシーチェーンを取り消します（直ちにデフォルト拒否となり、以後ずっと無料です）	ユーザーのみ
get_policy_versions	ポリシーバージョンの履歴（チェーンとハッシュ。オンチェーンコミットメントと照合可能）	誰でも
get_policy	レガシーのフォールバックポリシーを表示します	誰でも
get_spend_report	今日の支出額／残りの予算	エージェント
get_audit_trail	承認監査記録	エージェント
request_policy_change	エージェントがユーザーにポリシー変更を依頼します（キューに追加され、自動適用されることはありません）	エージェント
list_templates / render_template	ポリシーテンプレート用のヘルパー	エージェント

Claude Desktopへの追加

1行で設定できます。uvxが依存関係を解決し、サーバーを起動します。

{
  "mcpServers": {
    "boundra": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/gobeyondfj-cmd/boundra", "boundra-mcp"]
    }
  }
}

初回実行時は、boundra-init ウィザード（同じパッケージ）を使って、ウォレットの作成／インポート → ポリシーテンプレートの選択 → 署名 → MCP経由で公開まで行います。所要時間は約2分です。エージェントがASKに遭遇したら、boundra-approve を実行し、チャレンジを貼り付けて署名付き承認トークンを生成します。

⚠️ 既知の信頼境界の簡略化（本番環境では修正が必要です）

1. エージェントが自己申告する human_approved 解決済み（v3）：人間による 承認は署名付き承認トークンになりました（approval.py）。ASK は 支払いインテントに正確に紐づいたチャレンジを返し、ユーザーのデバイスが署名します。 ゲートウェイは署名、フィールドごとのインテント照合、nonce の リプレイ防止を検証します。従来の自己申告方式も残っていますが、 approve(legacy-deprecated) とタグ付けされています。
2. MCP レベルでの傍受は助言にとどまります — エージェントのフレームワークは ゲートウェイを迂回してウォレットと直接通信できます。対策：x402 の ネイティブフックと併用します（demo/demo_real.py で実演。署名の前に、 SDK 内部でフックが実行されます）。最終目標：ポリシーの決定論的な部分を スマートコントラクトウォレットのモジュールにコンパイルし、決済レイヤーで強制します。
3. セマンティック検出は正規表現ベースです — 本番環境では、LLM による 評価とインテントのアンカリングに置き換える必要があります。
4. アンカリングはデフォルトでローカルログに記録されます — 実際のコントラクト （contracts/PolicyAnchor.sol）と web3 クライアント（chain_anchor.BaseSepoliaAnchor）は 用意されています。chain_config.json を設定すれば実際のチェーンに切り替えられます （テスト ETH を使って Remix からデプロイしてください）。

経済モデル：評価 API 自体が x402 の加盟店です

段階的な料金体系：

操作	料金
決定論的評価（/evaluate/basic）	無料
セマンティック評価（/evaluate/semantic）	エージェントあたり最初の 100 回は無料。その後は 1 回につき $0.003 USDC（実際の x402 課金）
ポリシーのアンカリング／取り消し	無料（取り消しは永久に無料です — 安全上、譲れない一線です）

オープンコア：このリポジトリのクライアント、評価エンジン、デモは Apache-2.0 です。ホスト型評価サービス（段階的料金体系、無料枠の 管理、収益台帳）は、非公開の boundra-ops リポジトリから実行されます。

検証済み／未検証

検証済み（test_product.py の 22 件すべてのアサーションと test_mcp_client.py が成功）： 4 層のポリシー適用（プラットフォームのレッドライン × ユーザー × エージェント × Mandate）では 最も厳しいルールを適用。署名付き承認トークン（有効なトークンは通過、偽造は拒否、 インテントの再バインドは拒否、リプレイは拒否）。Mandate は単回使用。取り消し時の デフォルト動作は拒否で、署名付き v2 で復元可能。テンプレートのレンダリングとコンパイル。 すべての MCP ツールを通信経由で検証。実際の x402 の 402 ラウンドトリップにおいて、SDK が署名する前にゲートウェイがインジェクション攻撃をブロック。 段階的料金体系の全サイクル — まず Base Sepolia で実証（2026-10-16）、続いて Base メインネット（2026-10-21）：無料枠は通過し、有料枠では実際に $0.003 USDC を決済（購入者の残高は 1.010 → 1.007、プラットフォームのアドレスに 0.003 を入金）。 dogfood フックが自己評価し、セマンティックレイヤーがインジェクションをブロックし、 /revenue 台帳に記録。 メインネットの決済トランザクションは公開検証できます：0xf04d3497…4eac7e5 — 現在、ライブ API は Coinbase の CDP ファシリテーターを通じて Base メインネットで決済します。 以前のテストネットでの実証：0x5ad8ef4b…c474bbe （ホスト型サービスのコードは設計上非公開です — チェーンが領収記録となります）。

未検証：実際のオンチェーン・アンカリング（コントラクトは用意済みですが、デプロイにはテスト ETH が必要です）。 実際のユーザー需要。実際の LLM 挙動の分布におけるセマンティックレイヤーの誤検知率。