hedera-dev/hedera-skills

x402-payments

x402 pay-per-use payments on Hedera.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/hedera-dev/hedera-skills --skill x402-payments

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

x402 Payments (Hedera)

Pay-per-use pattern: store protected bytes off-chain, record access terms separately (on-chain or config), gate HTTP resources with HTTP 402 + a self-hosted Hedera facilitator that verifies and settles native HBAR transfers.

text
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

The resource server never holds facilitator keys. Settlement uses a funded ECDSA fee-payer account on the facilitator process.

Quick Reference

PieceRole
Payment asset"0.0.0" — native HBAR; amounts in tinybars (1 HBAR = 1e8)
Resource server@x402/core + ExactHederaScheme → talks to facilitator over HTTP
FacilitatorGET /supported, POST /verify, POST /settle, GET /health
ClientRequest → read 402 → sign → retry with PAYMENT-SIGNATURE (legacy X-PAYMENT also accepted)
WalletECDSA Hedera account (e.g. HashPack via WalletConnect / UniversalProvider)

See references/examples.md for server/client snippets. See references/facilitator.md for env vars and settle semantics.

Critical: Facilitator Fee Payer

Hedera x402 settles with native TransferTransactions. The buyer partially signs (authorize buyer → seller). The facilitator must:

  1. Verify the signed payload against payment requirements
  2. Co-sign as the advertised fee payer (/supported)
  3. Pay network fees and submit until SUCCESS

Requires FACILITATOR_ACCOUNT_ID + FACILITATOR_PRIVATE_KEY on a funded ECDSA account — separate from deployer/seller keys. Do not put that key in the resource-server process.

Critical: Prices Are Tinybars

Payment requirements use tinybars. Convert in UIs with 8-decimal helpers; never float.

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

Resource Server Flow (paid resource)

  1. Load access terms for the resource — if missing → 404
  2. If free/public → return the resource
  3. Else build payment requirements: payTo = seller Hedera account id, amount in tinybars, asset 0.0.0, network (e.g. hedera:testnet)
  4. No payment header → 402 with PAYMENT-REQUIRED header + JSON body
  5. With payment header → verifyPayment then settlePayment; only on success return resource + PAYMENT-RESPONSE
ts
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

Client Flow

ts
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
}

Machine-to-machine clients use a key-based signer instead of a browser wallet.

Checklist

  • [ ] Resource server has no facilitator private key
  • [ ] Client and server share the same X402_NETWORK (e.g. hedera:testnet)
  • [ ] Amounts are tinybars; asset id is 0.0.0
  • [ ] 402 challenge → signed retry → verify → settle → resource only after success
  • [ ] Fee-payer account is ECDSA and funded for network fees
  • [ ] Facilitator /health OK before testing paid requests
  • [ ] payTo is a Hedera account id string (e.g. 0.0.1234), not an EVM address

References

Verwandte Aufgaben

aus demselben Repository

Weitere Skills

Alle Skills
hedera-dev
Community

agent-kit-plugin

This skill should be used when the user asks to "create a hedera plugin", "build a hedera agent kit plugin", "extend hedera agent kit", "create custom hedera tools", "add hedera functionality", "write a hedera tool", "implement hedera tool", or needs guidance on Hedera Agent Kit plugin architecture, tool definitions, mutation tools, query tools, or parameter schemas using Zod.

Installationen / 1h
3
GitHub Stars
28
Aktualisiert
3. Sept.
hedera-dev
Community

axelar-gmp

Axelar General Message Passing (GMP) on Hedera. Use when sending or receiving cross-chain contract calls via Axelar Gateway (callContract, payNativeGasForContractCall), building AxelarExecutable receivers, wiring Hedera↔EVM destinations, or separating bridge transport from destination handlers (orchestrated / scheduled flows).

Installationen / 1h
3
GitHub Stars
28
Aktualisiert
3. Sept.
hedera-dev
Community

ccip

Chainlink CCIP Cross-Chain Tokens on Hedera. Use when bridging burn-and-mint CCT between Hedera and EVM, registering TokenAdminRegistry / pools, calling ccipSend with chain selectors, or wiring HTS-backed wrappers (HtsBurnMintERC20) vs vanilla BurnMintERC20. Not for Chainlink Data Feeds / price oracles.

Installationen / 1h
3
GitHub Stars
28
Aktualisiert
3. Sept.
hedera-dev
Community

chainlink-data-feeds

Chainlink Data Feeds on Hedera. Use when reading AggregatorV3 price feeds on Hedera (testnet 296 / mainnet 295), calling latestRoundData, checking round completeness and staleness, or normalizing feed decimals. Not for Chainlink CCIP (cross-chain tokens).

Installationen / 1h
3
GitHub Stars
28
Aktualisiert
3. Sept.