介绍
# x402 Singularity Layer
x402 是一个 **Web3 支付层**，使 AI 智能体能够： - 💰 使用 USDC **支付** API 访问费用 - 🚀 **部署** 货币化端点 - 🔍 通过市场 **发现** 服务 - 📊 **管理** 端点和信用额度
**网络：** Base (EVM) • Solana **货币：** USDC **协议：** HTTP 402 Payment Required
---
## 快速开始
### 1. 安装依赖 ```bash pip install -r {baseDir}/requirements.txt ```
### 2. 设置钱包（选择一种模式）
#### 选项 A：私钥（现有模式） ```bash # For Base (EVM) export PRIVATE_KEY="0x..." export WALLET_ADDRESS="0x..."
# For Solana (optional) export SOLANA_SECRET_KEY="[1,2,3,...]" # JSON array ```
#### 选项 B： Coinbase Agentic Wallet (AWAL)
若要不暴露私钥进行 Base 支付，请使用 Coinbase Agentic Wallet：
```bash # First, install and set up AWAL (one-time setup) npx skills add coinbase/agentic-wallet-skills
# Then enable AWAL mode for this skill export X402_USE_AWAL=1 ```
> **注意**：完整设置说明请参阅 [Coinbase AWAL 文档](https://docs.cdp.coinbase.com/agentic-wallet/welcome)。您需要通过身份验证并在 Base 网络上为您的 AWAL 钱包充值 USDC。
配置好 AWAL 后，所有 Base 支付脚本将自动使用它，而不是 PRIVATE_KEY。
---
## ⚠️ 安全公告
> **重要提示**：此技能涉及处理用于签署区块链交易的私钥。 > > - **切勿使用您的主托管钱包** - 请创建一个仅存有少量资金的专用钱包 > - **私钥仅在本地使用** - 它们在本地签署交易，绝不会被传输 > - **签名载荷会发送至 api.x402layer.cc** - 支付签名和钱包地址会被传输以进行结算 > - **用于测试**：使用一个一次性钱包，存入少量 USDC（1-5 美元足以用于测试） > - **API 密钥**：当您创建端点时，请妥善保存返回的 API 密钥 > - **审查代码**：所有脚本均在 `scripts/` 目录中可审计
---
## 脚本概览
### 🛒 消费者模式（购买服务）
| 脚本 | 用途 | |--------|---------| | `pay_base.py` | 在 Base 网络上支付端点费用 | | `pay_solana.py` | 在 Solana 网络上支付端点费用 | | `consume_credits.py` | 使用预先购买的信用额度（快速） | | `consume_product.py` | 购买数字产品（文件） | | `awal_cli.py` | 运行 Coinbase Agentic Wallet CLI 命令（auth, bazaar, pay, discover） | | `check_credits.py` | 检查您的信用余额 | | `recharge_credits.py` | 为端点购买信用包 | | `discover_marketplace.py` | 浏览可用服务 |
### 🏭 提供者模式（销售服务）
| 脚本 | 用途 | |--------|---------| | `create_endpoint.py` | 部署新的货币化端点（$5） | | `manage_endpoint.py` | 查看/更新您的端点 | | `topup_endpoint.py` | 使用信用额度为您自己的端点充值 | | `list_on_marketplace.py` | 更新市场列表 |
---
## 安全：API 密钥验证
> [!IMPORTANT] > 当您创建端点时，x402 充当您源服务器的代理。您必须验证请求是否来自 x402。
1. **获取您的 API 密钥**：运行 `create_endpoint.py` 时返回。 2. **验证请求头**：您的源服务器必须在每个请求中检查此请求头： ```http x-api-key: <YOUR_API_KEY> ``` 如果请求头缺失或错误，请拒绝该请求（401 Unauthorized）。
---
## 信用系统：工作原理
> [!WARNING] > **信用额度不是测试信用！** 每次请求都会消耗它们。
### 流程
``` User pays $0.01 → Your wallet receives payment → 1 credit deducted from your endpoint ```
### 经济模型
| 项目 | 价值 | |------|-------| | **创建成本** | $5（一次性） | | **起始信用** | 20,000 信用 | | **充值费率** | 每 $1 充值 500 信用 | | **消耗** | 每次 API 请求消耗 1 信用 | | **您的收益** | 您设定的每次调用价格 |
### 示例
1. **创建端点**：支付 $5，获得 20,000 信用 2. **设定价格**：每次调用 $0.01 3. **用户调用您的 API 1,000 次**：您赚取 $10，扣除 1,000 信用 4. **剩余**：19,000 信用 + $10 利润 5. **信用不足？** 使用 `topup_endpoint.py` 充值
### 当信用 = 0 时会发生什么？
您的端点将**停止工作**并返回错误。在您充值之前，用户无法访问它。
---
## 消费者流程
### A. 按需付费（推荐）
```bash # Pay with Base (EVM) - 100% reliable python {baseDir}/scripts/pay_base.py https://api.x402layer.cc/e/weather-data
# Pay with Solana - includes retry logic python {baseDir}/scripts/pay_solana.py https://api.x402layer.cc/e/weather-data
# Pay with Coinbase Agentic Wallet (AWAL) python {baseDir}/scripts/awal_cli.py pay-url https://api.x402layer.cc/e/weather-data ```
### B. 基于信用的访问（最快）
预先购买信用，即时访问，无区块链延迟：
```bash # Check your balance python {baseDir}/scripts/check_credits.py weather-data
# Buy credits (consumer purchasing credits) python {baseDir}/scripts/recharge_credits.py weather-data pack_100
# Use credits for instant access python {baseDir}/scripts/consume_credits.py https://api.x402layer.cc/e/weather-data ```
### C. 发现服务
```bash # Browse all services python {baseDir}/scripts/discover_marketplace.py
# Search by keyword python {baseDir}/scripts/discover_marketplace.py search weather
# AWAL bazaar discovery python {baseDir}/scripts/awal_cli.py run bazaar list ```
---
## 提供者流程
### A. 创建端点（$5 一次性）
部署您自己的货币化 API：
**基础版（未在市场上列出）：** ```bash python {baseDir}/scripts/create_endpoint.py my-api "My AI Service" https://api.example.com 0.01 --no-list ```
**带市场列表（推荐）：** ```bash python {baseDir}/scripts/create_endpoint.py my-api "My AI Service" https://api.example.com 0.01 \ --category ai \ --description "AI-powered data analysis API" \ --logo https://example.com/logo.png \ --banner https://example.com/banner.jpg ```
**可用类别：** `ai`、`data`、`finance`、`utility`、`social`、`gaming`
> **注意**：请保存输出中的 `API Key`，并使用它来保护您的源服务器。
> ⚠️ **重要 - 信用如何工作：** > - **成本：** $5 一次性费用，包含 **20,000 信用**（不是测试信用！） > - **消耗：** 对您端点的 **每次 API 请求** 都会扣除 1 个信用 > - **当信用归零时：** 您的端点将**停止工作**，直到您充值 > - **充值：** 使用 `topup_endpoint.py` 添加更多信用（$1 = 500 信用） > - **用户向您付款：** 每笔用户付款都会进入您的钱包，然后使用 1 个信用
包含 20,000 个起始信用。
### B. 管理您的端点
```bash # List your endpoints python {baseDir}/scripts/manage_endpoint.py list
# View stats python {baseDir}/scripts/manage_endpoint.py stats my-api
# Update price python {baseDir}/scripts/manage_endpoint.py update my-api --price 0.02 ```
### C. 为您的端点充值（保持其工作所必需）
**您的端点每次请求消耗 1 个信用。** 当信用用完时，它将停止工作。充值以保持其活跃状态：
```bash # Add $10 worth of credits (5,000 credits at 500 credits/$1) python {baseDir}/scripts/topup_endpoint.py my-api 10
# Check remaining credits first python {baseDir}/scripts/manage_endpoint.py stats my-api ```
> ⚠️ **请记住：** `topup_endpoint.py` 是供**提供者**为他们**自己的**端点充值的。 > `recharge_credits.py` 是供**消费者**在别人的端点购买信用的。
### D. 市场列表管理
市场列表可以**在创建期间**或**之后单独**进行：
**选项 1：创建期间**（推荐） ```bash python {baseDir}/scripts/create_endpoint.py my-api "My API" https://api.example.com 0.01 \ --category ai \ --description "AI-powered analysis" \ --logo https://example.com/logo.png \ --banner https://example.com/banner.jpg ```
**选项 2：创建后**（稍后更新或列出） ```bash # List or update marketplace listing python {baseDir}/scripts/list_on_marketplace.py my-api \ --category ai \ --description "AI-powered analysis" \ --logo https://example.com/logo.png \ --banner https://example.com/banner.jpg
# Unlist from marketplace python {baseDir}/scripts/list_on_marketplace.py my-api --unlist ```
> **提示：** 您可以随时使用 `list_on_marketplace.py` 更新您的列表 - 更改类别、描述或图片，而无需重新创建端点。
---
## 支付技术细节
### Base (EVM) - EIP-712 签名
使用 USDC `TransferWithAuthorization` (EIP-3009)： - 支付者免 Gas 费 - 促进者（Facilitator）在链上结算 - 100% 可靠
### Solana - 版本化交易
使用 `VersionedTransaction` 和 `MessageV0`： - 促进者（来自 `extra.feePayer`）支付 Gas - SPL 代币 `TransferChecked` 指令 - 约 75% 成功率（包含重试逻辑）
---
## 环境变量参考
| 变量 | 必需于 | 描述 | |----------|--------------|-------------| | `PRIVATE_KEY` | Base 支付（私钥模式） | EVM 私钥 (0x...) | | `WALLET_ADDRESS` | 所有操作 | 您的钱包地址 | | `SOLANA_SECRET_KEY` | Solana 支付 | 字节的 JSON 数组 | | `X402_USE_AWAL` | AWAL 模式 | 设置为 `1` 以启用 Coinbase Agentic Wallet 用于 Base 网络 | | `X402_AUTH_MODE` | 身份验证选择（可选） | `auto`、`private-key` 或 `awal`（默认：auto） | | `X402_PREFER_NETWORK` | 网络选择（可选） | `base` 或 `solana`（默认：base） | | `AWAL_PACKAGE` | AWAL 模式（可选） | AWAL CLI 的 NPM 包/版本（默认：`[email protected]`） | | `AWAL_BIN` | AWAL 模式（可选） | 预安装的 `awal` 二进制文件路径/名称 | | `AWAL_FORCE_NPX` | AWAL 模式（可选） | 设置为 `1` 以强制使用 npx，即使存在 `awal` 二进制文件 |
---
## API 基础 URL
- **端点：** `https://api.x402layer.cc/e/{slug}` - **市场：** `https://api.x402layer.cc/api/marketplace` - **信用：** `https://api.x402layer.cc/api/credits/*` - **Agent API：** `https://api.x402layer.cc/agent/*`
---
## 资源
- 📖 **文档：** [studio.x402layer.cc/docs/agentic-access/openclaw-skill](https://studio.x402layer.cc/docs/agentic-access/openclaw-skill) - 💻 **GitHub 文档：** [github.com/ivaavimusic/SGL_DOCS_2025](https://github.com/ivaavimusic/SGL_DOCS_2025) - 🐦 **OpenClaw：** [x.com/openclaw](https://x.com/openclaw) - 🌐 **x402 Studio：** [studio.x402layer.cc](https://studio.x402layer.cc)
---
## 已知问题
⚠️ **Solana 支付**由于促进者侧费用支付者基础设施问题，成功率约为 75%。`pay_solana.py` 中包含了重试逻辑。**Base (EVM) 支付 100% 可靠**，推荐用于生产环境。