docs

Integrating

hbar402 is an ordinary HTTP API that answers 402 Payment Required until you pay. Any x402 v2 client with the Hedera scheme registered can buy from it. There is no signup, no API key and no minimum spend.

Get a funded Hedera testnet account

Create one at portal.hedera.com and claim testnet HBAR. Either key type works for paying — ED25519 keys come DER-encoded, ECDSA keys as raw hex.

For USDC, use the Circle faucet and select Hedera Testnet. Paste your account id (0.0.x), not the EVM address. If your account has unlimited automatic token associations you do not need a separate TokenAssociateTransaction.

You do not need HBAR for gas to buy. Under the Hedera exact scheme the facilitator is the fee payer and submits the transaction, so you are debited exactly the quoted price. You only need a balance of the asset you are paying in.

Install

pnpm add @x402/core @x402/fetch @x402/hedera

Build a paying fetch

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactHederaScheme } from "@x402/hedera/exact/client";
import { createClientHederaSigner, PrivateKey } from "@x402/hedera";

// Import PrivateKey from @x402/hedera, not @hiero-ledger/sdk. The SDK relies on
// internal instanceof checks and two copies on disk fail at runtime with
// "t.startsWith is not a function".
const signer = createClientHederaSigner(
  "0.0.1234",
  PrivateKey.fromStringDer(process.env.HEDERA_PRIVATE_KEY!),
  { network: "hedera:testnet" },
);

const payingFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "hedera:testnet", client: new ExactHederaScheme(signer) }],

  // Optional. hbar402 offers HBAR, USDC and H402 in one 402; without a selector
  // the client takes the first option.
  paymentRequirementsSelector: (_v, reqs) =>
    reqs.find((r) => r.asset === "0.0.0") ?? reqs[0],
});

const res = await payingFetch("https://hbar402.okeyamy.xyz/api/v1/network-pulse");
const data = await res.json();

Read the settlement receipt

import { decodePaymentResponseHeader } from "@x402/fetch";

// v2 dropped the x- prefix: it is PAYMENT-RESPONSE, matching PAYMENT-REQUIRED
// on the 402 itself.
const settled = decodePaymentResponseHeader(res.headers.get("payment-response")!);

// The generic SettleResponse field is 'transaction'; on Hedera it holds the
// Hedera transaction id, e.g. "0.0.9185802@1785406701.936622066".
console.log(settled.transaction, settled.payer, settled.success);

Independently of that header, every settled purchase is also appended to our public HCS topic 0.0.9840930 — so you have a consensus-ordered record of the transaction that neither side can alter after the fact.

Or just use curl

# Unpaid: returns 402 with the catalog entry and all accepted assets
curl -i https://hbar402.okeyamy.xyz/api/v1/hbar-spot

# The PAYMENT-REQUIRED header is base64 JSON. Decode it to see the options:
curl -sD - -o /dev/null https://hbar402.okeyamy.xyz/api/v1/hbar-spot \
  | grep -i '^payment-required:' | cut -d' ' -f2 | base64 -d | jq

reference

Endpoints

GET /api/v1/hbar-spot

0.01 HBAR · $0.001 · 0.001 H402

Live HBAR/USD spot price with 24h change and volume. The cheapest product in the catalog — priced so an agent polling every minute spends under a cent an hour.

returns: usd, change24hPct, vol24hUsd, marketCapUsd, asOf

GET /api/v1/network-pulse

0.02 HBAR · $0.002 · 0.002 H402

Live Hedera network throughput measured off the mirror node: observed TPS over the most recent transaction window, plus HBAR supply figures.

returns: observedTps, windowSeconds, sampleSize, circulatingHbar, totalHbar, asOf

GET /api/v1/token-snapshot

0.03 HBAR · $0.003 · 0.003 H402

Supply and distribution snapshot for any HTS token: total and max supply, decimals, treasury, freeze/kyc posture, and the top holders by balance.

tokenId (required) — HTS token id to inspect, e.g. 0.0.429274

returns: tokenId, name, symbol, decimals, totalSupply, maxSupply, treasury, topHolders[]

GET /api/v1/whale-watch

0.05 HBAR · $0.005 · 0.005 H402

Recent large transfers touching an account, ranked by absolute size. Useful for agents that need to react to treasury movements without running their own indexer.

accountId (required) — Hedera account id to watch, e.g. 0.0.5864587

minHbar (optional) — Minimum absolute HBAR movement to report (default 100), e.g. 100

returns: accountId, minHbar, movements[] { transactionId, hbar, counterparty, consensusAt, hashscan }

Requests that fail validation return 4xx and are not settled, so a malformed call costs nothing.

settlement

Accepted assets

networkhedera:testnet

facilitatorhttps://x402.org/facilitator

payTo0.0.9841120

HBAR asset0.0.0 (tinybars)

USDC asset0.0.429274 (6dp)

H402 asset0.0.9840995 (6dp)

Paying in H402 also pays our shareholders: the token carries fractional custom fees, so consensus routes a cut of your transfer to collector accounts inside the same transaction. The fees are charged on top of the price, so the amount debited from you is slightly higher than the quoted figure while the seller still receives exactly the quote.