Skip to content

docs: add x402 payment standard page under AI Studio on Hedera#550

Open
piotrswierzy wants to merge 1 commit into
hashgraph:mainfrom
blockydevs:docs/hedera-x402
Open

docs: add x402 payment standard page under AI Studio on Hedera#550
piotrswierzy wants to merge 1 commit into
hashgraph:mainfrom
blockydevs:docs/hedera-x402

Conversation

@piotrswierzy
Copy link
Copy Markdown

@piotrswierzy piotrswierzy commented May 25, 2026

Description:

Add a top-level x402 doc covering Hedera's official "exact" payment
scheme and reference implementation in the x402 repo.

  • Explain what x402 is/is not, who uses it, and its use cases to correct the "magic crypto-for-agents" misconception
  • Document the facilitator-as-feePayer flow and the PaymentRequirements /PaymentPayload/SettlementResponse messages
  • Add client/server usage examples; note @x402/hedera is not yet on npm (use from the x402 monorepo source)
  • Cover requirements and limitations
  • Highlight the Blocky402 facilitator (verified hedera:testnet endpoint and docs) plus how to run and get listed as a Hedera facilitator
  • Link the Hedera blog, scheme spec, package, whitepaper, and report

Register the page in docs.json under the "AI Studio on Hedera" group.

Related issue(s):

Fixes #

Notes for reviewer:

Checklist

  • Documented (Code comments, README, etc.)
  • Tested (unit, integration, etc.)

    Add a top-level x402 doc covering Hedera's official "exact" payment
    scheme and reference implementation in the x402 repo.

    - Explain what x402 is/is not, who uses it, and its use cases to
      correct the "magic crypto-for-agents" misconception
    - Document the facilitator-as-feePayer flow and the PaymentRequirements
      /PaymentPayload/SettlementResponse messages
    - Add client/server usage examples; note @x402/hedera is not yet on npm
      (use from the x402 monorepo source)
    - Cover requirements and limitations
    - Highlight the Blocky402 facilitator (verified hedera:testnet endpoint
      and docs) plus how to run and get listed as a Hedera facilitator
    - Link the Hedera blog, scheme spec, package, whitepaper, and report

    Register the page in docs.json under the "AI Studio on Hedera" group.

Signed-off-by: Piotr Swierzy <piotr.swierzy@blockydevs.com>
@chopmob-cloud
Copy link
Copy Markdown

@piotrswierzy @walkerlj0 -- adding a data point for the Hedera x402 facilitator listing (point 6 of the issue scope on hashgraph/hedera-agent-kit-js#806).

AlgoVoi APM (Agent Payment Module) runs x402 on Hedera in production via the gateway at api.algovoi.co.uk. The Hedera-specific envelope shape was posted on the parent issue #806 on 2026-05-16 as a concrete example of the exact scheme: HTS token-ID asset field, Hedera account-ID payTo field, fee-payer model. Two shape gotchas worth a callout in the page (HTS decimal-string asset, not 0x hex; Hedera 0.0.X account-ID payTo) are also in that comment.

Facilitator surfaces:

  • Production endpoint: api.algovoi.co.uk -- supports the Hedera exact scheme alongside 7 other chain families (Algorand, VOI, Solana, Stellar, Base, Tempo, Ethereum)
  • Hedera testnet x402 resource example: https://api.algovoi.co.uk/r/demo/x402-test-hedera
  • /supported declaration includes Hedera mainnet + testnet with the standard signer metadata
  • Settlement emits categorical receipts under draft-hopley-x402-canonicalisation-jcs-v1 (POSTED IETF Internet-Draft, sole AlgoVoi authorship); the receipt-format suite covers compliance / settlement / cancellation / refund / composite-trust-query
  • APM landing page: docs.algovoi.co.uk/platform/apm
  • Substrate Adopters Registry recording the canonicalisation discipline: docs.algovoi.co.uk/adopters

The page would benefit from at least two production-grade Hedera facilitator entries (parallel coverage, not single-vendor) so readers see Hedera x402 as ecosystem infrastructure rather than implementation-specific. Happy to PR the facilitator-list entry directly against this branch or file a follow-up PR once #550 lands -- whichever path keeps the review cycle short for you.

-- AlgoVoi

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants