x402 Agent Demo

基于 x402 协议与 MCP 架构的自主经济 AI Agent 设计与实现

Design and Implementation of an Autonomous Economic AI Agent Based on x402 Protocol and MCP Architecture

项目简介

本项目是一个创新的 AI Agent 演示，展示了如何让 AI 自主地发现付费服务、评估价格、执行加密货币支付并获取内容。项目融合了三个前沿技术：

• x402 协议 - 基于 HTTP 402 状态码的 Web3 支付标准
• MCP (Model Context Protocol) - Anthropic 推出的 AI 工具调用协议
• AI Agent - 具备自主经济行为能力的智能体

项目意义

随着大语言模型（LLM）从单纯的信息处理向自主智能体（Agent）演进，如何赋予 Agent 独立的经济行为能力成为构建"机器经济体"的关键挑战。目前的 AI Agent 大多受限于传统的 API Key 付费模式，缺乏自主发现服务、评估价格并完成支付的能力。

本项目旨在探索 Web3 支付在 AI 领域的应用落地，解决 Agent 跨平台、无许可支付的难题，为未来去中心化 AI 协作网络的构建提供实践参考。

系统架构

采用 三层架构 设计：

┌─────────────────────────────────────────┐
│   AI Agent Client (Claude API)          │
│   - 任务理解与意图识别                    │
│   - 支付决策                             │
│   - 用户交互                             │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│   MCP Tools Layer                       │
│   ├─ http_request      (HTTP 请求/402检测)│
│   ├─ web3_payment      (Web3 支付执行)    │
│   ├─ get_wallet_balance (钱包余额查询)    │
│   └─ check_payment_policy (策略检查)      │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│   Mock x402 Service (Flask)             │
│   ├─ Premium Article API   (0.5 USDC)   │
│   ├─ Image Generation API  (0.8 USDC)   │
│   └─ Video Generation API  (5.0 USDC)   │
└─────────────────────────────────────────┘

各层职责

1. Agent 客户端层：部署 AI 模型，负责理解用户意图、调用工具、做出支付决策
2. MCP 工具层：封装 HTTP 请求和 Web3 钱包功能，实现 x402 协议解析
3. 资源服务层：模拟支持 x402 协议的付费 API，用于验证 Agent 支付能力

核心功能

• 自动检测 HTTP 402 付费墙
• 解析 x402 支付需求（金额、地址、挑战数据）
• 基于策略自主决策是否支付
• 执行 Web3 加密货币交易（模拟）
• 获取付费内容并呈现给用户

支付策略

• 免密支付额度：低于阈值（默认 1.0 USDC）自动批准
• 超额确认：超过阈值需要用户手动确认
• 余额检查：支付前检查钱包余额

功能流程

用户下达指令
     ↓
Agent 访问资源 → 返回 HTTP 402 (Payment Required)
     ↓
解析 x402 Headers (价格、收款地址、挑战数据)
     ↓
检查支付策略 (金额是否在免密范围内?)
     ↓
┌─────────────┬─────────────────────┐
│ 免密范围内   │ 超过免密额度          │
│ 自动批准支付 │ 请求用户确认          │
└─────────────┴─────────────────────┘
     ↓
执行 Web3 支付，获取交易凭证
     ↓
携带支付凭证重新请求资源
     ↓
服务验证凭证，返回内容

用户交互示例

场景一：自动支付（预算内）

👤 用户: 帮我查看这篇关于"量子计算最新进展"的付费研报

🤖 Agent: 正在访问该链接...
   检测到付费内容，价格 0.5 USDC (低于免密额度 1.0)
   已自动完成支付 (TxHash: 0x123...)

   以下是研报的核心内容：...

场景二：需要用户确认（超额）

👤 用户: 生成一段 4K 风景视频

🤖 Agent: 已连接视频生成 API，服务商报价 5.0 USDC
   超过免密支付额度，需要您的确认

💰 PAYMENT APPROVAL REQUIRED
   Amount: 5.0 USDC
   Description: AI-Generated 10s 4K Video

   Approve payment? (yes/no): yes

✅ Payment executed
🤖 Agent: 视频生成完成！

项目结构

crypto_agent/
├── x402-agent-demo/             # Demo 实现
│   ├── agent-client/            # AI Agent 客户端
│   │   └── agent.py             # Claude Agent 实现
│   ├── mcp-server/              # MCP Server
│   │   └── server.py            # MCP 工具定义
│   ├── mock-service/            # Mock x402 服务
│   │   └── app.py               # Flask API
│   ├── setup.py                 # 环境配置脚本
│   ├── run_mock_service.py      # 启动 Mock 服务
│   ├── run_agent.py             # 启动 Agent
│   └── README.md                # Demo 详细文档
├── CLAUDE.md                    # 项目开发指引
└── README.md                    # 本文档

快速开始

# 进入 demo 目录
cd x402-agent-demo

# 安装依赖
uv sync

# 配置环境（生成测试钱包和 .env）
python setup.py

# 终端 1 - 启动 Mock x402 服务
python run_mock_service.py

# 终端 2 - 启动 AI Agent
python run_agent.py

详细说明请参考 x402-agent-demo/README.md

技术栈

安全说明

• 本项目仅用于演示和研究
• 所有支付交易都是模拟的，不会产生真实链上交易
• 不要在测试钱包中存入真实资金
• 不要将私钥提交到代码仓库

后续扩展方向

• 集成本地 LLM (Ollama + Llama 3 / Qwen)
• 真实区块链交易（Sepolia/Base 测试网）
• EIP-712 签名实现
• 服务商白名单和黑名单
• 会话级预算管理
• 交易历史记录和审计
• Web UI 界面
• 多币种支持（ETH, USDT, USDC）

相关资源

x402 协议

• Coinbase x402 文档
• Cloudflare x402 博客
• OKX x402 指南

AI Agent 支付

• Google AP2 协议
• MCP 协议规范

Agent 开发

• Advent of Agents
• Claude Code Agent Skills

Web3 基础设施

• Questflow x402 Facilitator
• Kite AI Payment Chain