Agent Commerce Gateway

アルファ版。 v0.1.0-alpha は実験的です。独立したレビューなしに本番の資金で使用しないでください。SECURITY.md を参照してください。

10秒でわかる概要

あなたはすでにHTTP APIを持っています。AIエージェントはそれを発見し、呼び出し、支払いをしたいと考えています——あなたが書いたわけでも、維持したいわけでもないプロトコルを通じて。

Agent Commerce Gatewayは、あなたのインフラ内で、既存のAPIの前に立ち、それを代行します。YAMLファイルでエンドポイントを記述すると、エージェントはMCPツールとx402ペイウォールを取得できます。資金は直接あなたのウォレットに送られます——ゲートウェイは資金を保持せず、あなたの鍵も保持しません。

Your existing API → Agent Commerce Gateway → AI Agent
                        MCP · x402 · receipts · doctor

Related MCP server: opendexter

デモ

[agent] Discovering resources over MCP...
[agent] Found: market_report — Premium Market Report (0.01 USDC)
[agent] Requesting resource...

[gateway] Payment required: 0.01 USDC → 0x7099…79C8
[buyer] Signing x402 authorisation...
[gateway] Payment verified
[gateway] Payment settled tx 0x4f2c…9ab1
[gateway] Calling merchant backend...
[gateway] Resource delivered

[receipt] payment: settled
[receipt] amount: 0.01 USDC
[receipt] merchant: 0x7099…79C8
[receipt] buyer balance 100.00 → 99.99 mUSDC
[receipt] merchant balance 0.00 → 0.01 mUSDC

http://localhost:5173 のダッシュボードには、同じリクエストが発生したときに表示されます。ストリーミングではなく、短い間隔で認証済みイベントルートをポーリングします。ブラウザの EventSource は管理者トークンを送信できず、オペレータールートはトークンなしでは閉じられているため、SSEエンドポイントはヘッダー対応クライアントからは到達可能ですが、ブラウザからは決して到達できません。ポーリングは劣化モードではなく、ダッシュボードの意図された経路です。

インストール

npx @devlab.group/agent-commerce --help # no install needed
npm install -g @devlab.group/agent-commerce # or install the `agent-commerce` binary
agent-commerce doctor

Node >= 22 が必要です。1つのパッケージに2つのものが含まれています: agent-commerce CLI（init、validate、doctor、demo）と、ゲートウェイを独自のプロセスに組み込むためのライブラリです。デフォルトのインストールは約49 MBで、ブロックチェーンやウォレットの依存関係は一切含まれません。

import { createGateway, loadConfig, receipts } from '@devlab.group/agent-commerce';

const config = await loadConfig({ path: 'config.yaml' });
const gateway = await createGateway({
  config,
  store: receipts({ path: './receipts.sqlite' }),
  paymentProviders: [],
  protocolAdapters: [],
});
const { url } = await gateway.listen;

オプションのピア——使用するレールだけをインストール

MCPアダプタとx402プロバイダは、それぞれパッケージの他の部分にはない依存関係を必要とするため、独自のサブパスに配置されています。x402だけでブラウザウォレットスタック（wagmi、WalletConnect、Reown）が約572 MB引き込まれますが、無料のHTTPリソースを提供するゲートウェイがそれをインストールする理由はありません。

npm install @devlab.group/agent-commerce @modelcontextprotocol/sdk x402 viem

import { mcp } from '@devlab.group/agent-commerce/mcp';
import { x402 } from '@devlab.group/agent-commerce/x402';

ピアは正確に固定されています: x402のスキーマとEIP-712ドメインはこの境界を越えるため、バージョンのずれは利便性の問題ではなく正確性の問題です。ピアがインストールされていないサブパスをインポートすると、Nodeは欠落しているパッケージを指定してロード時に失敗します——何も提供しないゲートウェイを静かに起動するのではなく、意図的にそうなります。

クイックスタート

要件: Node >= 22、npm 10、Docker。それ以外は不要です——APIキーも、実際の資金も、手動のブロックチェーン設定もありません。

git clone <repo> && cd agent-commerce
npm install
docker compose up

次に、2番目のターミナルで:

npm run agent-commerce -- doctor --config config-demo.yaml # verify the whole stack
npm run demo:agent # watch an agent buy something

Linuxのみ、かつユーザーがUID/GID 1000でない場合のみ（id -u && id -g で確認）: docker compose up の前に DOCKER_UID=$(id -u) DOCKER_GID=$(id -g) をエクスポートしてください。チェーン展開ステップはそのユーザーとして実行され、書き込まれる展開マニフェストがroot所有ではなくホスト側で書き込み可能なままになります。macOSとWindowsのDocker DesktopはVMを通じて権限を変換するため、これは不要です。

これで全部です。スタックはプライベートなAnvilチェーン、モックUSDCトークン、デモのマーチャントAPI、ゲートウェイ、ダッシュボードで構成され、すべてローカルで使い捨て可能です。

停止して状態を消去するには: docker compose down -v。

仕組み

        ┌──────────────────────────────────────────────────────┐
        │ AI Agent │
        └──────────────┬───────────────────────────────────────┘
                       │ MCP · HTTP + X-PAYMENT
        ┌──────────────▼───────────────────────────────────────┐
        │ Agent Commerce Gateway (yours) │
        │ │
        │ protocol adapters → ExecutionPipeline → … │
        │ │ │
        │ ┌─────────────────────┼──────────────┐ │
        │ ▼ ▼ ▼ │
        │ PaymentProvider BackendExecutor ReceiptStore │
        │ (x402) (bounded HTTP) (SQLite) │
        └────────┬─────────────────────┬───────────────────────┘
                 │ │
        buyer → merchant ┌──────▼───────────────┐
        (never through us) │ Your backend API │
                                └───────────────────────┘

すべてのプロトコルアダプタは1つの実行パイプラインに収束します。それが、支払いの強制を各アダプタが覚えておくべきものではなく、システムの特性にする理由です。詳細は docs/architecture.md にあります。

リソースの設定

resources:
  market_report:
    name: Premium Market Report
    backend:
      type: http
      method: GET
      url: ${MERCHANT_API_BASE_URL}/api/report
      timeoutMs: 10000
    pricing:
      type: fixed
      amount: "0.01"
      currency: USDC
    expose: [http, mcp]
    payments: [x402]

これが統合です。バックエンドにSDKは不要で、書き直しもありません。

npm run agent-commerce -- init # generate a config interactively
npm run agent-commerce -- validate # fails loudly, exits non-zero

docs/configuration.md を参照してください。

プロトコルサポート

「計画中」はコードが提供されないことを意味します。各アダプタは実行時に GET /.well-known/agent-commerce と agent-commerce doctor を通じて、独自の supportedSpec、capabilities、unsupported リストを報告します——つまり、この主張はマーケティングではなく検証可能です。詳細: docs/protocols.md。

支払いモデル

• 非カストディアル。 ゲートウェイは資金を保持せず、マーチャントやバイヤーの秘密鍵を要求することもありません。payTo はあなたのアドレスです。

• フェイルクローズ。 欠落、不正な形式、期限切れ、リプレイ、誤った金額、誤った受取人、誤ったネットワーク、誤ったアセットの支払いはすべて失敗します——それぞれにテストがあります。

• 二重のリプレイ耐性。 EIP-3009はオンチェーンでの二重使用を防ぎます。さらにゲートウェイは、決済前に認証から導出された replayKey を予約します。

• CIでの実際の決済。 エンドツーエンドテストは、バイヤーの残高が減少し、マーチャントの残高が正確に価格分増加することを、レシート内の実際のトランザクションハッシュとともに検証します。「支払い成功」というログ行だけではカウントされません。

詳細: docs/payment-flow.md。

診断

$ npm run agent-commerce -- doctor --config config-demo.yaml

PASS Config valid — 2 resource(s), merchant "Demo Data Store"
PASS Gateway healthy and ready at http://127.0.0.1:8080
PASS Backend 2/2 backend host(s) reachable
PASS Protocols http=on mcp=on (/mcp)
PASS Payments x402 enabled — network=base-sepolia, destination=0x7099…79C8, facilitator=local
INFO Payments (MPP) planned — not implemented in v0.1
PASS Storage sqlite schema v1 writable; receipts=2
PASS Protocol versions reported by gateway /.well-known/agent-commerce

Score: 7/7 checks passed

これはイラストではなく実際の出力です。doctor はまた、ゲートウェイのライブ決済設定がローカル設定の解決結果と一致するかを相互検証し、不一致があれば失敗します——システムが誤設定されているのに診断が成功するのは、診断がないのと同じくらい悪いことです。

何か失敗すれば非ゼロで終了します。機械用には --json。

公開範囲とアクセス

デモはすべてを 127.0.0.1 にバインドします。ゲートウェイを他の誰かが到達可能な場所に置く前に、この分割を理解してください:

• エージェントルート（/api/resources/:id/invoke、/mcp）は設計上認証なしです——有料リソースはパスワードではなく支払いによって保護されます。

• オペレータールート（/api/receipts、/api/events、/api/events/stream）はマーチャントのコマース台帳です: 支払人アドレス、金額、決済ハッシュ。これらは server.adminToken を必要とし、設定されていない場合は 404 を返します。

• ブラウザは server.allowedOrigins によって管理されます。これは明示的な許可リストで、デフォルトは空です。

• レート制限はありません。 無料リソースは、呼び出し側が選択する任意のレートでバックエンドへの認証なしプロキシです。クォータと不正使用対策は、APIまたはエッジに属します。

SECURITY.md は、これが保護するものと保護しないものを明確に述べています。

ライブ決済——このリリースには含まれません

v0.1.0-alpha はローカルの決定論的チェーン（Anvil + MockUSDC）に対してのみ決済します。 ライブモードも、それを有効にするフラグも、それに向けた部分的な経路もありません: facilitator.mode: "remote" は設定読み込み時に拒否され、x402プロバイダのヘルスチェックはAnvil専用のRPCメソッドを必要とするため、/ready は実際のネットワークに対して503を返します。実際の価値の決済は計画中であり、提供されていません——docs/payment-flow.md を参照してください。

開発

npm run verify # contract + lint + typecheck + test
npm run test:e2e # deterministic end-to-end, boots its own chain

チェーン作業にはFoundry（anvil、forge、cast）が必要です。CONTRIBUTING.md を参照してください。

ロードマップ

現在（v0.1.0-alpha） — MCP、x402、レシート、doctor、決定論的デモ。

次回 — OpenAPIインポート · より強力な適合性スイート · doctor GitHub Action · UCP · MPP · ACP · A2A · AP2 · ShopifyおよびWooCommerceの例 · PostgreSQL · より豊かな可観測性。

新しいプロトコルは、アダプタモデルが実際の使用に耐えた後にのみ導入されます。スコープの規律はムードではなく、リリースの要件です。

ドキュメント

ライセンス

Apache-2.0。