DzikPasnik/x402Guard
GitHub: DzikPasnik/x402Guard
为自主 AI 代理在 DeFi 场景中提供非托管安全代理，通过支出限额、合约白名单和审计日志防止失控代理造成资金损失。
Stars: 0 | Forks: 0
# x402Guard
### 自主 AI 代理在接触真实资金之前所需的安全层。
[](https://github.com/DzikPasnik/x402Guard/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://x402guard-production.up.railway.app/api/v1/health)
[](https://github.com/DzikPasnik/x402Guard/actions)
[](SECURITY.md)
[](proxy/)
[](solana/)
[](dashboard/)
[实时仪表盘](https://x402-guard-flame.vercel.app) ·
[代理演示](https://x402-guard-flame.vercel.app/agent) ·
[安全策略](SECURITY.md) ·
[贡献指南](CONTRIBUTING.md)
## 为什么选择 x402Guard？
AI 代理正在拥有自己的钱包。Coinbase 的 [x402 protocol](https://www.x402.org/) 允许代理使用真实的加密货币支付 Web 服务。但在没有保障措施的情况下，自主代理可能会：
- **掏空钱包** —— 没有单笔交易或每日支出上限
- **与恶意合约交互** —— 没有白名单强制执行
- **在循环中过度消费** —— 没有针对失控代理的熔断机制
- **不留痕迹** —— 没有用于合规的审计追踪
**x402Guard** 是一个位于您的代理和 Web3 服务之间的非托管代理。它拦截 x402 支付流程并执行可配置的规则 —— 无需触碰私钥。
```
┌─────────┐ ┌──────────────────────────────────┐ ┌─────────────────┐
│ AI Agent │────▶│ x402Guard Proxy │────▶│ Target Service │
│ │◀────│ (Rust/Axum :3402) │◀────│ (402 paywall) │
└─────────┘ └──────────┬───────────┬────────────┘ └─────────────────┘
│ │
┌──────▼──┐ ┌─────▼──────┐
│ Redis │ │ Postgres │
│ rate lim │ │ keys, audit │
│ nonces │ │ guardrails │
└─────────┘ └─────────────┘
```
## 主要功能
| 功能 | 描述 |
|---------|-------------|
| **支出限额** | `MaxSpendPerTx` 和 `MaxSpendPerDay` —— 限制单笔和每日支付 |
| **合约白名单** | `AllowedContracts` —— 只有经批准的地址才能接收资金 |
| **会话密钥** | Base 链上基于 EIP-7702 的有时限、限定范围的支付密钥 |
| **Solana Guard** | 具有单笔交易限额和程序白名单的 PDA 保险库 |
| **重放攻击防护** | 基于 Redis 的 nonce 跟踪，防止双重支付攻击 |
| **速率限制** | 基于 IP 和全局的滑动窗口速率限制 |
| **审计日志** | 每一项操作的不可变、仅追加日志（无 UPDATE/DELETE） |
| **x402 验证** | 针对 x402 `exact` 方案的 EIP-3009 `TransferWithAuthorization` |
## 立即体验
| | |
|---|---|
| **[代理演示](https://x402-guard-flame.vercel.app/agent)** | 与实时使用 x402Guard 工具的 AI 代理聊天 —— 检查防护措施、模拟支付、查询审计日志 |
| **[仪表盘](https://x402-guard-flame.vercel.app)** | 监控代理、配置防护规则、查看支出分析 |
| **Proxy API** | 生产环境位于 `x402guard-production.up.railway.app` —— [检查健康状态](https://x402guard-production.up.railway.app/api/v1/health) (返回 JSON) |
## 快速开始
**选项 A：试用在线部署（无需设置）**
所有服务已在测试网上运行 —— 只需访问 [代理演示](https://x402-guard-flame.vercel.app/agent) 或 [仪表盘](https://x402-guard-flame.vercel.app)。
**选项 B：使用 Docker 在本地运行**
```
git clone https://github.com/DzikPasnik/x402Guard.git
cd x402Guard
# 启动 proxy + Postgres (含 schema + seed data) + Redis
docker compose up
# 验证 proxy 正在运行
curl http://localhost:3402/api/v1/health
# → {"status":"ok","version":"0.1.0","service":"x402guard-proxy","redis":"connected"}
# 用于本地开发的 Management API key：dev-api-key-change-me
curl -H "X-Api-Key: dev-api-key-change-me" http://localhost:3402/api/v1/agents
# → 返回 seeded demo-agent
# Dashboard (可选，需单独终端)
cd dashboard && npm install && npm run dev
# → http://localhost:3000
```
## 技术栈
| 组件 | 技术 | 测试 |
|-----------|-----------|-------|
| **Proxy** | Rust, Axum, SQLx, alloy-rs | 106 项测试 |
| **Solana Guard** | Anchor, SPL Token | 13 项测试 |
| **Dashboard** | Next.js 16, TypeScript, Tailwind, shadcn/ui | E2E |
| **Database** | PostgreSQL (Supabase) + Redis (Upstash) | — |
| **CI** | GitHub Actions (Rust, Node, Solana, secrets scan) | — |
## 集成
适用于流行 AI 代理框架的即用型插件：
| 框架 | 类型 | 代码 |
|-----------|------|------|
| **Direct SDK** | TypeScript 客户端 | [`examples/core`](examples/core/) |
| **ElizaOS** | 代理插件 | [`examples/elizaos`](examples/elizaos/) |
| **Virtuals Protocol** | GAME SDK 插件 | [`examples/virtuals`](examples/virtuals/) |
| **Cod3x** | DeFi 适配器 | [`examples/cod3x`](examples/cod3x/) |
## 开发
```
# Rust proxy
cargo check --workspace # Compile check
cargo test --workspace # Run all tests
cargo clippy --workspace --all-targets -- -D warnings # Lint
# Dashboard
cd dashboard && npm run build # Production build
cd dashboard && npm run dev # Dev server
```
环境变量
请参阅 [`.env.example`](.env.example) 获取完整列表。 | 变量 | 描述 | 默认值 | |----------|-------------|---------| | `PROXY_PORT` | 代理监听端口 | `3402` | | `DATABASE_URL` | Postgres 连接字符串 | `postgresql://...` | | `UPSTASH_REDIS_URL` | Redis 连接 URL | `redis://localhost:6379` | | `RATE_LIMIT_RPS` | 速率限制 (请求/秒) | `1000` | | `BASE_SEPOLIA_RPC_URL` | Base Sepolia RPC | `https://sepolia.base.org` |标签：AI 代理, Base 区块链, DeFi 安全, EIP-7702, Rust, Solana, Web3 安全, x402 协议, 交易限额, 会话密钥, 加密货币防护, 可视化界面, 审计日志, 搜索引擎查询, 支付代理, 智能合约白名单, 测试用例, 熔断机制, 网络流量审计, 自主代理, 自动化攻击, 请求拦截, 配置审计, 链上合规, 防御引擎, 非托管钱包