内容
# XAgent 支付 API
AI 代理和开发者使用的 XRPL 支付 API
## 介绍
基于 FastAPI 的 XRPL（XRP Ledger）测试网支付服务器。抽象复杂的区块链逻辑，使 AI 代理和应用程序轻松集成 XRP 和 RLUSD 支付。
- **支持货币：** XRP, RLUSD（稳定币）
- **认证：** 可发行/废止的 API 密钥，按层级划分的费用和限额
- **钱包：** API 密钥发行时自动创建/资助专用 XRPL 钱包（每个代理单独运营）
- **观察：** 使用量仪表盘（Web UI），交易历史，累计费用查询
- **通知：** 支付成功/失败时 Webhook 回调（签名验证 + 重试）
## 快速开始
```bash
# 1. 克隆存储库并安装依赖
pip install -r requirements.txt
# 2. 创建 .env 文件（复制 .env.example 并填写值）
cp .env.example .env
```
`.env` 中至少需要填写以下值才能启动服务器：
```bash
SENDER_ADDRESS=测试网_XRP 地址 # 平台公用钱包（旧密钥备用）
SENDER_SECRET=密钥
FEE_ACCOUNT=手续费接收地址
XRPL_NODE=wss://s.altnet.rippletest.net:51233
ADMIN_API_KEY=强大的管理员密钥 # 用于发行/废止 API 密钥（无则禁用 /admin/keys）
```
如果没有测试网账户，请在 [XRPL Faucet](https://xrpl.org/xrp-testnet-faucet.html) 获取。
```bash
# 3. 启动服务器
python main.py
# 或
uvicorn main:app --host 0.0.0.0 --port 8000
# 生产环境（但请参考“已知限制” - 目前设计为单 worker）
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1
```
- API：http://localhost:8000
- Swagger 文档：http://localhost:8000/docs
- 使用量仪表盘：http://localhost:8000/dashboard
```bash
# 4. 发行第一个 API 密钥（使用管理员密钥运行一次）
curl -X POST "http://localhost:8000/admin/keys" \
-H "Content-Type: application/json" \
-H "X-Admin-Key: your_admin_key" \
-d '{"name": "my-first-agent", "tier": "free"}'
```
响应中收到的 `api_key` 是后续所有请求的 `X-API-Key` 值。请安全保管，**仅在该响应中以明文显示**。响应中的 `wallet_address` 是为该密钥自动创建/资助的钱包地址。
## 定价政策
| 层级 | 价格 | 每月请求限额 | 支付手续费率 |
|---|---|---|---|
| Free | $0 | 100 次 | 1% |
| Pro | $49/月 | 无限制 | 0.15% |
| Enterprise | 自定义 | 无限制 | 自定义协商（根据用量调整） |
- Pro 的 $49/月 订阅费不由该 API 直接处理（在单独的 SaaS 计费层处理）。
- 该 API 实际应用的仅有**每笔交易手续费率**。
- Enterprise 可以在发行密钥时指定 `fee_rate` 以覆盖层级默认值。
## 认证 — API 密钥发行/查询/废止
密钥发行和废止是管理员专属的（`X-Admin-Key` 头部），而所有其他 API 则使用已发行的密钥（`X-API-Key` 头部）调用。
```bash
# 发行密钥（包括自动创建专用钱包）
curl -X POST "http://localhost:8000/admin/keys" \
-H "Content-Type: application/json" \
-H "X-Admin-Key: your_admin_key" \
-d '{"name": "customer-a-bot", "tier": "pro"}'
# 查询密钥列表（不显示明文密钥）
curl "http://localhost:8000/admin/keys" -H "X-Admin-Key: your_admin_key"
# 废止密钥
curl -X POST "http://localhost:8000/admin/keys/{key_id}/revoke" \
-H "X-Admin-Key: your_admin_key"
```
| 代码 | 说明 |
|------|------|
| 401 | 无 API 密钥 |
| 403 | API 密钥无效或已废止 |
| 429 | 层级月限额超限 |
| 503 | 未设置 `ADMIN_API_KEY`，管理员 API 已禁用 |
## 钱包管理（多代理）
发行 API 密钥时，**专用钱包将自动创建/资助**至 XRPL 测试网 faucet。后续使用该密钥进行的支付将从**专用钱包**而非平台公用钱包中扣除 — 多个代理同时支付时，钱包（= XRPL 序列号）是分离的，不会冲突。
```bash
curl "http://localhost:8000/wallet/info" -H "X-API-Key: your_api_key"
```
```json
{
"wallet_address": "r...",
"balance_xrp": 998.5,
"dedicated": true
}
```
`dedicated: false` 表示专用钱包创建/资助失败（例如测试网 faucet 速率限制）或 `.env` 中的 `API_KEYS` 迁移了旧密钥，共享平台公用钱包。
## 支付 API
所有支付 API 都需要 `X-API-Key` 头部。
### 创建支付
**XRP 支付：**
```bash
curl -X POST "http://localhost:8000/payment/create" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"recipient_address": "rExampleAddress...",
"amount": 10.0,
"currency": "XRP"
}'
```
**RLUSD 支付：**
```bash
curl -X POST "http://localhost:8000/payment/create" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"recipient_address": "rExampleAddress...",
"amount": 100.0,
"currency": "RLUSD"
}'
```
⚠️ **RLUSD 支付前注意事项：** 接收者必须先为 RLUSD 代币设置 trust line。
**响应：** （手续费率根据 API 密钥层级不同 - 以下是 Pro 层级的示例）
```json
{
"success": true,
"tx_hash": "交易哈希",
"fee_amount": 0.015,
"fee_rate": 0.0015,
"sent_amount": 9.985,
"remaining_quota": null
}
```
### 验证/查询支付状态
```bash
curl "http://localhost:8000/payment/verify/{tx_hash}" -H "X-API-Key: your_api_key"
curl "http://localhost:8000/payment/status/{tx_hash}" -H "X-API-Key: your_api_key"
```
### 支持的货币和手续费率查询（无需认证）
```bash
curl "http://localhost:8000/payment/rates"
```
```json
{
"supported_currencies": {
"XRP": {"currency": "XRP", "issuer": null, "scale": 6},
"RLUSD": {"currency": "RLUSD", "issuer": "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De", "scale": 5}
},
"default_currency": "XRP",
"fee_rates_by_tier": {"free": 0.01, "pro": 0.0015, "enterprise": 0.0015}
}
```
## 使用量仪表盘
在浏览器中打开 http://localhost:8000/dashboard，输入 API 密钥后，可以在一个页面上查看层级、本月请求数/剩余配额、各类累计手续费、最近交易历史、钱包地址/余额。
同样的数据也可以通过 API 查询：
```bash
# 限额 + 累计手续费 + 最近交易（与仪表盘页面调用相同）
curl "http://localhost:8000/usage/dashboard" -H "X-API-Key: your_api_key"
# 仅交易历史
curl "http://localhost:8000/usage/transactions?limit=50" -H "X-API-Key: your_api_key"
# 仅限额
curl "http://localhost:8000/usage/info" -H "X-API-Key: your_api_key"
```
## 速率限制
- **Free:** 超过每月 100 次请求，返回 `429 Too Many Requests`
- **Pro / Enterprise:** 无限制（无请求次数限制，仅按手续费收费）
- 限额可通过环境变量 `FREE_MONTHLY_LIMIT` 调整
## Webhook 通知
支付成功（`payment.success`）/失败（`payment.failed`）时，将事件发送到指定 URL。失败时将重试 2 次，间隔 2 秒、10 秒、60 秒。
```bash
# 注册（每次注册都会生成新的签名密钥，仅在该响应中可见）
curl -X PUT "http://localhost:8000/webhook" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"url": "https://your-server.com/xagent-webhook"}'
# 查询
curl "http://localhost:8000/webhook" -H "X-API-Key: your_api_key"
# 删除
curl -X DELETE "http://localhost:8000/webhook" -H "X-API-Key: your_api_key"
```
接收服务器使用 `X-XAgent-Signature: sha256=<hmac>` 头部验证签名：
```python
import hmac, hashlib
expected = hmac.new(webhook_secret.encode(), request_body, hashlib.sha256).hexdigest()
is_valid = hmac.compare_digest(expected, received_signature.removeprefix("sha256="))
```
内部/私有 IP 地址（localhost、内网等）无法注册为 webhook URL 以防止 SSRF。
## x402 支付
支持 AI 代理的 HTTP 402 Payment Required 标准
```bash
# 1. 请求需要支付的资源
curl "http://localhost:8000/data/market-info"
# → 402 Payment Required + 支付信息头部
# 2. 创建 x402 支付
curl -X POST "http://localhost:8000/x402/create-payment" \
-H "X-API-Key: your_api_key"
# 3. 发行访问令牌
curl -X POST "http://localhost:8000/x402/pay" \
-H "Content-Type: application/json" \
-d '{"tx_hash": "交易哈希"}'
# 4. 使用令牌访问资源
curl "http://localhost:8000/data/market-info" \
-H "X-Payment-Token: access_token"
```
## RLUSD Trust Line 配置指南
### 什么是 Trust Line？
Trust Line 是 XRPL 中用于 IOU 代币（例如 RLUSD）的许可额度。每个发行者都需要配置 Trust Line 才能接收该代币。
### Trust Line 配置方法
#### 1. 使用 Xaman 钱包（推荐）
```
1. 访问 Xaman 钱包（https://xaman.app）
2. 设置为测试网 → "I want to add a trust line"
3. 输入以下信息：
- Currency: USD
- Issuer: rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De
4. 设置 Trust Line 限额（例如 1000）
5. 确认并设置
```
#### 2. 使用 XRPL Explorer
```
1. 访问 XRPL Testnet Explorer（https://testnet.xrpl.org）
2. 搜索钱包地址
3. "Trust Lines" 标签页 → "Add Trust Line"
4. Currency: USD, Issuer: rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De
5. 设置限额后添加
```
### 查询 Trust Line
```bash
curl "http://localhost:8000/payment/trustline/{address}" \
-H "X-API-Key: your_api_key"
```
**响应（无 Trust Line）：**
```json
{
"address": "rExampleAddress...",
"has_rlUSD_trustline": false,
"rlUSD_limit": null,
"rlUSD_balance": null,
"message": "RLUSD 的 Trust Line 未配置。"
}
```
### 无 Trust Line 的错误
如果 RLUSD 支付时接收者未配置 Trust Line，将返回以下错误：
```json
{
"detail": "接收者未为 RLUSD 代币配置 Trust Line。接收者必须先配置 Trust Line 才能接收 RLUSD。"
}
```
**解决方法：** 向接收者提供上述 Trust Line 配置指南，并引导他们配置 Trust Line。
## Claude MCP 集成
Claude AI 可以直接调用 XAgent Pay API 作为工具。
### 安装和运行
```bash
# 启动 XAgent Pay API 服务器
python main.py
# 启动 MCP 服务器（单独的终端）
python mcp_server.py
```
在 `.env` 中指定 MCP 将使用的 API 密钥：
```bash
MCP_API_KEY=your_api_key
```
### 配置 Claude Desktop
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"xagent-pay-api": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"XAGENT_PAY_API_URL": "http://localhost:8000",
"MCP_API_KEY": "your_api_key"
}
}
}
}
```
### 可用工具
- **get_rates** — 查询支持的货币和手续费
- **create_payment** — 创建 XRP/RLUSD 支付
- **verify_payment** — 验证交易
- **check_trustline** — 查询 RLUSD Trust Line
### 演示
Claude AI 直接支付 1 XRP 的实际结果：
- 接收地址：rM9SpkNUPUygwTcE7baTYTeZWP6BwhKePK
- 实际支付金额：0.99 XRP
- 手续费：0.01 XRP（1%）
- 交易哈希：CB2AC710B2EA8E335FB7EBEB258306CE96C30C0F09ABD728087C6099AC28D9AB
## 路线图
- [x] 支持 x402 代币
- [x] 支持 RLUSD（稳定币）
- [x] 支持 MCP 服务器（与 Claude AI 集成）
- [x] 可发行/废止的 API 密钥 + 按层级认证
- [x] 使用量仪表盘
- [x] 速率限制 + 多钱包管理
- [x] Webhook 通知
- [ ] 支持更多 IOU 代币
- [ ] 部署到主网
- [ ] 批量支付
## 已知限制
- 目前 API 密钥/交易/webhook 配置存储在基于 JSON 文件。单个进程（`--workers 1`）是安全的。如果要扩展到多个 worker 实例，需要迁移到 SQLite 等（详见 [TODO_MIGRATION.md](TODO_MIGRATION.md)）。
- 目前仅限测试网。迁移到主网时需要额外的安全审查。
## 安全
- **专用钱包种子（seed）使用 `SECRET_ENCRYPTION_KEY`（Fernet）加密存储。** 如果没有此密钥，专用钱包创建将被禁用（防止明文存储）。请勿将主密钥硬编码到代码中，仅在 `.env` 中管理。
- `.env` 中的 `SENDER_SECRET`（平台公用钱包）仍为明文 - 由于它是启动时所需的启动凭证，因此它位于此应用存储加密范围之外。迁移到主网时，请考虑集成 KMS/Secrets Manager。
⚠️ **目前仅限测试网**。迁移到主网时，请额外审查以下内容：
- 将 API 密钥/管理员密钥存储迁移到 SQLite 等并加强访问控制
- Webhook 目标 URL 的 SSRF 防护逻辑（当前已应用私有/环回 IP 阻止）和 DNS 重绑定防御强化
## 许可证
MIT License
## GitHub 仓库
该项目在 GitHub 上进行管理。错误报告和功能请求请通过 Issues 提交。
---
联系方式：[GitHub Issues](https://github.com/TLSRUF/xagent-pay-api/issues)
