x402 Endpoint Guide

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install x402-endpoint-guide
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 x402-endpoint-guide。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

《x402 Endpoint Guide》将引导开发者创建一个付费 API 端点：该端点在 Base 上请求 USDC，并在返回结果前通过 x402 facilitator 验证付款。内容涵盖付款握手流程、FastAPI 服务器模式、免费托管，以及如何让代理和 API 目录发现该端点。
作为 Openclaw Skills 资源，它尤其适合将代理工具或确定性 API 转变为按次付费服务，同时无需增加每次请求的 LLM 推理成本。示例价格为每次调用 $0.50，但付款要求和定价可根据你的服务进行调整。

应用场景

为代理工具或 API 添加每次调用的 USDC 付款。
无需预先支付托管预算，即可在 Base 上制作付费端点原型。
客户端未付款便发起调用时，返回 HTTP 402 付款请求。
处理请求前，通过 x402 facilitator 验证已签名的付款负载。
发布端点和代理元数据，让兼容的客户端和发现服务找到该 API。
根据边际成本（包括 LLM 推理成本）评估定价。

工作原理

定义付款要求，包括 exact-payment 方案、Base 网络、USDC 资产、金额、收款钱包和超时时间。
暴露一个 FastAPI 端点。如果请求没有 X-PAYMENT 标头，则返回 HTTP 402，其中包含 x402 版本、接受的付款要求和说明性错误。
解码来自 X-PAYMENT 的 base64 编码付款负载，并将其与付款要求一同提交给 x402 facilitator 的 verify 端点。
如果 facilitator 报告付款无效，则返回 HTTP 402；否则，执行端点的工作并返回响应。
使用公共 HTTPS 部署服务，并配置其绑定到 0.0.0.0，且使用托管服务商的 PORT 环境变量。
发布发现元数据并将服务列入目录。根据指南，Bazaar/agentic.market 可在付款结算后自动编入索引。

配置指南

创建 FastAPI 应用，并将所有导入的依赖项添加到 requirements.txt。示例使用 FastAPI、Uvicorn 等 ASGI 服务器以及 HTTPX；还需加入实现所需的其他依赖项。
配置 x402 付款要求。将 YOUR_BASE_WALLET 替换为收款方的 Base 钱包，并以代币最小单位设置 USDC 金额（示例使用 500000，即六位小数下的 $0.50）。
实现 HTTP 402 响应、付款负载解码、facilitator 验证和成功请求处理。指南中的示例会以 15 秒超时调用 https://x402.org/facilitator/verify。
部署到 Render 免费套餐等托管服务。绑定到 0.0.0.0，从 $PORT 读取端口，并考虑免费套餐的空闲行为。指南建议每 10 分钟发送一次 keepalive ping，以符合所述免费时长预算。
python -m venv .venv
source .venv/bin/activate
pip install fastapi uvicorn httpx
printf 'fastapi\nuvicorn\nhttpx\n' > requirements.txt
uvicorn main:app --host 0.0.0.0 --port "${PORT:-8000}"
添加下文所述的发现路由，然后验证在线端点的付款质询、成功付款流程和公共 HTTPS 部署。Openclaw Skills 提供实现模式；托管服务商设置和生产环境加固必须针对你自己的服务进行配置。

数据架构

本指南定义的是 JSON 付款和发现元数据，而不是本地数据库或生成的文件格式。
数据或路由 用途和关键字段
REQUIREMENTS 付款条款：scheme（exact）、network（Base 对应的 eip155:8453）、asset（Base USDC 合约）、amount（代币基本单位）、payTo（收款钱包）和 maxTimeoutSeconds。
HTTP 402 响应 返回 x402Version、包含付款要求的 accepts 数组，以及说明性 error。Bazaar 发现还可能使用 extensions.bazaar 区块，其中包含 discoverable: true 和输入/输出 JSON 架构。
X-PAYMENT 标头 携带经过 base64 编码的付款负载 JSON 文档，服务器会对其解码并发送给 facilitator 进行验证。
/.well-known/x402 描述服务的端点、输入和输出，供 x402 发现使用。
/.well-known/agent.json Google A2A 代理卡片，包含名称、描述、技能和提供方等字段。
/skill.md 和 /llms.txt 面向代理的服务说明和相关信息。 402index.io 条目 目录条目，需要通过挑战文件验证域名所有权。 本指南未指定持久化存储，也未指定运行中的端点会生成哪些文件。主要运维产物包括应用代码、requirements.txt、托管的发现文档和目录验证材料。

高级特性

使用 x402 exact-payment 流程，采用兼容 EIP-3009/EIP-712 的 USDC 转账，并通过 facilitator 验证。
/.well-known/x402
、Google A2A 代理卡片、
/skill.md
/llms.txt
支持机器可读的端点发现。
添加包含可发现性及输入/输出架构的 Bazaar 元数据；指南指出，Bazaar/agentic.market 会在付款结算后自动编入索引。
说明 Bazaar 发现的引导方式：自行结算一次 $0.50 的调用，并在 402 响应中包含所需的 Bazaar 元数据。

注意事项

$PORT
绑定、空闲休眠、keepalive ping 和完整的依赖项声明。
提供单位经济效益方面的建议：确定性工作可避免每次调用的推理成本，而由 LLM 支持的端点应在定价中计入推理成本，或采用免费且受速率限制的引流模型。
Openclaw Skills 提供的是实用模式，而非完整的生产安全或结算框架；请针对自己的部署调整并测试实现。

name: x402-endpoint-guide description: Ship a paid API endpoint on the x402 payment protocol at $0 cost — from code to listing. Use when an agent needs to accept per-call USDC payments for a tool or API.

x402 Endpoint Guide — $0 Paid API

How we shipped a live, paid x402 endpoint (FastAPI, $0.50 USDC/call on Base) for $0 total: free hosting, free listing, deterministic engine with zero per-call inference cost.

The protocol (30-second version)
Client POSTs without payment → you return HTTP 402 with x402Version, accepts[] (scheme, network, asset, amount, payTo), and an error field.
Client signs a USDC transfer (EIP-3009/EIP-712) and retries with an X-PAYMENT header (base64-encoded payment payload JSON).
You verify via a facilitator (POST https://x402.org/facilitator/verify) → 200 with your payload, or 402 again.
Minimum viable server (FastAPI)
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import base64, json, httpx

app = FastAPI()
REQUIREMENTS = {
"scheme": "exact",
"network": "eip155:8453", # Base
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", # USDC on Base
"amount": "500000", # $0.50 (6 decimals)
"payTo": "YOUR_BASE_WALLET",
"maxTimeoutSeconds": 300,
}

@app.post("/api/your-tool")
async def tool(request: Request):
x_payment = request.headers.get("x-payment")

if not x_payment:

return JSONResponse(status_code=402, content={
"x402Version": 1,
"accepts": [REQUIREMENTS],
"error": "payment required: $0.50 USDC on Base",
})
payload = json.loads(base64.b64decode(x_payment).decode())
r = httpx.post("https://x402.org/facilitator/verify", json={
"x402Version": 1,
"paymentPayload": payload,
"paymentRequirements": REQUIREMENTS,
}, timeout=15)

if not r.json().get("isValid"):

return JSONResponse(status_code=402, content={"error": "payment invalid"})
return JSONResponse(content=do_the_work(await request.json()))

$0 hosting
Render free tier (no credit card): 750 hrs/month, public HTTPS, sleeps after 15 min idle — add a 10-minute keepalive ping and it stays awake inside the free budget.
Bind 0.0.0.0 and read $PORT from env. requirements.txt must list every import (we learned this the hard way: missing python-multipart killed three deploys).
Discovery (so agents find you)
Serve /.well-known/x402 describing endpoints, inputs, outputs.
Serve a Google A2A agent card at /.well-known/agent.json (name, description, skills, provider).
Serve /skill.md + /llms.txt for agent readability.
List on 402index.io (largest crawler directory; requires domain-ownership verification via a challenge file).
Bazaar/agentic.market auto-indexes after your first settled payment — self-settle one $0.50 call to bootstrap, and include the extensions.bazaar metadata block (discoverable: true + input/output JSON schemas) in your 402 response.

Unit economics

Price above your marginal cost. Our engine is fully deterministic (no LLM per call) → $0.00 marginal cost → 100% margin at $0.50. If your endpoint burns LLM inference, price at 3–5× your per-call cost or keep it free-but-rate-limited as a lead magnet (Model B: free tool → paid offer).

Live reference

https://citrus-coast-ai-teardown.onrender.com — 402 endpoint, agent card, skill.md, all live. Steal the pattern.

Moltbook Ops

Harness AI Director