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
- Create a Stellar signer.
createEd25519Signer(secret, network) parses
the secret and produces the signer expected by the Stellar client scheme.
- Register
exact. x402Client().register() associates
stellar:testnet with the client-side ExactStellarScheme.
- Make the application request without payment. Keep the method, body, and
other application headers available for an identical retry.
- Parse
PaymentRequired. x402HTTPClient.getPaymentRequiredResponse()
reads the canonical body and response headers.
- 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.
- Create
PaymentPayload. createPaymentPayload(required) asks the
registered scheme to construct and sign the Stellar authorization.
- Encode payment headers.
encodePaymentSignatureHeader(payload) creates
the canonical headers for the paid retry.
- Retry the same application request. Reuse the same method and exact body;
add the payment headers once.
- Parse
PaymentSettleResponse. Read it from the successful response with
getPaymentSettleResponse() and verify success, network, and payer.
- 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 10, 2026