feat(hedera): add initial @x402/hedera package by piotrswierzy · Pull Request #1360 · x402-foundation/x402

piotrswierzy · 2026-02-26T14:52:03Z

add initial @x402/hedera package with exact payment scheme support

Introduced the @x402/hedera package implementing the x402 v2 exact payment scheme for Hedera.
Added client, server, and facilitator implementations along with necessary utilities and types.
Included configuration files for ESLint, Prettier, and Vitest.
Created documentation in README and CHANGELOG for package usage and features.
Established a .prettierignore file to exclude specific directories and file types from formatting checks.

Description

Tests

Checklist

I have formatted and linted my code
All new and existing tests pass
My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits
I added a changelog fragment for user-facing changes (docs-only changes can skip)

cb-heimdall · 2026-02-26T14:52:08Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 0/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 0

Global minimum 0

Max 1

1

1 if commit is unverified 1

Sum 2

vercel · 2026-02-26T14:52:09Z

@piotrswierzy is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

examples/typescript/clients/advanced/all_networks.ts

examples/typescript/clients/advanced/package.json

examples/typescript/clients/axios/index.ts

examples/typescript/clients/advanced/all_networks.ts

examples/typescript/clients/advanced/package.json

examples/typescript/facilitator/advanced/all_networks.ts

cb-heimdall · 2026-03-12T14:43:05Z

Review Error for skurzyp-blockydevs @ 2026-03-12 14:43:04 UTC
User failed mfa authentication, either user does not exist or public email is not set on your github profile. \ see go/mfa-help

typescript/packages/mechanisms/hedera/src/utils.ts

typescript/packages/mechanisms/hedera/.env.test

typescript/packages/mechanisms/hedera/src/exact/facilitator/scheme.ts

typescript/packages/mechanisms/hedera/src/exact/client/register.ts

kierzniak · 2026-03-13T09:20:58Z

typescript/packages/mechanisms/hedera/src/exact/facilitator/scheme.ts

+    if (requirementsValidation !== null) {
+      return requirementsValidation;
+    }
+    const feePayer = requirements.extra.feePayer as string;


I don't like this casting. Maybe we should extend PaymentRequirements with own type and guards to be sure that extra.feePayer exist?

SVM does it the same way

typescript/packages/mechanisms/hedera/src/exact/facilitator/scheme.ts

typescript/packages/mechanisms/hedera/src/exact/facilitator/register.ts

typescript/packages/mechanisms/hedera/src/exact/server/scheme.ts

cb-heimdall · 2026-03-16T11:45:39Z

Review Error for kierzniak @ 2026-03-16 11:45:39 UTC
User failed mfa authentication, either user does not exist or public email is not set on your github profile. \ see go/mfa-help

phdargen · 2026-03-19T02:22:15Z

Thanks a lot for the contribution @piotrswierzy, I'll begin reviewing shortly.

A few initial comments:

please remove the registerExactHederaScheme helper functions in favor of builder pattern, see https://github.com/coinbase/x402/pull/1266
revert changes in axios/fetch examples, hedera should ONLY be added to all_networks examples
please add hedera to the e2e tests https://github.com/coinbase/x402/tree/main/e2e

piotrswierzy · 2026-03-23T09:29:37Z

@phdargen
Let me know if there is anything else I can do, to support you in the review process.

phdargen · 2026-04-01T01:30:52Z

examples/typescript/clients/fetch/README.md


 Example client demonstrating how to use `@x402/fetch` to make HTTP requests to endpoints protected by the x402 payment protocol.

 ```typescript


please revert changes in this file, seems unrelated

phdargen · 2026-04-01T01:31:05Z

examples/typescript/clients/axios/README.md


 Example client demonstrating how to use `@x402/axios` to make HTTP requests to endpoints protected by the x402 payment protocol.

 ```typescript


please revert

phdargen · 2026-04-01T01:39:59Z

typescript/packages/mechanisms/hedera/test/integrations/exact-hedera.test.ts

@@ -0,0 +1,358 @@
+import { beforeEach, describe, expect, it } from "vitest";


In the TS package root package.json please add hedera integration test here:
"test:integration": "pnpm --filter @x402/core --filter @x402/evm --filter @x402/svm --filter @x402/aptos --filter @x402/stellar test:integration",

phdargen · 2026-04-01T01:42:41Z

examples/typescript/servers/advanced/all_networks.ts

+  price: string | { amount: string; asset: string; extra?: Record<string, unknown> };
  network: `${string}:${string}`;


Suggested change

price: string | { amount: string; asset: string; extra?: Record<string, unknown> };

network: `${string}:${string}`;

price: Price;

network: Network;

with import type { Network, Price } from "@x402/core/types";

phdargen · 2026-04-01T02:03:32Z

examples/typescript/servers/advanced/.env-local

@@ -1,4 +1,5 @@
 EVM_ADDRESS=
 SVM_ADDRESS=
+HEDERA_ADDRESS=


Took me a while to get the examples/e2e tests running, they fail when using an address like
HEDERA_ADDRESS=0x3f376c1e06b5495f2a015975671cc53f61e8e351

This address was accepted by the faucet (https://portal.hedera.com/faucet), so seems to be a valid address. I created it with PrivateKey.generateECDSA() from @hiero-ledger/sdk

I then had claude write me a script to fetch the accountId from the API
https://testnet.mirrornode.hedera.com/api/v1/accounts/ (any easier, more straightforward way to setup the accounts?)

With this the examples/e2e tests ran successfully
HEDERA_ADDRESS=0.0.8450511

Is HEDERA_ADDRESS supposed to accept both formats? Or just account ids? Then env vars should be renamed to HEDERA_ACCOUNT_ID

Please also put a link to the faucet in the appropriate READMEs

phdargen · 2026-04-01T02:12:57Z

There have been some changes to the e2e route structure, see https://github.com/coinbase/x402/pull/1779.
Could you please rebase against main and align your e2e tests?

Please also add e2e tests for the remaining server packages hono/next/fastify

phdargen · 2026-04-01T03:54:12Z

typescript/packages/mechanisms/hedera/src/signer.ts

+      }
+
+      tx.setTransactionId(TransactionId.generate(AccountId.fromString(feePayer)));
+      tx.setTransactionMemo(`x402:${Date.now().toString(36)}`);


A transaction memo isnt mentioned in the specs, is this needed? Does it incur any additional tx costs? Should there be any constraints enforced by the facilitator on memo format and size?

phdargen · 2026-04-01T04:02:22Z

typescript/packages/mechanisms/hedera/src/exact/facilitator/scheme.ts

+        payer: "",
+      };
+    }
+    const inspectedValidation = this.validateInspectedTransaction(inspected);


I think we should check the client set txFee here and reject if above a reasonable threshold, similar to SVM. Otherwise malicious client could set it arbitrarily large and grief the facilitator

phdargen · 2026-04-01T04:20:02Z

typescript/packages/mechanisms/hedera/src/exact/facilitator/scheme.ts

+    if (payToValidation !== null) {
+      return payToValidation;
+    }
+


Could we add tx simulation here or at least a balance check to protect the server from doing work for invalid requests?

phdargen · 2026-04-01T04:47:21Z

typescript/packages/mechanisms/hedera/src/exact/facilitator/scheme.ts

+   * @param transactionId - Hedera transaction id
+   * @returns Failed verify response or null
+   */
+  private async validateReplay(transactionId: string): Promise<VerifyResponse | null> {


Not sure about this replay protection mechanism.

Could you please elaborate why this is needed in the first place? Is this security critical or an optimization?

If a client sends the exact same tx multiple times, and the tx hasn't reached a confirmed state onchain yet, would settle return success for all even though only one actually settles and client pays only once?

If that's the case, could we align the implementation with the in-memory cache introduced for SVM in
https://github.com/coinbase/x402/pull/1468?

If a client sends a request and tx confirms onchain, then sends a request with exact same payload again, would settle fail? If we add simulation to verify would it fail for the duplicate tx? If so, do we still need the replay mechanism?

phdargen · 2026-04-01T04:49:48Z

typescript/packages/mechanisms/hedera/src/exact/server/scheme.ts

+   * @param network - Hedera network
+   * @returns AssetAmount in configured default HTS token
+   */
+  private defaultMoneyConversion(amount: number, network: Network): AssetAmount {


could we define any default stablecoin for the moneyParser here as for all the other networks?

phdargen · 2026-04-01T04:51:52Z

Hi @piotrswierzy, nice work! Made a first pass through the code and manually tested the examples/e2e tests, please find a few comments/suggestions above

…eme support- Introduced the @x402/hedera package implementing the x402 v2 exact payment scheme for Hedera.- Added client, server, and facilitator implementations along with necessary utilities and types.- Included configuration files for ESLint, Prettier, and Vitest.- Created documentation in README and CHANGELOG for package usage and features.- Established a .prettierignore file to exclude specific directories and file types from formatting checks. Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

- Introduced a new .env.test file for configuring ECDSA keys required for live integration tests. - Updated README to include instructions for setting up the environment and running integration tests. - Modified the createClientHederaSigner function to accept PrivateKey objects instead of strings for better type safety. - Enhanced error handling in ExactHederaScheme to manage unsupported network values and unexpected HBAR transfers. Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

…d clean up unused dependencies Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

…ilitators- Added support for Hedera payments in advanced clients (axios, fetch, advanced).- Updated environment variables to include HEDERA_ACCOUNT_ID, HEDERA_PRIVATE_KEY, and HEDERA_NETWORK.- Implemented Hedera signing and transaction handling in all relevant files.- Enhanced README documentation to reflect new Hedera configurations and requirements.This update allows users to interact with the Hedera network alongside existing EVM and SVM functionalities. Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

…ross all relevant files - Updated imports in various client and facilitator files to use @hiero-ledger/sdk instead of @hashgraph/sdk. - Adjusted README documentation to reflect the new SDK usage. - Removed obsolete .env.test file related to Hedera integration tests. - Updated pnpm-lock.yaml to reflect the new dependency version for @hiero-ledger/sdk. This change enhances compatibility and aligns with the latest SDK updates. Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

…ted pnpm-lock.yaml to reflect the new versioning for axios and @hiero-ledger/sdk.- Replaced instances of @hashgraph/sdk with @hiero-ledger/sdk in package.json files across clients and facilitators.- Enhanced network handling in the Hedera signer and utility functions to assert supported networks.- Refactored code to improve clarity and maintainability, including the removal of unused functions.This update ensures better compatibility with the latest SDK and improves the overall robustness of the Hedera integration. Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

…essary line breaks in imports within , , and .- Added a newline at the end of to comply with formatting standards. Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

…f to comply with formatting standards. Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

…age- Removed unnecessary imports from utils.ts.- Updated parameter naming in createPaymentPayload method for clarity.Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com> Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

…payment capabilities across various components including clients, facilitators, and servers.- Updated environment variables and configurations to include Hedera account and private key.- Enhanced README and documentation to reflect new Hedera protocol support.- Modified test configurations to include Hedera endpoints and payment requirements.This update expands the multi-chain support of the application, allowing for seamless integration with the Hedera network. Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

Expand Hedera e2e test coverage to Hono and Next.js servers, aligning with the new /exact/{chain} route naming convention from x402-foundation#1779. - Hono: add ExactHederaScheme import, env vars, registration, guard, middleware config, route handler, and test.config.json endpoint - Next.js: add proxy route (/api/exact/hedera), withX402 wrapper route, scheme registration in proxy.ts, and test.config.json endpoints - Update package.json dependencies for both servers - Update .env-local templates with HEDERA_PAYEE_ADDRESS Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

- Revert unrelated README changes in axios/fetch client examples - Add @x402/hedera to root test:integration filter - Use imported Network/Price types in server example instead of inline - Rename HEDERA_ADDRESS to HEDERA_ACCOUNT_ID for clarity, add faucet link - Add USDC as default stablecoin for Hedera money conversion (testnet: 0.0.429274, mainnet: 0.0.456858, 6 decimals) Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

github-actions bot added typescript sdk Changes to core v2 packages labels Feb 26, 2026

piotrswierzy changed the title ~~feat(hedera): add initial @x402/hedera package with exact payment sch…~~ feat(hedera): add initial @x402/hedera package Feb 26, 2026

github-actions bot added the examples Changes to examples label Mar 3, 2026

jaycoolslm reviewed Mar 4, 2026

View reviewed changes

examples/typescript/clients/advanced/all_networks.ts Show resolved Hide resolved

examples/typescript/clients/advanced/package.json Show resolved Hide resolved

examples/typescript/clients/axios/index.ts Show resolved Hide resolved

piotrswierzy commented Mar 4, 2026

View reviewed changes

examples/typescript/clients/axios/index.ts Show resolved Hide resolved

walkerlj0 mentioned this pull request Mar 4, 2026

Hedera x402 implementation hashgraph/hedera-agent-kit-js#525

Open

skurzyp-blockydevs approved these changes Mar 12, 2026

View reviewed changes

kierzniak reviewed Mar 13, 2026

View reviewed changes

kierzniak approved these changes Mar 16, 2026

View reviewed changes

piotrswierzy marked this pull request as ready for review March 18, 2026 13:18

phdargen self-assigned this Mar 19, 2026

phdargen reviewed Apr 1, 2026

View reviewed changes

piotrswierzy added 11 commits April 2, 2026 13:33

fix(pnpm-lock): update ws dependency version from 8.19.0 to 8.18.0 an…

1db0933

…d clean up unused dependencies Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

fix: clean up imports and formatting in Hedera package- Removed unnec…

7074ec0

…essary line breaks in imports within , , and .- Added a newline at the end of to comply with formatting standards. Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

fix: clean formatting in Hedera package- Added a newline at the end o…

1ab6bb5

…f to comply with formatting standards. Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>

piotrswierzy force-pushed the feat/hedera branch from c4dff0d to 3c868fa Compare April 2, 2026 18:09


		Example client demonstrating how to use `@x402/fetch` to make HTTP requests to endpoints protected by the x402 payment protocol.

		```typescript

		@@ -0,0 +1,358 @@
		import { beforeEach, describe, expect, it } from "vitest";

		price: string \| { amount: string; asset: string; extra?: Record<string, unknown> };
		network: `${string}:${string}`;

Conversation

piotrswierzy commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Tests

Checklist

Uh oh!

cb-heimdall commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Heimdall Review Status

Uh oh!

vercel bot commented Feb 26, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cb-heimdall commented Mar 12, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cb-heimdall commented Mar 16, 2026

Uh oh!

phdargen commented Mar 19, 2026

Uh oh!

piotrswierzy commented Mar 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phdargen commented Apr 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phdargen commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

piotrswierzy commented Feb 26, 2026 •

edited

Loading

cb-heimdall commented Feb 26, 2026 •

edited

Loading