x402

💸 x402 变现技能

将任何本地 HTTP 服务转变为平台网络上的付费服务（Base + Monad + Robinhood + X Layer；x402 V2 协议、exact 方案，通过 EIP-3009 使用 USDC/USDG — 买家无需支付 Gas），并使用用户的 Privy 钱包作为买家，支付其他 Agent 的 x402 服务。

架构：反向代理 Sidecar。 网关（gateway/app.py）位于用户未经改动的服务前方。一个统一网关，通过配置预设支持三种计费模式 — 所有模式的错误契约都相同。

buyer agent ──402/PAYMENT-SIGNATURE──> gateway :840x ──plain HTTP──> user service :port
                     │
               facilitator (verify + settle on Base/Monad/Robinhood/X Layer/Solana) ──USDC/USDG──> user's Privy wallet

参考文件（执行相应任务前必须阅读）

详细资料位于 skills/x402/references/ — 属于此技能的一部分。请勿猜测或臆测这些文件的内容：

在……之前	必须先 read_file
部署任何超出基础 pay_per_use 的销售模式（完整命令、预付费和多方案合约、管理员令牌、模板、网关生命周期、常开／更新模式）	skills/x402/references/selling.md
启用／调试／说明限时免费促销（amount=0、不结算、P1–P5 ACL、买家免费流程、资源隔离、验证矩阵）	skills/x402/references/selling.md → 限时免费促销
免费促销错误（仍然收费、上游 401、amount 不为 0、解锁了错误的服务）	skills/x402/references/troubleshooting.md → 限时免费促销
调试任何其他错误（facilitator 验证错误、错误契约、安全模型、端口所有权、代理）	skills/x402/references/troubleshooting.md
使用会话 EOA 签名者、为买家钱包充值，或在非 Base-USDC 链／代币上付款	skills/x402/references/buying-advanced.md

限时免费促销（卖家速查规则）

对于已上架的付费市场服务，所有者可以开启免费时段（最长 90 天）。完整操作指南：references/selling.md → 限时免费促销。

Agent 必须：

1. 不要仅凭 UI 提示就盲目执行 PUT 来开启免费促销 — 先运行 P1–P5 自检。
2. 牢记，免费 = 钱包身份 + amount 为 0 的验证 + 不结算／扣款，并非匿名，也不是时段结束后仍可终身免费订阅。
3. 在平台网关上：内置了 amount 为 0 的挑战，以及跳过结算／扣款的逻辑。
4. 对于自定义上游密钥（P3/P4）或自建 x402：必须修改 ACL／强制设置 amount="0"／跳过结算 — 参见 selling.md 步骤 C。
5. 使用 x402 **resource（路径）**进行访问隔离 — 绝不要在传输数据中虚构 service_id。
6. 启用后：验证免费状态、402 的 amount 为 0、免费调用无需结算，然后确认取消／到期后付费路径恢复。

买家提示：如果未付款的 402 显示 accepts[].amount == "0"，请签署 0（无需 USDC）；免费期间不要强制按标价签名。

销售 — 服务变现（快速入门）

FAC=https://starchild-x402-facilitator.fly.dev
# pay_per_use: verify -> settle on EVERY request (simplest mode)
# --networks defaults to "all" (Base + Monad + Robinhood + X Layer + Solana mainnet); the 402 challenge
# returns a multi-accepts list — the buyer picks one chain per payment.
python3 skills/x402/scripts/monetize.py --name my-api --upstream-port 5173 \
    --mode pay_per_use --price 0.01 --facilitator $FAC

# lock to a single chain (custom)
python3 skills/x402/scripts/monetize.py --name my-api --upstream-port 5173 \
    --mode pay_per_use --price 0.01 --networks eip155:8453 --facilitator $FAC

平台模式遵循 community-gateway 计费契约：402 JSON 正文中的 accepts 为列表（支持多个 accepts，每个网络一个条目 — 买家每次付款选择一条链），accepts[].pricingModel，facilitator 是判断“是否已付款”的唯一可信来源，每次结算都会自动回调 community-gateway 以记录交易。

计费模式决策表

模式	层级	买家体验	适用场景
pay_per_use	平台级	每次请求都发送 X-PAYMENT，每次调用都结算	简单的数据端点、Agent 间的一次性调用
lifetime	平台级	一次付费，永久访问（由 facilitator 验证）	一次性解锁、买断定价
monthly	平台级	每个自然月付费一次	SaaS 式订阅
weekly / quarterly / yearly	平台级	固定时长通行证：从最近一次付款起有效 7 / 90 / 365 天	短期试用、年度折扣
prepaid	平台级	一笔链上存款 → 每次调用进行链下扣款	高频、单次费用低于 1 美分或按使用量计费的 API
payperuse	旧版	SDK V2 请求头，按请求付费	2.0 之前的部署
subscription	扩展	x402 充值 → API 密钥 + N 个额度，每次调用扣除 1 个额度	预付额度，避免每次调用的付款延迟
metered	扩展	类似订阅，按路由加权计量	混合了低成本和高成本端点的场景（例如 LLM 调用）
timepass	扩展	x402 付款 → API 密钥获得 N 天通行证	固定时长通行证（非自然月）

⚠️ lifetime/monthly/weekly/quarterly/yearly 必须使用 --facilitator-admin-token （启动时默认拒绝）。多计划：--plan MODE=PRICE（可重复指定）。 → 部署任何这些模式之前，必须先阅读 references/selling.md — 其中包含确切的命令、合约详情和模板列表。

输出包含 gateway_port。通过 preview 或社区发布时，应公开 GATEWAY 端口，而非上游端口。pay_to 默认为用户的 Privy EVM 钱包，收入会直接进入该钱包。 注册表：/data/workspace/.x402/services.json；每项服务的配置、日志和状态： /data/workspace/.x402/<name>/。

网络与 facilitator

该平台支持多条链。默认情况下，服务会使用平台主网完整集合（--networks all，默认值）——目前包括 Base + Monad + Robinhood + X Layer + Solana。402 挑战会返回一个包含多个 accepts 的列表（每条链对应一项）；买家每次付款选择一条链。使用 --networks eip155:8453,eip155:143,eip155:4663,eip155:196 锁定特定链（自定义）。

网络	CAIP-2	稳定币	EIP-712 名称	Gas
Base 主网	eip155:8453	USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	USD Coin	ETH（平台支付）
Base Sepolia（测试网）	eip155:84532	USDC 0x036CbD53842c5426634e7929541eC2318f3dCF7e	USDC	ETH（平台支付）
Monad 主网	eip155:143	USDC 0x754704bc059f8c67012fed69bc8a327a5aafb603	USDC	MON（平台支付）
Monad 测试网	eip155:10143	USDC 0x534b2f3A21130d7a60830c2Df862319e593943A3	USDC	MON（平台支付）
Robinhood 主网	eip155:4663	USDG 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168	Global Dollar	ETH（平台支付）
Robinhood 测试网	eip155:46630	USDG 0x7E955252E15c84f5768B83c41a71F9eba181802F	Global Dollar	ETH（平台支付）
X Layer 主网	eip155:196	USDC 0x74b7F16337b8972027F6196A17a631aC6dE26d22	USD Coin	OKB（平台支付）
X Layer 测试网	eip155:1952	USDC 0x74b7F16337b8972027F6196A17a631aC6dE26d22	USD Coin	OKB（平台支付）

Facilitator	网络	使用场景
platform（https://starchild-x402-facilitator.fly.dev，主网默认值；通过 X402_FACILITATOR_URL 或 --facilitator 覆盖）	Base + Monad + Robinhood + X Layer + Solana 主网	生产环境——平台结算方在每条链上支付 Gas
https://x402.org/facilitator（测试网默认值）	Base Sepolia + Monad + Robinhood + X Layer 测试网	仅供测试——主网会拒绝使用（启动检查）

平台 facilitator 会在所有受支持的链上处理 /verify + /settle；其结算方密钥仅用于支付 Gas——资金流由买家的签名固定，绝不会触及用户资金。**所有链上的 Gas/费用均由平台支付（Base 上为 ETH、Monad 上为 MON、Robinhood 上为 ETH、X Layer 上为 OKB、Solana 上为 SOL）——绝不会转嫁给服务提供商。**安全措施：花费 Gas 前必须进行 eth_call 模拟、按付款方进行速率限制、授权 nonce 幂等性。 测试网 USDC（Base Sepolia）：0x036CbD53842c5426634e7929541eC2318f3dCF7e，水龙头位于 faucet.circle.com。价格会自动换算：$0.01 → 10000 个 USDC 原子单位。

多链配置（networks_mode）

配置	行为
--networks all（默认值）或 networks_mode: all	402 accepts = 平台主网完整集合（Base + Monad + Robinhood + X Layer + Solana）；当 facilitator 为 x402.org 时，则为测试网完整集合
--networks eip155:8453 或 networks_mode: custom + networks: [...]	402 accepts = 列出的链（自定义锁定），不多不少
（无 networks 字段）	与 all 相同

要通过新增链扩展平台，只需更新 platform_modes.py 中的 ASSETS + MAINNET_NETWORKS（以及 facilitator 的 KNOWN_ASSETS） ——每个配置为 all 的服务都会在下一次 402 时自动采用新链，无需更新任何业务表。

⚠️ Robinhood USDG 注意事项：USDG 合约使用了非标准 EIP-712 域的 Diamond 代理。facilitator 会从链上读取 DOMAIN_SEPARATOR() 以进行验证。买家端原始摘要签名仍待实现（参见 client.py 中的 _CHAIN_DOMAIN_SEP_CHAIN_IDS）；目前使用标准的类型化数据签名，若链上域与元数据相符，该方式即可正常工作。

历史上的仅 Base 配置会迁移一次（通过 SQL/配置扫描将其设为 networks_mode: all）；resolve_networks 不会将“裸 Base”猜测为“全部”。

Keepalive（每台机器只注册一次）

一个 watchdog 守护所有 x402 网关（cloudflare-skill 模式：幂等， 仅在状态变化时输出 → 状态正常时计划任务静默运行）：

1. 启动时：将以下内容追加到 /data/workspace/setup.sh： bash /data/workspace/skills/x402/scripts/keepalive.sh || true
2. Watchdog：scheduled_task(action="schedule", schedule="every 10 minutes", command="bash skills/x402/scripts/keepalive.sh", deliver="origin") — 无输出 = 静默。 ⚠️ 使用相对路径（skills/x402/...），绝不要使用 /data/workspace/skills/... — 调度器的路径清理器会从绝对命令中移除 workspace/，将其篡改为不存在的 /data/skills/...，导致任务每次运行都失败。注册后， 使用 get_log 验证首次执行成功。

网关宕机 → 根据其配置重启。上游宕机 → 报告，但不重启（上游通过预览环境有自己的 supervisor — 不要干预）。

已上架的付费服务必须保持 24/7 可访问（空闲时挂起 + 自动更新重启会影响这一点）→ 发布前阅读 references/selling.md § 始终在线的可用性，了解更新模式的检查／切换流程。

购买 — 支付其他 Agent 的 x402 服务

快速入门 — 预设 CLI 脚本（优先使用这些，无需自定义代码）

每个步骤运行一个进程，stdout 仅输出一个 JSON 对象 — 无需逐次调用 LLM 推理余额／签名／支付通道选择：

# 1. FREE probe: is it x402? which rails? (never pays)
python3 skills/x402/scripts/discover.py --url https://host/api/thing
python3 skills/x402/scripts/discover.py --query "weather api"   # catalog search

# 2. Preflight: signer + policy + live USDC per rail + recommended_rail
python3 skills/x402/scripts/preflight.py --usd 0.05

# 3. Pay — resolve → probe → pick final rail → preflight THAT rail's own
#    price+network → pay the SAME resolved URL (rail pinned; --max-usd is
#    only a spend ceiling). Exit 2 = blocked/over-cap/network-not-accepted,
#    nothing signed. --network not in accepts fails fast (no silent fallback).
python3 skills/x402/scripts/buy.py --url https://host/api/thing --max-usd 0.05
python3 skills/x402/scripts/buy.py --url https://host/x402/q \
    --json '{"q":"hello"}' --max-usd 0.10 --network eip155:8453

原始客户端（高级／自定义流程）：

python3 skills/x402/client.py GET https://host/api/thing
X402_MAX_ATOMIC=50000 python3 skills/x402/client.py POST https://host/x402/topup

首先进行预检（一次往返，不要逐项排查）

在询问用户是否确认购买前，运行 client.payment_preflight(amount_atomic, networks=<the 402's accept networks>)，并一次性列出所有阻碍项。它会一次检查： ① 签名者是否可访问；② 钱包策略是否正常 — 已启用但规则为空的策略会拒绝所有请求，并拒绝每个签名（新的 Privy 钱包应为允许所有请求；如果发现此情况，提出策略卡片并在付款前让用户签名）；③ 每个候选支付通道上的 USDC 余额（直接 RPC）。如果没有任何支付通道有资金，则一次性提供所有选项 — 从其他已充值的链付款、跨链桥接或法币入金 — 绝不要只说“给钱包充值”，导致用户之后又遇到新的阻碍。不要让用户先解决资金问题，然后在另外两次往返中才发现策略阻止和依赖项错误。

依赖项：买家路径需要 web3>=7。如果机器固定使用较旧的 web3（交易机器人通常固定使用 6.x），绝不要全局升级 — 运行 bash skills/x402/scripts/ensure_env.sh（无需交互，且幂等）：它会创建一个独立的 .venv-x402，不受 PIP_USER／PYTHONPATH／用户站点干扰（虚拟环境使用 --without-pip 构建，并设置 PYTHONNOUSERSITE=1），最后一行 stdout 会输出要使用的解释器。payment_preflight 会检测版本冲突并指向此脚本。请在设置时完成，而不是在购买过程中处理。

多链选择（买家收到多个接受的网络）

当服务返回的 402 中，accepts 是一个列表（每个网络一项，例如 Base + Monad + Robinhood + X Layer + Solana）时，买家 Agent 无需询问用户要使用哪条链 — paid_request 和 bazaar_pay 都会全自动选择链。逻辑如下：

1. payment_preflight（确认前运行）：检查每个候选支付通道上的 USDC 余额，并返回 funded_rails[]。如果多个支付通道有资金，自动选择器会选出最佳通道。如果没有任何支付通道有资金，则一次性列出所有充值选项（跨链桥接、法币入金、从其他链付款）— 绝不要在答案是“都没有”时询问“用哪条链？”。

2. 自动排序支付通道 — 考虑余额，默认使用 Base（bazaar.probe_402 显示和 paid_request 支付共用，因此探测时显示的链就是实际支付所用的链）。选择顺序：

   • ① 优先选择余额充足的支付通道：该支付通道上的实时 USDC 余额 ≥ 支付金额（直接通过 RPC 查询，缓存约 60 秒）。因此，签名友好的链即使没有 USDC，也不会优先于余额充足的链，从而避免因所选支付通道余额不足而导致结算失败。
   • ② 余额相同时默认使用 Base（eip155:8453）（平台钱包在 Base 上持有 USDC）。
   • ③ 静态次级排序（network_rank）：Base（主要的 USDC 链）→ Solana／其他未使用 EIP-7702 委托的 EVM 链（普通 ECDSA，例如 Monad）→ 使用委托代码的 EVM 链（Kernel EIP-1271）。signer_mode="eoa"：排除 Solana，所有 EVM 链优先级相同。
   • ④ 同一排序等级内，优先选择金额较低的项／最先接受的项。
   • 余额检查失败 = 未知，而非余额不足（失败时仍按排序选择）。

3. 用户指定链（prefer_network）：用户明确要求在特定链上支付时（例如“在 Base 上支付”“使用 Monad”），向 paid_request 或 bazaar_pay 传入 prefer_network="eip155:8453"（或 Monad 对应的 "eip155:143"）。这会覆盖自动排序，并优先选择匹配的 accept（如果 402 挑战中存在）。也可通过环境变量 X402_PREFER_NETWORK 使用。如果指定的链不在服务的 accepts 中，则回退到自动排序。常见的 CAIP-2 ID：Base eip155:8453、Monad eip155:143、Solana solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp。

   # User says "pay on Base"
   paid_request("GET", url, prefer_network="eip155:8453")
   # User says "pay on Monad"
   bazaar_pay(url, prefer_network="eip155:143")
   # User says "pay on Solana" / "use Solana"
   paid_request("GET", url, prefer_network="solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp")
   # Via env (CLI)
   X402_PREFER_NETWORK=eip155:8453 python3 skills/x402/client.py GET https://host/api
   

4. 预付押金重试：如果首次支付触发 402 insufficient_balance（需要预付充值），重试仍使用买家已选择的同一条链（_pick_accept 中的 prefer_network 参数）——流程中不会跳转到其他链。

5. 结果验证：每个 paid_request 结果都包含 network（实际使用的链）和 signer_type——务必将这些信息告知用户，让他们知道付款最终落在哪条链上。

paid_request 会自动检测两种 402 格式：V2 标头挑战（PAYMENT-REQUIRED → x402 SDK 路径）和平台 JSON 正文挑战（accepts.pricingModel → 手动签署 EIP-3009 → 使用 X-PAYMENT 重试）。 对于终身／按月服务，付费周期内重复调用只会验证，不会结算——结果中 paid: true，且不会产生新的链上交易。 买方签名者默认是 Privy 钱包（signer_mode="auto"）；系统会自动检测智能账户，并通过兼容 ERC-1271 的路径进行签名。多接受路由优先选择 Privy 使用普通签名的支付通道（最大限度兼容 facilitator，无需为 EOA 充值）： ① Base（主要的 USDC 链）→ ② Solana / 付款方没有 EIP-7702 代码的 EVM 链（普通 ECDSA，例如 Monad）→ ③ 带有委托代码的 EVM 链（Kernel EIP-1271，例如 Base），作为最后选择——符合规范，但部分卖家 facilitator 会拒绝；对于这类卖家仅支持 Base 的情况，请使用 signer_mode="eoa"。请勿撤销钱包的委托（它用于支持 Gas 赞助）。auto 为失败时关闭模式：如果 Privy 签名者无法初始化，paid_request 会报错，而不是改用其他身份付款——仅可通过显式设置 allow_fallback_eoa=True / 环境变量 X402_FALLBACK_EOA=1 / signer_mode="eoa" 来允许回退到 session-EOA。每个结果都包含 signer_type（"privy" | "session_eoa"）；选择加入回退时还会设置 signer_warning——请检查这些字段，以确认实际付款的身份。⚠️ 两个签名者对应不同的付款方身份： 订阅 / 预付余额不会在两者之间转移。同样，EVM 和 Solana 的预付余额彼此独立（pay_to 地址不同）——Solana 上的存款不能用于 EVM，反之亦然。网关会在显示时合计两种余额，但会从存款所在的链扣款。 → EOA 充值步骤和签名者内部机制：使用 session EOA 前，请阅读 references/buying-advanced.md。

支出保护：拒绝签署超过 X402_MAX_ATOMIC 的金额（默认值为 1_000_000 = 1 USDC）。⚠️ 签名 = 结算后实际支出资金——向用户确认后，才能向不熟悉的服务付款或提高上限。已付款的响应正文会完整返回；未付款 / 错误响应正文最多返回 2000 个字符（环境变量 X402_BODY_MAX，0 = 不限）。结果包含 settlement.transaction（链上交易哈希）——请报告该值，并按照交易验证规则进行验证。

支付账本（记录每笔本地支付）

client.py 会将其签署的每笔付款追加到 $WORKSPACE/.x402/payments.jsonl（可通过环境变量 X402_LEDGER 覆盖路径）。每 行是一条 JSON 事件：signed（已提交授权——url、amount、payTo、payer、caller）和 result（HTTP 状态码、是否已付款、结算交易）。caller 字段用于标识付款者（SC_CALLER_ID / JOB_ID / pid），因此也能追溯后台会话发起的付款。

若要回答“这笔 USDC 去了哪里”：先读取账本，再与钱包链上的 USDC 转账记录核对——每笔转出都必须对应一条账本记录。账本写入尽力而为，绝不会阻塞付款。

自动化会话的支出规则

• 后台 / 计划任务 / 派生会话除非任务明确授予预算，否则不得进行 x402 付款；请将 X402_MAX_ATOMIC 设置为该会话的 预算。
• 自动化会话进行的每笔付款都必须出现在最终输出中 （金额、url、结算交易）——仅记录在账本中的付款虽然可审计，但仍属于未报告的工作。
• 任何 4xx 付款拒绝都不得使用新的付款重试：每次 重试都可能再次产生支出。请先排查原因。

公共付费 URL（与 Cloudflare Monetization Gateway 能力一致）

将任意本地服务变成公共付费 API（任何调用方都可为任何资源付费，无需账户 / API 密钥——具备与 Cloudflare Monetization Gateway 相同的功能，并运行在你自己的机器上）：

1. python3 skills/x402/scripts/make_public.py --name my-api --upstream-port <port> --mode payperuse --route 'GET /api/*=$0.01' --pay-to <wallet> — 创建 output/my-api/start.py + 配置（默认使用 --networks all：Base + Monad + Robinhood + X Layer + Solana）
2. preview(action='serve', dir='output/my-api', command='python3 start.py', port=<gateway_port>) — 注意：如果上游服务尚未运行，请在同一条命令中启动它
3. community-publish 技能 → publish_preview(preview_id, slug='my-api') → 公共 URL
4. 内置价格查询：GET <public-url>/.well-known/x402 会返回机器可读的路由 / 价格 / payTo / networks（兼容 Bazaar 的格式；accepts 是多链列表）。

公共 URL 不等于市场列表。 步骤 1–4 只能让服务可访问——完成 LIST 流程（community-publish 技能）之前，服务市场不会显示任何内容（或显示“免费”）：

5. create_paid_service(name=..., service_type=..., api_endpoint=<public paid route>, provider_wallet=..., pricing_model=..., price=..., pricing_options=[...] for multi-plan) → 服务记录。
6. publish_service(service_id) → 发布付费列表。审核仅供参考： 可以选择运行 submit_for_review(service_id) + get_review_status() 进行 5 项自查（402 可访问、价格一致、x402 有效、响应匹配、文档完整）——将结果展示给所有者；审核不会阻止发布。

⚠️ LIST 流程必须通过 community-publish 技能函数完成——绝不要手动构建网关负载。create_paid_service() 会要求所有付费字段都必须提供；缺少字段的手动构建负载会被网关拒绝（而旧版网关会静默创建免费服务，导致后续审核失败，并返回误导性的 400）。

跳过步骤 5–6 是“为什么我的付费服务显示为免费 / 没有出现在市场中”的首要原因。

付费项目：两种形式

付费项目是一个需要付费才能访问的 Starchild 项目。它有两种形式——平台同时支持这两种形式，且两者共用相同的 service_type="paid_project" + project_slug 列表结构：

形式 1：整个页面置于付费墙之后（用户实现访问控制）

访问页面本身需要付费。用户（服务提供方）自行实现访问控制——例如登录组件，在提供内容前验证付款凭据。

平台职责： 发布项目，并在市场中列出付费 API 端点。x402 网关负责处理支付协议（402 挑战 → 结算 → 凭据）。

用户职责： 在自己的应用中实现访问控制拦截器：

• 前端的付费墙 / 登录组件（输入凭据 → localStorage）
• 用于验证凭据并返回内容的后端端点
• x402 支付成功后，由用户自己的 API 签发凭据——用户的 API 将凭据返回给买家

流程：

1. Visitor opens the page → sees a paywall (user's frontend code)
2. Visitor pays via x402 (Agent or direct) → user's API returns a credential
3. Visitor enters the credential → user's backend validates it → serves content
4. Credential cached in localStorage → subsequent visits skip the paywall

平台提供的内容：

• x402 网关：处理 402 付款挑战和链上结算
• /x402/topup 端点：买家付款后获得 API 密钥（timepass / 订阅模式），或者 x402 签名本身就是凭据（平台模式）
• /x402/balance 端点：用户的应用可以使用该端点检查 API 密钥是否有效（可选——用户也可以自行实现验证）

用户需要实现的内容（自己的代码，自己的逻辑）：

• 前端：付费墙界面、凭据输入、localStorage 缓存
• 后端：凭据验证（可以调用网关的 /x402/balance，自行实现验证逻辑，或直接使用 x402 签名）
• 付费墙页面上关于“如何付款”的说明

“如何使用 Agent 付款”文档

用户的付费墙页面应包含“如何付款”部分，说明买家如何通过 x402 付款获取访问凭证。Agent 应根据服务的实际价格、时长和 URL 生成此文档，不要照搬固定模板。文档应涵盖：

• 价格和支付网络（例如：“$2.99 USDC/USDG，支持 Base、Monad 或 Robinhood——买家每次付款选择一条链”）
• 如何通过 Agent 付款（调用 /x402/topup 的 x402 客户端）
• 如何直接付款（使用任何兼容 x402 的客户端，并携带 X-PAYMENT 标头）
• 买家付款后会收到什么（api_key 凭证）

表单 2：免费页面 + 付费 API（流程 D）

页面可免费浏览（介绍／文档／落地页），但 API 调用需要付费。这是流程 D——详情请参阅 community-publish 技能。上游应用在 / 提供免费介绍页面，在 /api/* 提供付费 API。

总结：付费项目 = 免费项目 + 付费 API（相同模式）

两种形式都使用 service_type="paid_project" + project_slug。区别仅在于用户需要实现的内容：

形式	页面访问	API 访问	用户需要实现
整个页面付费	付费墙（用户的访问控制）	通过 x402 付费	付费墙 UI + 凭证验证
免费页面 + 付费 API	免费（介绍／文档页面）	通过 x402 付费	无需额外实现（由网关处理）

在这两种情况下，平台（x402 网关 + community-gateway）都会处理支付协议和市场上架。用户只需为表单 1 实现访问控制拦截器。

仅凭 URL 使用任意 x402 服务

只需提供服务 URL（无需文档或说明），即可按以下流程完成接入和验证——协议会自描述所有所需信息：

1. 发现（无需付款）：不带付款标头，对 GET <url> 发起请求。402 响应就是价格表：accepts 是一个列表（支持多种接受方式，每个网络对应一项）——每项都包含 amount（USDC 最小单位）、pricingModel、network、asset、payTo。选择一条链进行付款。对于支持多种方案的服务，plans 映射会包含每个选项的 accepts。也可以选择对 GET <base>/.well-known/x402 发起请求，获取机器可读的路由、价格和网络索引。
   • 如果 amount == "0"（或市场的免费状态已启用），则服务正处于限时免费促销：签署金额 0 的请求以验证身份；预计不会发生结算。这是临时状态——free_end 过后，同一 URL 会再次返回原价。
2. 探测方案（无需付款，仅适用于多方案服务）：带上 X-Pricing-Model: <plan> 重复发送未付款的 GET 请求——每个 402 响应都会给出该方案的确切金额。未知方案会返回 HTTP 400，并列出有效方案。
3. 付款并调用：client.paid_request("GET", url, max_amount_atomic=<cap>) 会处理完整流程（402 → EIP-3009 签名 → 携带 X-PAYMENT 重试）。使用 pricing_model="<plan>" 选择方案。默认付款方是 Privy 钱包（signer_mode="auto"）。对于付费报价，钱包必须在服务所在的网络上持有 USDC；对于免费促销金额 0，只需有一个签名钱包（无需持有原价所需的 USDC）。只有在指定 signer_mode="eoa" 或结果报告 signer_type: "session_eoa" 时，会话 EOA 才需要注资（见上文买方部分）。cap 是你的支出上限（免费期间可以是 0）。实际付款前请先征得用户确认。检查结果中的 signer_type：它会告知你实际付款的身份。如果 Privy 签名者不可用，auto 会报错（失败关闭），而不会悄悄改用会话 EOA 付款；只有在明确允许回退时才会出现 signer_warning。
4. 验证计费语义（订阅模式）：再次调用——结果必须为 200，且不能有新的结算（paid: true，无新交易）。对于支持多种方案的服务，持有一个方案时请求不同方案也不得再次扣费。第 3 步中的 settlement.transaction 是链上凭证——请提供该凭证，并按照交易验证规则进行验证。免费促销期间，第 3 步首次访问也不应产生新的结算。

同一流程也可作为任意 x402 部署的冒烟测试：第 1–2 步免费，并验证质询约定；第 3–4 步则验证结算和访问计费的端到端流程。

发现并支付——先 marketplace，再 CDP

买家流程以 marketplace 优先。不要合并不同流程；不要抓取第三方 x402 目录。

步骤	规则
1. 查找	优先使用 discover_services(query) 或 community-publish.explore_marketplace。marketplace 没有匹配项时，再使用 CDP（bazaar_search）作为后备方案。
2. 解析支付 URL	已上架的服务 → community.iamstarchild.com/proxy/{service_id}（+ 路径）或内部 /{user}-{slug}/...。存在代理时，绝不要向列表中的外部原始 URL 付款。
3. 支付	bazaar_pay(url) 会重新解析为 marketplace 代理，然后执行 probe_402 → paid_request。Community 会 透明代理 并在 HTTP 200 时 记账。未上架的外部 URL 会被 拒绝——先在 marketplace 上架该服务，再向其代理 URL 付款。

import sys; sys.path.insert(0, "/data/workspace/skills/x402")
from bazaar import discover_services, resolve_marketplace, probe_402, bazaar_pay

discover_services("weather", limit=5)          # marketplace first, CDP fallback
resolve_marketplace("https://example.com/api") # → pay_url via community when listed
bazaar_pay(url, max_usd=0.01)                  # proxy-first pay; refuse non-standard

probe_402 / bazaar_pay 只会在已知的原生 USDC 轨道上支付 standard-v2 精确匹配项（参见 bazaar.PAYABLE_USDC）：Base、Polygon、Arbitrum、World Chain、Solana 主网、Monad、Avalanche、Ethereum、Optimism、Linea、Celo、Unichain。支持多种接受方式时 → 优先选择 Privy 原生轨道（Base → Solana/无代码 EVM → 委托 EVM；参见买家签名器部分）。相同的选择器（client.network_rank）会决定 bazaar 的 probe_402 排序，因此探测时显示的轨道，就是 auto 实际付款所用的轨道。signer_mode="eoa" 不会注册 SVM 签名器，并会硬性过滤 Solana 接受项——绝不会替换固定的会话 EOA 付款方身份。结果和账本条目会记录实际选定的 network/payer/signer_type（Solana 结算会报告 Privy Solana 地址作为付款方）。Solana 通过 Privy wallet_sol_sign（base64 原始消息）签名。暂不支持：EURC/其他稳定币、测试网。其他类型（wrong-rail、tx-hash、non-standard、no-payment）会在任何签名前被拒绝。买家签名；卖家由 facilitator 结算。

错误与诊断

支付或网关失败 → 必须阅读 references/troubleshooting.md（错误约定、facilitator 验证错误、安全模型、端口归属检查、代理配置）。可随时进行快速端到端检查： python3 skills/x402/scripts/verify_setup.py（无需资金；--funded 会添加真实结算测试）。

设置

Python SDK 版本为 x402 v2.10+。依赖项不会自动安装：每台机器运行一次 bash skills/x402/setup.sh（同时将其追加到 /data/workspace/setup.sh，以便重启时重新安装）。