x402 奇点层

x402 是一个 Web3 支付层，人类和智能体可以在此出售和消费 API、产品和服务积分。 本技能涵盖了奇点层的完整生命周期：

• 支付/消费服务
• 创建/管理/列出端点
• 将自定义支付流程集成到应用或平台中
• 接收并验证 Webhook 支付事件
• 注册智能体并提交链上信誉反馈
• 可选择使用 Singularity MCP 进行所有者范围内的仪表板和控制平面操作

网络：Base、Ethereum、Polygon、BSC、Monad、Solana
货币：USDC
协议：HTTP 402 需要付款

意图路由器

请先使用此路由，然后加载相关的参考文档。

快速入门

1) 安装技能依赖项

pip install -r {baseDir}/requirements.txt

2) 选择钱包模式

选项A：私钥

export PRIVATE_KEY="0x..."
export WALLET_ADDRESS="0x..."
# Solana optional
export SOLANA_SECRET_KEY="base58-or-[1,2,3,...]"

选项B：Coinbase AWAL

# Install Coinbase AWAL skill (shortcut)
npx skills add coinbase/agentic-wallet-skills
export X402_USE_AWAL=1

使用私钥模式进行 ERC-8004 钱包优先注册。AWAL 在 x402 支付流程中仍然有用。

3) 可选仪表板 / MCP 模式

如果用户提供了仪表板 PAT，代理也可以使用 Singularity MCP 执行所有者作用域的账户操作：

export SINGULARITY_PAT="sgl_pat_..."

当任务涉及以下内容时，使用 MCP：

• 列出仪表板用户拥有的所有端点或产品
• 更新端点或产品设置
• 设置或移除 Webhook
• 以所有者作用域的方式请求创建端点或充值支付挑战

保留直接脚本用于：

• 实际请求支付和本地签名
• AWAL 驱动的支付/发现流程
• 支持和 XMTP 流程
• 钱包优先的 ERC-8004 / Solana-8004 注册和更新

安全说明：脚本仅读取显式声明的进程环境变量。.env文件不会自动加载。 安装说明：安装时不需要全局设置任何秘密环境变量。只需根据您正在使用的操作手册，设置所需的那部分变量。

脚本清单

消费者

提供方

智能体注册与信誉系统

核心安全要求

在源站进行 API 密钥验证（强制要求）

当 x402 将流量代理到您的源站时，请验证：

x-api-key: <YOUR_API_KEY>

当缺失或无效时拒绝请求。

积分经济体系（提供方侧）

• 端点创建：一次性 1 美元
• 初始积分：4,000
• 充值汇率：每 1 美元兑换 500 积分
• 消耗：每次请求 1 积分
• 如果积分降至 0，端点将停止服务，直到重新充值

快速操作指南

A) 将支付集成到您的应用中

# 1. Create or reuse a paid endpoint
python {baseDir}/scripts/create_endpoint.py my-api "My API" https://api.example.com 0.01

# 2. Add server-side fulfillment
python {baseDir}/scripts/manage_webhook.py set my-api https://my-server.com/webhook

# 3. Verify webhook signatures and payment receipts server-side
python {baseDir}/scripts/verify_webhook_payment.py \
  --body-file ./webhook.json \
  --signature 't=1700000000,v1=<hex>' \
  --secret '<YOUR_SIGNING_SECRET>' \
  --required-source-slug my-api \
  --require-receipt

B) 支付与消耗

python {baseDir}/scripts/pay_base.py https://api.x402layer.cc/e/weather-data
python {baseDir}/scripts/pay_base.py https://api.x402layer.cc/e/weather-data --agentkit auto
python {baseDir}/scripts/pay_solana.py https://api.x402layer.cc/e/weather-data
python {baseDir}/scripts/consume_credits.py https://api.x402layer.cc/e/weather-data

C) 发现/搜索市场

python {baseDir}/scripts/discover_marketplace.py
python {baseDir}/scripts/discover_marketplace.py search weather
python {baseDir}/scripts/discover_marketplace.py details weather-api

D) 创建和管理端点

python {baseDir}/scripts/create_endpoint.py my-api "My API" https://api.example.com 0.01
python {baseDir}/scripts/manage_endpoint.py list
python {baseDir}/scripts/manage_endpoint.py update my-api --price 0.02
python {baseDir}/scripts/topup_endpoint.py my-api 10

E) 在市场列表/更新

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

F) Webhook 设置与真实性验证

python {baseDir}/scripts/manage_webhook.py set my-api https://my-server.com/webhook
python {baseDir}/scripts/manage_webhook.py info my-api
python {baseDir}/scripts/manage_webhook.py remove my-api

Webhook 验证辅助工具：

python {baseDir}/scripts/verify_webhook_payment.py \
  --body-file ./webhook.json \
  --signature 't=1700000000,v1=<hex>' \
  --secret '<YOUR_SIGNING_SECRET>' \
  --required-source-slug my-api \
  --require-receipt

G) World AgentKit 优势

# Inspect whether a listing advertises a verified human-backed agent wallet benefit
python {baseDir}/scripts/discover_marketplace.py details weather-data

# Attempt Base payment with AgentKit if the endpoint advertises a benefit
python {baseDir}/scripts/pay_base.py https://api.x402layer.cc/e/weather-data --agentkit auto

# Require AgentKit qualification instead of silently falling back
python {baseDir}/scripts/pay_base.py https://api.x402layer.cc/e/weather-data --agentkit required

H) XMTP 支持线程

# Authenticate the current wallet for support APIs
python {baseDir}/scripts/support_auth.py login

# Check whether support is available for a listing
python {baseDir}/scripts/support_threads.py eligibility endpoint weather-data

# Open or reuse the support thread
python {baseDir}/scripts/support_threads.py open endpoint weather-data

# Read and send XMTP messages for a support thread
node {baseDir}/scripts/xmtp_support.mjs messages <thread_id>
node {baseDir}/scripts/xmtp_support.mjs send <thread_id> "Need help with this endpoint"

I) MCP 所有者作用域控制平面

# Set a dashboard PAT only for owner-scoped control-plane actions
export SINGULARITY_PAT="sgl_pat_..."

# Then use Singularity MCP for owner inventory/config operations such as:
# - list_my_endpoints
# - update_endpoint
# - list_my_products
# - update_product
# - set_webhook
# - remove_webhook
# - request_endpoint_creation_payment

J) 代理注册 + 声誉

python {baseDir}/scripts/list_my_endpoints.py

python {baseDir}/scripts/register_agent.py \
  "My Agent" \
  "Autonomous service agent" \
  --network baseSepolia \
  --image https://example.com/agent.png \
  --version 1.9.1 \
  --tag finance \
  --tag automation \
  --endpoint-id <ENDPOINT_UUID> \
  --custom-endpoint https://api.example.com/agent

python {baseDir}/scripts/list_agents.py --network baseSepolia

python {baseDir}/scripts/update_agent.py \
  --network baseSepolia \
  --agent-id 123 \
  --version 1.4.1 \
  --tag finance \
  --tag automation \
  --endpoint-id <ENDPOINT_UUID> \
  --public

# The same EVM flow also supports:
#   --network ethereum
#   --network polygon
#   --network bsc
#   --network monad

python {baseDir}/scripts/submit_feedback.py \
  --network base \
  --agent-id 123 \
  --rating 5 \
  --comment "High quality responses"

参考资料

仅加载用户任务所需内容：

• 参考资料/支付集成.md： 产品 vs 端点 vs 积分的决策指南，以及 webhook/收据履行模式。
• 参考资料/按请求付费.md： EIP-712/Solana 支付流程和底层签名细节。
• 参考资料/基于积分的.md： 积分购买 + 消耗行为及示例。
• 参考资料/市场.md: 搜索/列出/取消列出市场端点。
• 参考资料/agentkit-权益.md: 发现、获取资格并利用World AgentKit人工支持代理钱包权益进行支付。
• 参考资料/代理端点.md: 端点创建/充值/状态API行为。
• 参考资料/webhooks-验证.md: webhook事件、签名验证和收据交叉检查。
• 参考资料/代理注册表-声誉.md: ERC-8004/Solana-8004注册、发现、管理和反馈规则。
• 参考资料/xmtp-支持.md: 支持聊天在Studio中的工作原理、需要人工设置的内容以及代理应如何与用户协调。
• 参考资料/mcp-控制平面.md: 何时使用Singularity MCP、需要哪些PAT作用域，以及哪些所有者作用域的操作应优先使用MCP而非直接脚本。
• 参考资料/支付签名.md: 确切的签名域/类型/头部负载详细信息。

环境参考

没有单一任务需要用到以下所有变量。请遵循最小权限原则，仅设置当前脚本所需的变量。

通用

可选的 MCP 控制平面

提供商与市场管理

Solana

支持与XMTP

代理注册和反馈

API 基础路径

• 端点：https://api.x402layer.cc/e/{slug}
• 市场：https://api.x402layer.cc/api/marketplace
• 积分：https://api.x402layer.cc/api/credits/*
• 代理路由：https://api.x402layer.cc/agent/*
• MCP：https://mcp.x402layer.cc/mcp

资源

• 文档：https://studio.x402layer.cc/docs/agentic-access/openclaw-skill
• MCP 文档：https://studio.x402layer.cc/docs/agentic-access/mcp-server
• SDK 文档：https://studio.x402layer.cc/docs/developer/sdk-receipts
• GitHub 文档仓库：https://github.com/ivaavimusic/SGL_DOCS_2025
• x402 Studio：https://studio.x402layer.cc

已知问题

Solana 精确支付流程必须使用费用支付方由挑战返回，并将交易的计算单元限制保持在协调方要求范围内。pay_solana.py和solana_signing.py已为当前 PayAI 支持的流程处理此问题；当你需要最简单的生产路径时，建议优先使用 Base。