x402 Facilitator Proxy

X402 Facilitator Proxy - 多租户支付网关

基于 Base L2 的去中心化自主支付基础设施，用于 API 变现，支持程序化费用路由和兼容 Agent 的结算协议。

🏗️ 架构概览

X402 Facilitator Proxy 实现了一个完整的多租户支付网关，使商家能够通过 HTTP 402“需要付款”响应实现 API 变现，同时自主 Agent 可使用 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. 模型上下文协议（MCP）服务

MCP 服务（x402-client-sdk/src/mcp-server.ts）为 AI Agent 提供标准化接口，以便与支付系统交互：

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

协议功能：

• 标准输入/输出通信接口
• 兼容 Agent 的支付工具注册
• 自动处理和验证交易
• 兼容跨平台 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. 自主 Agent 模板

TypeScript/LangChain Agent（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 Agent（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. 设置 Agent 模板

# 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-...

Agent 运行时安全

• TypeScript Agent：使用 process.env.AGENT_PRIVATE_KEY
• Python Agent：使用 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% 路由至平台金库
• Gas 优化：批量转账以提高成本效率

📖 集成模式

HTTP 402 支付流程

1. API 请求：客户端尝试访问受保护的端点
2. 支付挑战：服务器返回 HTTP 402 和支付说明
3. Agent 处理：自主 Agent 检测到 402，并执行 USDC 付款拆分
4. 验证：代理网关验证链上交易
5. 授予访问权限：附带支付请求头的原始 API 请求成功

Agent 集成工作流

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 Agent 设置
• API 参考：核心网关端点和响应

🤝 贡献

1. Fork 此仓库
2. 为新的集成创建功能分支
3. 在部署到主网之前，先在 Base L2 测试网上测试
4. 提交包含全面测试覆盖的 pull request

📄 许可证

本项目采用 MIT 许可证，支持开源创新，同时通过程序化费用路由维持平台的可持续发展。

---

为自主经济而构建。由 Base L2 提供支持。通过多租户验证保障安全。