x402-payments

x402 付款（Hedera）

按使用量付费模式：将受保护的字节存储在链下，单独记录访问条款（链上或配置中），并通过 HTTP 402 和可自托管的 Hedera 协调器保护 HTTP 资源；该协调器负责验证和结算原生 HBAR 转账。

Buyer → GET protected resource
          ├─ free / public → resource
          └─ paid → 402 PAYMENT-REQUIRED
                → client signs HBAR transfer
                → retry with PAYMENT-SIGNATURE
                → resource server verify + settle via facilitator
                → PAYMENT-RESPONSE + resource

资源服务绝不持有协调器密钥。结算使用协调器进程中已注资的 ECDSA 费用付款账户。

快速参考

组成部分	作用
付款资产	"0.0.0" — 原生 HBAR；金额以 tinybar 计（1 HBAR = 1e8）
资源服务	@x402/core + ExactHederaScheme → 通过 HTTP 与协调器通信
协调器	GET /supported、POST /verify、POST /settle、GET /health
客户端	请求 → 读取 402 → 签名 → 使用 PAYMENT-SIGNATURE 重试（也接受旧版 X-PAYMENT）
钱包	ECDSA Hedera 账户（例如通过 WalletConnect / UniversalProvider 使用 HashPack）

服务器/客户端代码片段见 references/examples.md。环境变量和结算语义见 references/facilitator.md。

重要：协调器费用付款方

Hedera x402 使用原生 TransferTransaction 进行结算。买方进行部分签名（授权买方向卖方付款）。协调器必须：

1. 根据付款要求验证已签名的载荷
2. 作为公布的费用付款方（/supported）共同签名
3. 支付网络费用并提交交易，直到状态为 SUCCESS

需要在已注资的 ECDSA 账户上设置 FACILITATOR_ACCOUNT_ID + FACILITATOR_PRIVATE_KEY——该账户应与部署者/卖方密钥分开。不要将此密钥放入资源服务进程中。

重要：价格以 tinybar 计

付款要求使用 tinybar。在 UI 中使用 8 位小数的辅助函数进行转换；切勿使用浮点数。

const TINYBAR_PER_HBAR = 100_000_000n;
// hbar "1.5" → 150_000_000n tinybars

资源服务流程（付费资源）

1. 加载资源的访问条款——如果缺失 → 404
2. 如果免费/公开 → 返回资源
3. 否则构建付款要求：payTo = 卖方 Hedera 账户 ID，amount 以 tinybar 计，资产为 0.0.0，网络（例如 hedera:testnet）
4. 没有付款标头 → 返回带有 PAYMENT-REQUIRED 标头和 JSON 正文的 402
5. 有付款标头 → 执行 verifyPayment，然后执行 settlePayment；仅在成功后返回资源和 PAYMENT-RESPONSE

const facilitator = new HTTPFacilitatorClient({ url: FACILITATOR_URL });
const server = new x402ResourceServer(facilitator)
  .register(X402_NETWORK, new ExactHederaScheme());
await server.initialize(); // pulls fee-payer from /supported

客户端流程

const first = await fetch(resourceUrl);
if (first.status === 402) {
  const paymentRequired = httpClient.getPaymentRequiredResponse(...);
  const payload = await httpClient.createPaymentPayload(paymentRequired);
  const headers = httpClient.encodePaymentSignatureHeader(payload);
  const paid = await fetch(resourceUrl, { headers });
  // processResponse → resource + settle receipt
}

机器对机器客户端使用基于密钥的签名器，而不是浏览器钱包。

检查清单

• 资源服务没有协调器私钥
• 客户端和服务器使用相同的 X402_NETWORK（例如 hedera:testnet）
• 金额以 tinybar 计；资产 ID 为 0.0.0
• 402 挑战 → 签名后重试 → 验证 → 结算 → 仅在成功后返回资源
• 费用付款账户为 ECDSA 账户，且已注资以支付网络费用
• 测试付费请求前，确认协调器 /health 正常
• payTo 是 Hedera 账户 ID 字符串（例如 0.0.1234），而非 EVM 地址

参考资料

• references/examples.md — 资源服务接线配置、客户端重试循环、tinybar 辅助函数
• references/facilitator.md — 端点、环境变量、费用付款方角色
• x402 文档
• @x402/hedera