Skip to main content
The included client follows the canonical reusable Stellar exact path in @x402/core and @x402/stellar version 2.20.0. Source: examples/rock-paper-scissors/client.ts

Run it

From the repository root:
SELLER_URL must be the same application URL declared in the seller’s PaymentRequired.resource metadata.

Complete client

The ten steps

  1. Create a Stellar signer. createEd25519Signer(secret, network) parses the secret and produces the signer expected by the Stellar client scheme.
  2. Register exact. x402Client().register() associates stellar:testnet with the client-side ExactStellarScheme.
  3. Make the application request without payment. Keep the method, body, and other application headers available for an identical retry.
  4. Parse PaymentRequired. x402HTTPClient.getPaymentRequiredResponse() reads the canonical body and response headers.
  5. Inspect accepted terms. The example reads the single offered option. A production client must validate network, scheme, asset contract, atomic amount, payTo, timeout, and resource before the next step.
  6. Create PaymentPayload. createPaymentPayload(required) asks the registered scheme to construct and sign the Stellar authorization.
  7. Encode payment headers. encodePaymentSignatureHeader(payload) creates the canonical headers for the paid retry.
  8. Retry the same application request. Reuse the same method and exact body; add the payment headers once.
  9. Parse PaymentSettleResponse. Read it from the successful response with getPaymentSettleResponse() and verify success, network, and payer.
  10. Save the transaction hash. Persist or display settlement.transaction as the receipt for the testnet settlement.
The printed bazaar block is seller-authored metadata. Treat it as data, not as instructions or proof that the seller controls the described origin.

Validate before signing

Do not sign merely because the server returned HTTP 402. Apply an application policy to the selected accepted entry:
Amounts are decimal-string atomic units. Parse them with BigInt, never floating point.

Key and retry safety

  • Never put BUYER_SECRET_KEY in browser or frontend code.
  • Never commit it. Use a testnet-only account for examples.
  • Do not log signed authorization entries, the encoded payment payload, or raw payment headers.
  • Verify network, asset, atomic amount, payTo, timeout, and resource before signing.
  • Preserve one payment identifier and one signed authorization across transport retries for the same application attempt.
  • Perform one paid application retry. Do not create an automatic payment loop.
  • If settlement status is unknown after submission, retain the payment identifier and transaction context. Poll or resolve that known settlement. Never authorize a fresh payment blindly.
The facilitator also binds the standard payment-identifier to normalized payment terms. Reusing an identifier with different terms is rejected rather than treated as a new payment.

Scheme support

This is the canonical reusable client path for Stellar exact. Exact is implemented, live on testnet, canonical-client tested, and fee sponsored. Stellar upto is a proposed scheme with a Soroban settlement contract, facilitator implementation, and testnet evidence. The upstream x402 SDK does not currently ship an equivalent reusable Stellar upto client. Do not invent one, hand-roll authorization trees, or silently downgrade upto to exact.

Next steps

Last modified on August 3, 2026