用途:为 HTTP 资源提供按次付费(pay-per-use)门禁,受保护内容存放在链下,访问条款单独记录(链上或配置),通过 HTTP 402 与自托管 Hedera facilitator 验证、结算原生 HBAR 转账。
主要能力:资源服务器使用 @x402/core 与 ExactHederaScheme,通过 HTTP 与 facilitator 通信;facilitator 提供 GET /supported、POST /verify、POST /settle、GET /health;客户端收到 402 后签名 HBAR 转账并携带 PAYMENT-SIGNATURE(旧版 X-PAYMENT 亦接受)重试;支付资产为原生 HBAR("0.0.0"),金额以 tinybar 表示(1 HBAR = 1e8)。
流程:资源服务器加载访问条款(缺失则 404)→ 免费/公开直接返回 → 否则构造支付要求(payTo 为卖家 Hedera 账户 id、金额 tinybar、资产 0.0.0、network 如 hedera:testnet)→ 无支付头返回 402 与 PAYMENT-REQUIRED → 带支付头则 verifyPayment 后 settlePayment,仅成功才返回资源与 PAYMENT-RESPONSE。客户端先 fetch,遇 402 读取支付要求、创建支付载荷、编码签名头后重试;机器间可用基于密钥的签名器替代浏览器钱包。
限制与注意:facilitator 费用支付方须使用已充值的 ECDSA 账户(FACILITATOR_ACCOUNT_ID、FACILITATOR_PRIVATE_KEY),与部署者/卖家密钥分离,且不得放入资源服务器进程;资源服务器不持有 facilitator 密钥。金额必须用 tinybar 且避免浮点,可用 8 位小数辅助;payTo 是 Hedera 账户 id 字符串而非 EVM 地址;客户端与服务器需共用同一 X402_NETWORK。测试付费请求前先确认 facilitator /health 正常。更多片段见 references/examples.md 与 references/facilitator.md,另可参考 x402 文档与 @x402/hedera。