x402 Hedera

Build and demo paywalled experiences on Hedera testnet in minutes. This fork is in alpha.

This repo packages everything you need to stand up the x402 payment flow on Hedera: a facilitator, a token-gated resource server, and a sample client that pays for access.

Prerequisites

• Node.js 18+ and pnpm 10.7+ (corepack enable pnpm if you need to install it)
• git and a POSIX shell (bash/zsh)
• Hedera ECDSA testnet account funded with HBAR and associated with USDC 0.0.429274
• Basic familiarity with editing .env files on your machine

Need help preparing the Hedera account? Jump to Prepare your Hedera testnet wallet.

Quick Start (TL;DR)

git clone https://github.com/hedera-dev/x402-hedera.git
cd x402-hedera
chmod +x setup.sh
./setup.sh

Then open three terminals, all from the repo root:

1. Facilitator – cd examples/typescript/facilitator && cp .env-local .env → fill HEDERA_ACCOUNT_ID + HEDERA_PRIVATE_KEY → pnpm dev
2. Resource server – cd examples/typescript/servers/express && cp .env-local .env → set ADDRESS to the account that receives funds → pnpm dev
3. Client – cd examples/typescript/clients/axios && cp .env-local .env → set PRIVATE_KEY for the paying account → pnpm dev

You should see successful payments logged in all three terminals as the client purchases /hedera-usdc and /hedera-native.

Prepare your Hedera testnet wallet

1. Create or log into the Hedera Developer Portal and generate an ECDSA testnet account.
2. Fund the account with testnet HBAR from the portal faucet.
3. Associate USDC token 0.0.429274 with the wallet. Most wallets have an “Associate Token” action where you paste the token ID, or you can run this Hedera Portal Script.
4. Visit the Circle testnet faucet, choose Hedera Testnet, enter your account ID, and request USDC. The facilitator will spend from this account when verifying payments.

Keep both the account ID (0.0.x) and the private key handy; you will need them in the next steps.

Install project dependencies

The setup.sh script installs and builds the monorepo packages and the TypeScript examples.

chmod +x setup.sh
./setup.sh

If you prefer to do it manually:

cd typescript && pnpm install && pnpm build
cd ../examples/typescript && pnpm install && pnpm build

Run the facilitator

Terminal 1:

cd examples/typescript/facilitator
cp .env-local .env

Update .env with your fee payer credentials:

• HEDERA_ACCOUNT_ID – account that signs and pays fees
• HEDERA_PRIVATE_KEY – private key for the account (ECDSA)
• Optional PORT (defaults to 3002)

OR

Use our hosted testnet facilitator https://x402-hedera-production.up.railway.app/

You will need to update the .env in the next step

Start the facilitator:

pnpm dev

You should see Server listening on http://localhost:3002.

Run the resource server

Terminal 2:

cd examples/typescript/servers/express
cp .env-local .env

Configure .env:

• FACILITATOR_URL – typically http://localhost:3002
• NETWORK – leave as hedera-testnet
• ADDRESS – Hedera account that will receive the payment (can match the facilitator account or be different)

Start the server:

pnpm dev

The server exposes:

• GET /weather – free endpoint
• GET /hedera-usdc – pay $0.001 USDC on Hedera
• GET /hedera-native – pay 0.5 HBAR natively

Run the client

Terminal 3:

cd examples/typescript/clients/axios
cp .env-local .env

Set RESOURCE_SERVER_URL (default http://localhost:4021), PRIVATE_KEY for the paying account, and leave ENDPOINT_PATH as /hedera-native to exercise native HBAR payments. You can switch it to /hedera-usdc to test USDC payments instead.

Run the client:

pnpm dev

The script will:

1. Request the protected endpoint
2. Receive a 402 Payment Required
3. Pay through the facilitator
4. Retry and receive the gated response

Expect to see logs showing the transaction hash and the JSON payload returned from the server.

Verify everything is wired up

• The facilitator terminal prints verify and settle calls as they succeed.
• The resource server logs incoming payments and successful responses.
• The client prints the final response body, for example:

{
  "message": "You paid 0.5 HBAR natively!",
  "data": {
    "premium_content": "Exclusive Hedera network data with native payment",
    "paid_with": "HBAR",
    "amount_hbar": "0.5"
  }
}

You can also replay the flow manually with curl:

curl -i http://localhost:4021/hedera-usdc

The first response will be 402 Payment Required. Use the client to handle the payment, or craft your own request with the X-PAYMENT header if you are exploring deeper integrations.

Troubleshooting

• TOKEN_NOT_ASSOCIATED – make sure the paying account associated USDC 0.0.429274.
• INVALID_SIGNATURE – confirm you are using an ECDSA account and the private key matches the ID.
• insufficient payer balance – top up HBAR via the Hedera portal and USDC via the Circle faucet.
• .env not loading – double-check you renamed .env-local to .env in each directory.
• Ports busy – adjust PORT in the facilitator .env or the server script.

Project layout essentials

• setup.sh – installs and builds the TypeScript packages and examples.
• examples/typescript/facilitator – Hedera facilitator reference implementation.
• examples/typescript/servers/express – paywalled Express server with Hedera endpoints.
• examples/typescript/clients/axios – sample client that pays via x402.
• specs/ – protocol specs if you want to dig into the internals.

Run pnpm test from typescript/ if you want to execute the library test suite.

Learn more about x402

• x402.org – protocol overview and ecosystem
• Protocol specs – full request/response formats
• ROADMAP.md – upcoming protocol milestones

Questions during the hackathon? Drop into the event Discord or open an issue, and share what you are building!