x402 Facilitator Proxy

X402 Facilitator Proxy - マルチテナント決済ゲートウェイ

Base L2 上で API を収益化するための、プログラムによる手数料振り分けとエージェント対応の決済プロトコルを備えた、分散型かつ自律型の決済インフラストラクチャです。

🏗️ アーキテクチャ概要

X402 Facilitator Proxy は、HTTP 402「Payment Required」レスポンスを通じてマーチャントが API を収益化できるようにする、完全なマルチテナント決済ゲートウェイを実装しています。また、自律型エージェントは Base L2 上で USDC を使用して、シームレスに取引を決済できます。

x402-facilitator-proxy/
├── src/                                    # Core Cloudflare Worker Engine
│   ├── index.ts                           # Main proxy gateway endpoint
│   └── backend/automation/
│       └── sweeper.ts                     # Automated fee collection
├── x402-client-sdk/                       # Core Interface Rails
│   ├── src/
│   │   ├── client-library.ts             # TypeScript SDK
│   │   └── mcp-server.ts                 # Model Context Protocol Server
│   ├── package.json                      # SDK dependencies
│   └── tsconfig.json                     # TypeScript configuration
└── templates/                             # Integration Templates
    ├── express-middleware/
    │   └── x402-guard.js                 # Merchant-Side API Gating
    ├── langchain-ts/
    │   ├── agent.ts                      # TypeScript Agent Template
    │   ├── package.json                  # LangChain dependencies
    │   └── README.md                     # Setup instructions
    └── crewai-python/
        └── agent.py                      # Python Agent Template

🚀 コアコンポーネント

1. Cloudflare Worker プロキシエンジン

コアバックエンド（src/index.ts）は、Cloudflare のエッジネットワークにデプロイされたサーバーレス決済検証ゲートウェイとして動作します。

• エンドポイント：https://x402-facilitator-proxy.seob5285.workers.dev/api/v1/verify-and-settle
• プラットフォーム保管庫：0x2E3DADfb314718849A93c49A78618E586c3b2C60
• 手数料体系：プラットフォーム手数料 1% の自動振り分け

主な機能：

• マルチテナントの取引検証
• Base L2 の USDC 決済検証
• 手数料の自動分配（99% をマーチャントに、1% をプラットフォームに）
• グローバルな低レイテンシアクセスを実現するエッジへのデプロイ

2. Model Context Protocol（MCP）サーバー

MCP サーバー（x402-client-sdk/src/mcp-server.ts）は、AI エージェントが決済システムを利用するための標準化されたインターフェースを提供します。

# Start the MCP server locally via stdio
npm run mcp:start

プロトコルの機能：

• 標準入出力の通信インターフェース
• エージェント対応の決済ツール登録
• 取引の自動処理と検証
• クロスプラットフォームの AI フレームワークとの互換性

3. マーチャント側の API ゲート制御

Express ミドルウェア（templates/express-middleware/x402-guard.js）を使用すると、マーチャントは HTTP 402 チャレンジによって API を保護できます。

import { x402TollboothGuard } from './templates/express-middleware/x402-guard.js';

app.use('/api/premium', x402TollboothGuard("0.10", "0xYourWalletAddress"));

ミドルウェアの動作：

1. チャレンジ：ヘッダーがない場合、決済手順とともに HTTP 402 を返します
2. 検証：プロキシゲートウェイを通じて決済を検証します
3. アクセス：決済の検証に成功すると、API へのアクセスを許可します

4. 自律型エージェントのテンプレート

TypeScript/LangChain エージェント（templates/langchain-ts/agent.ts）

import { createPaymentAgent } from './templates/langchain-ts/agent.js';

const agent = await createPaymentAgent();
const result = await agent.invoke({
  input: JSON.stringify({
    agentPrivateKey: process.env.AGENT_PRIVATE_KEY,
    developerWallet: "0x742d35Cc6297C24aE0E4838C4667C02693C4cB36",
    amountUSD: "0.10"
  })
});

Python/CrewAI エージェント（templates/crewai-python/agent.py）

from templates.crewai_python.agent import X402PaymentAgent

agent = X402PaymentAgent()
result = agent.process_payment({
    "agent_private_key": os.getenv("AGENT_PRIVATE_KEY"),
    "developer_wallet": "0x742d35Cc6297C24aE0E4838C4667C02693C4cB36",
    "amount_usd": "0.10"
})

🔧 クイックスタート

1. プロキシエンジンのデプロイ

npm install
npm run deploy

2. MCP サーバーのセットアップ

cd x402-client-sdk
npm install
npm run mcp:start

3. マーチャントミドルウェアの統合

# Copy the Express middleware to your project
cp templates/express-middleware/x402-guard.js your-project/middleware/

# Install in your Express app
import { x402TollboothGuard } from './middleware/x402-guard.js';
app.use('/api/protected', x402TollboothGuard("0.05", "0xYourWallet"));

4. エージェントテンプレートのセットアップ

# For TypeScript/LangChain agents
cd templates/langchain-ts
npm install
npm run dev

# For Python/CrewAI agents
cd templates/crewai-python
pip install -r requirements.txt
python agent.py

🔐 セキュリティと環境変数

重要なセキュリティガイドライン

⚠️ 秘密鍵をリポジトリ内のファイルにハードコードしないでください

機密性の高い認証情報はすべて、安全な環境変数で管理する必要があります。

Cloudflare Worker 環境（本番環境）

# Set via Cloudflare Workers dashboard or wrangler
wrangler secret put FACILITATOR_PRIVATE_KEY
wrangler secret put PLATFORM_VAULT_ADDRESS

ローカル開発環境

ローカルテスト用に .env ファイルを作成します。

# .env (root directory - for Cloudflare Worker development)
FACILITATOR_PRIVATE_KEY=0x1234567890abcdef...
PLATFORM_VAULT_ADDRESS=0x2E3DADfb314718849A93c49A78618E586c3b2C60

# Agent execution environments
AGENT_PRIVATE_KEY=0xabcdef1234567890...
OPENAI_API_KEY=sk-...

エージェントの実行時セキュリティ

• TypeScript エージェント：process.env.AGENT_PRIVATE_KEY を使用します
• Python エージェント：os.getenv("AGENT_PRIVATE_KEY") を使用します
• MCP サーバー：実行時にシステム環境からキーを読み込みます

🌐 プラットフォームリファレンス

コアインフラストラクチャ

• 検証ゲートウェイ：https://x402-facilitator-proxy.seob5285.workers.dev/api/v1/verify-and-settle
• プラットフォーム保管庫：0x2E3DADfb314718849A93c49A78618E586c3b2C60
• ネットワーク：Base L2（チェーン ID：8453）
• 決済トークン：USDC（0x833589fCD6eDb6E08f4c7C32d4f71b54bda02913）

手数料体系

• マーチャントの収益：決済額の 99%
• プラットフォーム手数料：1% をプラットフォーム保管庫に自動振り分け
• ガスの最適化：コスト効率を高めるバッチ送金

📖 統合パターン

HTTP 402 決済フロー

1. API リクエスト：クライアントが保護されたエンドポイントへのアクセスを試みます
2. 決済チャレンジ：サーバーが決済手順とともに HTTP 402 を返します
3. エージェントの処理：自律型エージェントが 402 を検知し、USDC 決済の分配を実行します
4. 検証：プロキシゲートウェイがオンチェーン取引を検証します
5. アクセス許可：決済ヘッダーを付けて元の API リクエストが成功します

エージェント統合ワークフロー

graph TD
    A[Agent API Call] --> B{HTTP 402?}
    B -->|Yes| C[Parse Payment Requirements]
    C --> D[Execute USDC Split Transfer]
    D --> E[Submit to Proxy Gateway]
    E --> F[Retry Original Request]
    F --> G[Access Granted]
    B -->|No| G

🛠️ 開発コマンド

# Core proxy development
npm run dev              # Start local development server
npm run deploy           # Deploy to Cloudflare Workers
npm run cf-typegen       # Generate Cloudflare types

# SDK development
cd x402-client-sdk
npm run build           # Build TypeScript SDK
npm run mcp:start       # Start MCP server

# Template testing
cd templates/langchain-ts
npm run dev            # Test TypeScript agent

cd templates/crewai-python
python agent.py        # Test Python agent

# Automated fee collection
npm run sweep          # Execute fee sweeping automation

📚 ドキュメント

• クライアント統合ガイド：詳細な統合手順
• LangChain テンプレート README：TypeScript エージェントのセットアップ
• API リファレンス：コアゲートウェイのエンドポイントとレスポンス

🤝 コントリビューション

1. リポジトリをフォークします
2. 新しい統合用のフィーチャーブランチを作成します
3. メインネットにデプロイする前に、Base L2 テストネットでテストします
4. 包括的なテストカバレッジを備えたプルリクエストを送信します

📄 ライセンス

このプロジェクトは MIT ライセンスのもとで提供されています。プログラムによる手数料の振り分けを通じてプラットフォームの持続可能性を維持しながら、オープンソースのイノベーションを可能にします。

---

自律型経済のために構築。Base L2 が支えています。マルチテナント検証によって保護されています。