使用说明
完成用于API货币化的x402（索拉纳）支付协议实现
https://github.com/user-attachments/assets/7973183b-c5b5-4ed4-9955-e72599414630
专为Solana X402黑客马拉松而建 🏆
📋 目录
🎯 概述
MicroAPI中心 是完整的端到端实现 x402支付协议 对于Solana，使API提供商能够通过区块链支付将其端点货币化。该项目演示了如何构建一个与Solana区块链无缝集成的生产就绪支付系统。
什么是x402？
x402是一个开放的支付标准，使客户能够使用区块链支付来支付外部资源（API、内容、数据）。它遵循HTTP状态码402（需要支付）语义，并提供了一种标准化的方法来实现按使用付费的API，包括链上结算和可验证的收据。
主要亮点
- ✅ 完全遵守协议：完成x402规范的实施
- ✅ Solana集成：原生SOL和SPL代币支持
- ✅ 生产准备就绪：错误处理、验证、日志记录、测试
- ✅ 开发者友好：全面的文档、代码示例、易于集成
- ✅ 链上注册：去中心化API发现
- ✅ 多语言支持：TypeScript、Python、Go示例
✨ 特性
🔐 支付处理
- 付款验证：加密安全签名验证
- 链上结算：自动区块链交易处理
- 多令牌支持：本地SOL和SPL代币（USDC等）
- Nonce重播保护：防止双重支出攻击
- 时间窗口验证：确保付款新鲜度
🌐 web界面
- 钱包集成：连接Phantom、Solflare和其他Solana钱包
- 付款方式：用户友好的支付流程，实时状态
- 交易记录：查看并验证所有付款收据
- 资源发现：浏览可用的付费API
- 收据查看器：在Solscan上验证交易
🔧 开发者工具
- RESTful API：标准HTTP端点
- 发现端点:
.well-known/x402协议遵从 - 代码示例：TypeScript、Python、Go实现
- 综合文档：API参考资料、开发人员指南、教程
- E2E测试：完整的测试套件
📊 链上注册
- 去中心化发现：来自Solana区块链的查询API
- 提供者注册：注册API链上
- 类别式组织：按类型组织API
- 主动/非主动管理：控制API可用性
🛠️ 技术栈
后端
- Node.js 18+ -运行时环境
- TypeScript 5.6 -类型安全开发
- Express.js -Web框架
- 萨德 -架构验证
区块链
- 索拉纳 -区块链平台
- 锚固框架 -Solana程序框架
- @solana/web3.js -Solana JavaScript SDK
- @solana/spl令牌 -代币操作
前端
- Next.js 14 -React框架
- 反应18 -UI库
- Tailwind CSS -造型
- @solana/钱包适配器 -钱包集成
基础设施
- 码头工人 -集装箱化
- 瑞迪斯 -缓存和存储（可选）
- Vitest -测试框架
工具和库
- 皮诺 -日志记录
- 日期fns -日期实用程序
- 热烤面包 -通知
🏗️ 建筑
系统架构图
UML序列图（泳道）
以下Mermaid图显示了客户、提供商、协调人和Solana在泳道上的端到端x402支付流：
sequenceDiagram
autonumber
box Client
participant C as Client (Web UI / Agent)
end
box Provider API
participant P as Provider API (x402 Guard)
end
box Facilitator
participant F as Facilitator (Verify & Settle)
end
box Solana
participant S as Solana Network
end
C->>P: 1) GET /api/data (no X-PAYMENT)
P-->>C: 2) 402 Payment Required + PaymentRequirements
note over C: Create x402 Payment Header<br/>- Secure nonce<br/>- Time window<br/>- Authorization payload
C->>P: 3) GET /api/data with X-PAYMENT
P->>F: 4) POST /verify { paymentHeader, requirements }
F-->>P: 5) { isValid: true }
P->>F: 6) POST /settle { paymentHeader, requirements }
F->>S: 7) Submit transaction (native/SPL)
S-->>F: 8) Confirmed (tx hash)
F-->>P: 9) { success: true, txHash }
P-->>C: 10) 200 OK + X-PAYMENT-RESPONSE (txHash)
或者，这是一个使用Mermaid流程图子图（泳道）的泳道式活动视图：
flowchart LR
subgraph L1[Client]
A[Request /api/data] --> B[Receive 402 + Requirements]
B --> C[Create X-PAYMENT header]
C --> D[Call /api/data with header]
end
subgraph L2[Provider]
D --> E[Verify with Facilitator]
E --> G[Settle with Facilitator]
G --> H[Return 200 + X-PAYMENT-RESPONSE]
end
subgraph L3[Facilitator]
E --> F[Verify Authorization]
G --> I[Build & Submit Transaction]
end
subgraph L4[Solana]
I --> J[Confirm Transaction]
end
J --> H
付款流程顺序
┌─────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────┐
│ Client │ │ Provider │ │ Facilitator │ │ Solana │
└────┬────┘ └────┬─────┘ └──────┬──────┘ └────┬─────┘
│ │ │ │
│ 1. GET /api/data │ │ │
├──────────────────►│ │ │
│ │ │ │
│ 2. 402 Payment │ │ │
│ Required │ │ │
│ + Requirements │ │ │
│◄──────────────────┤ │ │
│ │ │ │
│ 3. Create Payment │ │ │
│ Authorization │ │ │
│ (with nonce) │ │ │
│ │ │ │
│ 4. POST /api/data │ │ │
│ + X-PAYMENT │ │ │
│ header │ │ │
├──────────────────►│ │ │
│ │ │ │
│ │ 5. POST /verify │ │
│ ├──────────────────────►│ │
│ │ │ │
│ │ 6. Verify Response │ │
│ │ {isValid: true} │ │
│ │◄──────────────────────┤ │
│ │ │ │
│ │ 7. POST /settle │ │
│ ├──────────────────────►│ │
│ │ │ │
│ │ │ 8. Create Transaction│
│ │ ├─────────────────────►│
│ │ │ │
│ │ │ 9. Transaction Hash │
│ │ │◄─────────────────────┤
│ │ │ │
│ │ 10. Settlement Resp │ │
│ │ {success: true, │ │
│ │ txHash: "..."} │ │
│ │◄──────────────────────┤ │
│ │ │ │
│ 11. 200 OK │ │ │
│ + X-PAYMENT- │ │ │
│ RESPONSE │ │ │
│◄──────────────────┤ │ │
│ │ │ │
组件交互
┌─────────────────────────────────────────────────────────────┐
│ Web UI (Next.js) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Wallet │ │ Payment │ │ Resource │ │
│ │ Provider │ │ Modal │ │ Card │ │
│ │ │ │ │ │ │ │
│ │ • Connect │ │ • Show │ │ • Display │ │
│ │ • Sign │ │ Amount │ │ Info │ │
│ │ • State │ │ • Execute │ │ • Trigger │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
│
│ HTTP
▼
┌─────────────────────────────────────────────────────────────┐
│ Provider API Service │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ x402 Guard Middleware │ │
│ │ │ │
│ │ 1. Check X-PAYMENT header │ │
│ │ 2. If missing → Return 402 │ │
│ │ 3. If present → Verify with Facilitator │ │
│ │ 4. If valid → Settle with Facilitator │ │
│ │ 5. If settled → Allow request to proceed │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ │ POST /verify, /settle │
│ ▼ │
└─────────────────────────────────────────────────────────────┘
│
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Facilitator Service │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Verification Engine │ │
│ │ │ │
│ │ • Parse payment header │ │
│ │ • Validate signature │ │
│ │ • Check nonce (replay protection) │ │
│ │ • Validate time window │ │
│ │ • Verify amount & recipient │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Settlement Engine │ │
│ │ │ │
│ │ • Create Solana transaction │ │
│ │ • Sign with fee payer │ │
│ │ • Submit to blockchain │ │
│ │ • Wait for confirmation │ │
│ │ • Return transaction hash │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ │ RPC │
│ ▼ │
└─────────────────────────────────────────────────────────────┘
│
│
▼
┌──────────────┐
│ Solana │
│ Blockchain │
└──────────────┘
🚀 快速开始
先决条件
- Node.js 18+和npm/pnpm
- Solana CLI（可选，用于合约部署）
- Docker（可选，用于容器化部署）
安装
# Clone the repository
git clone https://github.com/yourusername/microapi-hub.git
cd microapi-hub
# Install dependencies
npm install --workspaces
启动服务
1.主持人服务
cd services/facilitator
# Create .env file
cat > .env << EOF
PORT=8787
NETWORK=devnet
RPC_URL=https://api.devnet.solana.com
FEE_PAYER_SECRET= # Optional: base58-encoded keypair
SETTLEMENT_MODE=native
DEMO_MODE=true
EOF
# Start facilitator
npm run dev
2.供应商API
cd services/provider-api
# Create .env file
cat > .env << EOF
PORT=8080
PAY_TO_PUBKEY=YOUR_SOLANA_PUBKEY
USDC_MINT=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
FACILITATOR_URL=http://localhost:8787
EOF
# Start provider API
npm run dev
3.Web用户界面
cd clients/web
# Create .env.local file
cat > .env.local << EOF
NEXT_PUBLIC_PROVIDER_DISCOVERY_URL=http://localhost:8080/.well-known/x402
EOF
# Start web UI
npm run dev
访问应用程序
- 🌐 Web用户界面: http://localhost:3000
- 🔌 供应商API: http://localhost:8080
- ⚙️ 引导者: http://localhost:8787
🔧 服务
主持人服务
支付验证和链上结算服务。
终点：
POST /verify-验证付款授权POST /settle-在链上结算付款GET /health-健康检查GET /supported-支持的支付方案
主要特点：
- ✅ 签名验证
- ✅ Nonce重放保护
- ✅ 时间窗口验证
- ✅ 本地SOL和SPL代币结算
- ✅ devnet上的自动融资
- ✅ Redis/基于文件的存储
供应商API
具有x402支付保护的API服务器。
终点：
GET /api/data-受保护端点（示例）GET /.well-known/x402-发现端点GET /health-健康检查
主要特点：
- ✅ 402付款要求回复
- ✅ 支付验证集成
- ✅ 自动结算
- ✅ 发现端点
- ✅ 资源保护中间件
Web用户界面
Next.js应用程序与钱包集成。
特征：
- ✅ 钱包连接（幻影、Solflare）
- ✅ 实时状态的支付方式
- ✅ 资源发现
- ✅ 交易历史记录
- ✅ 收据查看器
- ✅ 代码示例
- ✅ 全面的文件
📚 文档
核心文件
应用内文档
- 📝 例子: http://localhost:3000/examples-多种语言的代码示例
- ❓ 常见问题解答: http://localhost:3000/faq-常见问题
- 📄 API文件: http://localhost:3000/api-交互式API文档
💻 发展
项目结构
microapi-hub/
├── services/
│ ├── facilitator/ # Payment verification & settlement
│ │ ├── src/
│ │ │ ├── index.ts # Main facilitator service
│ │ │ ├── config.ts # Configuration management
│ │ │ ├── errors.ts # Error handling
│ │ │ └── registry.ts # Registry client
│ │ └── package.json
│ └── provider-api/ # Protected API server
│ ├── src/
│ │ ├── index.ts # Main provider service
│ │ └── config.ts # Configuration
│ └── package.json
├── clients/
│ ├── web/ # Next.js web UI
│ │ ├── app/ # Next.js app router
│ │ ├── components/ # React components
│ │ ├── lib/ # Utilities
│ │ └── package.json
│ └── agent-demo/ # Example client
├── contracts/
│ └── registry/ # Solana Anchor program
│ └── programs/
│ └── registry/
│ └── src/
│ └── lib.rs # Registry contract
├── shared/
│ └── types/ # Shared TypeScript types
│ ├── x402.ts # x402 protocol types
│ ├── errors.ts # Error types
│ └── registry.ts # Registry types
├── docs/ # Documentation
│ ├── API.md
│ └── DEVELOPER.md
├── infra/ # Infrastructure
│ └── docker-compose.yml
└── x402/ # x402 protocol library
运行测试
# Run all tests
npm test
# Run E2E tests
npm run e2e
建筑
# Build all services
npm run build
码头工人
# Start all services with Docker Compose
cd infra
docker-compose up
🏆 黑客马拉松提交
满足要求
✅ x402协议集成：完整规范实施
✅ Solana集成：已部署到devnet，主网就绪
✅ 开源：GitHub上的所有代码
✅ 演示视频：3分钟演示
✅ 文档：全面的设置和使用指南
演示视频
看 哈克顿.md 有关演示视频脚本和提交详细信息。
是什么让这个特别
- 完整堆栈：从主持人到用户界面的端到端实施
- 生产准备就绪：错误处理、验证、日志记录、测试
- 开发者友好：全面的文档、代码示例、易于集成
- 链上注册：去中心化API发现
- 多语言：支持TypeScript、Python、Go
- 钱包集成：使用钱包适配器实现无缝支付用户体验
🤝 贡献
欢迎投稿！请随时提交拉取请求。
- 分叉存储库
- 创建功能分支(
git checkout -b feature/AmazingFeature) - 提交您的更改(
git commit -m 'Add some AmazingFeature') - 推到分支(
git push origin feature/AmazingFeature) - 打开拉取请求
开发指南
- 遵循TypeScript的最佳实践
- 为新功能编写测试
- 更新文档
- 遵循现有代码样式
- 确保所有测试通过
📝 许可证
这个项目是开源的。看 许可证 文件以获取详细信息。
🙏 致谢
- Coinbase 适用于x402协议规范
- 索拉纳黑客马拉松基金会
- 所有开源贡献者
📞 支持
- 📖 文档：参见
/docs目录 - 💻 例子: http://localhost:3000/examples
- ❓ 常见问题解答: http://localhost:3000/faq
- 🐛 GitHub问题：[存储库URL]/问题
🚧 路线图
- []主网部署
- []多链支持（EVM）
- []预付款方案
- []分析仪表板
- []Webhook通知
- []客户端SDK包
- []每位客户的费率限制
- []使用情况分析
内置于❤️ Solana X402黑客马拉松