hedera-dev/hedera-skills

x402-payments

x402 pay-per-use payments on Hedera.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/hedera-dev/hedera-skills --skill x402-payments

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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

Related by task

from this repository

More skills

All 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.

1h installs
3
GitHub stars
28
Updated
Sep 3
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).

1h installs
3
GitHub stars
28
Updated
Sep 3
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.

1h installs
3
GitHub stars
28
Updated
Sep 3
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).

1h installs
3
GitHub stars
28
Updated
Sep 3