x402-payments

x402 Payments (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。金額はtinybars（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 が必要です。これはデプロイヤー／販売者のキーとは別に用意します。このキーをリソースサーバーのプロセスに設定しないでください。

重要：価格は tinybars 単位です

決済要件では tinybars を使用します。UI で変換する際は小数点以下 8 桁に対応したヘルパーを使い、浮動小数点数は使用しないでください。

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

リソースサーバーのフロー（有料リソース）

1. リソースのアクセス条件を読み込みます。存在しない場合は 404 を返します
2. 無料／公開の場合はリソースを返します
3. それ以外の場合は決済要件を作成します。payTo = 販売者の Hedera アカウント ID、amount = tinybars 単位の金額、資産 = 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）を使用している
• 金額は tinybars 単位で、資産 ID は 0.0.0
• 402 チャレンジ → 署名付き再試行 → 検証 → 決済 → 成功後にのみリソースを返す
• 手数料支払者アカウントは ECDSA で、ネットワーク手数料を支払える資金がある
• 有料リクエストのテスト前に、ファシリテーターの /health が OK である
• payTo は Hedera アカウント ID の文字列（例：0.0.1234）であり、EVM アドレスではない

参考資料

• references/examples.md — リソースサーバーの設定、クライアントの再試行ループ、tinybar ヘルパー
• references/facilitator.md — エンドポイント、環境変数、手数料支払者の役割
• x402 docs
• @x402/hedera