Scheme: exact on Stellar
Versions supported
- ❌
v1- we don’t plan to support v1 for now. - ✅
v2
Supported Networks
This spec uses CAIP-2 identifiers:
stellar:pubnet- Stellar mainnetstellar:testnet- Stellar testnet
Summary
The x402 exact scheme on Stellar uses Soroban token transfers where the facilitator sponsors transaction fees while the client controls fund flow via signed authorization entries.
[!NOTE] > Scope: This spec covers SEP-41-compliant Soroban tokens only. Classic Stellar assets are not supported.
Protocol Flow
The protocol flow for exact on Stellar is client-driven with facilitator-sponsored execution:
- Client makes a request to a Resource Server.
- Resource Server responds with a
402 Payment Requiredstatus andPaymentRequiredheader containingextra.areFeesSponsored(fee sponsorship indicator). - Client builds a smart contract invocation transaction calling
transfer(from, to, amount)on the token contract reference and simulates it to identify required authorization entries. - Client signs the authorization entries (not the full transaction) with their wallet, setting expiration to
currentLedger + ledgerTimeout, whereledgerTimeout = ceil(maxTimeoutSeconds / estimatedLedgerSeconds); implementations should use the current network estimate forestimatedLedgerSecondswhen available (fallback to5seconds). - Client serializes the transaction with signed auth entries and encodes it as XDR (base64).
- Client sends a new request to the resource server with the
PaymentPayloadcontaining the base64-encoded transaction. - Resource Server forwards the
PaymentPayloadandPaymentRequirementsto the Facilitator Server’s/verifyendpoint. - Facilitator decodes the transaction XDR and validates the transaction’s: structure, auth entries, signature expiration, amount, payer, and recipient.
- Facilitator returns a
VerifyResponseto the Resource Server. - Resource Server, upon successful verification, forwards the payload to the facilitator’s
/settleendpoint.- NOTE:
/settleMUST perform full verification independently and MUST NOT assume prior verification.
- NOTE:
- Facilitator rebuilds the transaction with its own account as the source, preserving all operations and auth entries.
- Facilitator simulates the transaction to verify it succeeds, emits the expected transfer events, and derives the settlement fee and fresh Soroban resource data (footprint and resource fee cap) from that simulation.
- Facilitator signs the rebuilt transaction with its own key and submits it to the Stellar network via RPC
sendTransaction. - Facilitator polls for transaction confirmation and responds with a
SettlementResponseto the Resource Server. - Resource Server grants the Client access to the resource in its response upon successful settlement.
PaymentRequirements for exact
In addition to the standard x402 PaymentRequirements fields, the exact scheme on Stellar requires the following inside the extra field:
{
"scheme": "exact",
"network": "stellar:testnet",
"amount": "10000000",
"asset": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
"payTo": "GBHEGW3KWOY2OFH767EDALFGCUTBOEVBDQMCKU4APMDLQNBW5QV3W3KO",
"maxTimeoutSeconds": 60,
"extra": {
"areFeesSponsored": true
}
}
Field Definitions:
extra.areFeesSponsored: Whether facilitator sponsors fees. Currently always true; a non-sponsored flow will be added later.
PaymentPayload payload Field
The payload field of the PaymentPayload contains:
{
"transaction": "AAAAAgAAAABriIN4poutFUmHfB6FbFJu8GgXoPPTGQWREqFpPfvO1AAAAAAAAAAAAAAAAAAAAA..."
}
The transaction field contains the base64-encoded XDR of a Stellar transaction with a single invokeHostFunction operation calling transfer(from, to, amount) and signed authorization entries with expiration derived from maxTimeoutSeconds.
Full PaymentPayload object:
{
"x402Version": 2,
"resource": {
"url": "https://example.com/weather",
"description": "Access to protected content",
"mimeType": "application/json"
},
"accepted": {
"scheme": "exact",
"network": "stellar:testnet",
"amount": "10000000",
"asset": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
"payTo": "GBHEGW3KWOY2OFH767EDALFGCUTBOEVBDQMCKU4APMDLQNBW5QV3W3KO",
"maxTimeoutSeconds": 60,
"extra": {
"areFeesSponsored": true
}
},
"payload": {
"transaction": "AAAAAgAAAABriIN4poutFUmHfB6FbFJu8GgXoPPTGQWREqFpPfvO1AAAAAAAAAAAAAAAAAAAAA..."
}
}
Facilitator Verification Rules (MUST)
A facilitator verifying an exact scheme on Stellar MUST enforce all of the following checks before sponsoring and signing the transaction:
1. Protocol Validation
- The
x402VersionMUST be2. - Both
payload.accepted.schemeandrequirements.schemeMUST be"exact". - The
payload.accepted.networkMUST matchrequirements.network.
2. Transaction Structure
- The transaction MUST contain exactly 1 operation of type
invokeHostFunction. - The function type MUST be
hostFunctionTypeInvokeContract. - The contract address MUST match
requirements.asset. - The function name MUST be
"transfer"with exactly 3 arguments.- Argument 0 (from): The source address signing the auth entries.
- Argument 1 (to): MUST equal
requirements.payToexactly. - Argument 2 (amount): MUST equal
requirements.amountexactly (as i128).
3. Authorization Entries
- The transaction MUST contain signed authorization entries for the
fromaddress. - Auth entries MUST use an address-based credential type: either
sorobanCredentialsAddress(legacy) orsorobanCredentialsAddressV2(CAP-71). Both carry the sameSorobanAddressCredentialsfields and differ only in the preimage the signer commits to:ENVELOPE_TYPE_SOROBAN_AUTHORIZATIONfor the legacy arm and the address-boundENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESSfor V2.- NOTE: Protocol 28 activates the V2 arm on the network, so clients may submit V2-signed entries from that point on. Recording-mode simulation still returns the legacy arm as of Protocol 28, but facilitators MUST accept both so they keep working when a client opts into V2 or the simulation default changes.
- Auth entries MUST NOT use
sorobanCredentialsSourceAccountorsorobanCredentialsAddressWithDelegatescredentials. - The
rootInvocationMUST NOT containsubInvocationsthat authorize additional operations beyond the transfer. - The facilitator MUST verify that all required signers have signed their auth entries.
- The auth entry expiration ledger MUST NOT exceed
currentLedger + ceil(maxTimeoutSeconds / estimatedLedgerSeconds).- NOTE: implementations should use the current network estimate for
estimatedLedgerSecondswhen available (fallback to5seconds).
- NOTE: implementations should use the current network estimate for
4. 🚨🚨🚨 Facilitator Safety
- The transaction source account provided by the client MUST NOT be the facilitator’s address.
- The operation source account provided by the client MUST NOT be the facilitator’s address.
- The facilitator MUST NOT be the
fromaddress in the transfer. - The facilitator address MUST NOT appear in any authorization entries.
- The simulation MUST emit events showing only the expected balance changes (recipient increase, payer decrease), and NO OTHER BALANCE CHANGES.
These checks prevent the fee payer from being tricked into transferring their own funds or sponsoring unintended actions.
5. Simulation
- The facilitator MUST re-simulate the transaction against the current ledger state.
- The simulation MUST succeed without errors.
- The simulation MUST emit events confirming the exact balance change specified in
requirements.amount.
Transaction Fees
In the sponsored flow (areFeesSponsored: true), the facilitator fully controls settlement fees. The facilitator MUST NOT use the client’s fee bid when rebuilding the transaction.
Facilitator (MUST)
- Derive the settlement fee from a fresh simulation at settle time:
simulationResourceFee + inclusionBuffer, where the inclusion buffer MUST be at least 100 stroops. - Refresh the Soroban resource data (footprint and
resourceFeecap) from that same simulation before submitting. - Fully override the client’s fee when rebuilding the transaction for submission.
Safety ceiling: maxTransactionFeeStroops
Facilitator implementations MAY expose a maxTransactionFeeStroops configuration as a safety ceiling / circuit breaker (default: 50,000 stroops, operator-overridable). If the simulation-derived settlement fee exceeds this ceiling, the facilitator MUST reject verification with invalid_exact_stellar_payload_fee_exceeds_maximum. This is not a per-transaction budget knob; normal transfers should fall well below the default ceiling.
Settlement Logic
Settlement is performed via the facilitator rebuilding and signing the transaction:
Phase 1: Transaction Reconstruction
- Parse the client’s signed transaction XDR.
- Extract all operations and authorization entries.
- Re-simulate the transaction and derive the settlement fee and fresh Soroban resource data from the simulation result.
- Rebuild a new transaction with:
- Source Account: Facilitator’s Stellar address (spends sequence number and pays fees)
- Operations: Copied from the client’s transaction
- Auth Entries: Copied from the client’s transaction
- Fee: Simulation-derived (
simulationResourceFee + inclusionBuffer, buffer >= 100 stroops); MUST NOT use the client’s fee - Soroban Data: Refreshed from the settle-time simulation (footprint and
resourceFeecap)
Phase 2: Transaction Submission
- Sign the rebuilt transaction with the facilitator’s key.
- Submit the fully-signed transaction to the Stellar network via RPC
sendTransaction. - Verify the submission status is
PENDING, and then poll for confirmation (SUCCESSorFAILED).
Phase 3: SettlementResponse
The SettlementResponse for the exact scheme on Stellar:
{
"success": true,
"transaction": "a1b2c3d4e5f6...",
"network": "stellar:testnet",
"payer": "GBHEGW3KWOY2OFH767EDALFGCUTBOEVBDQMCKU4APMDLQNBW5QV3W3KO"
}
transaction: The transaction hash (64-character hex string)payer: The address that paid for the transaction (the client’s address, not the facilitator)
Appendix
Key concepts for understanding Stellar transaction composition and authorization in x402:
Transaction Hierarchy
Per the transaction hierarchy below, the client builds and signs the contract invocation (innermost component) and sends it to the resource server. During settlement, the facilitator attaches the signed invocation to a transaction for Stellar network submission, handling fees and sequence numbers.
FeeBumpTransactions are optional but recommended for higher throughput and lower latency.
Authorization Patterns
Clients can authorize invocations via:
- Auth entry signing (reference): Authorizes only the invocation.
- Higher throughput (no sequence number spent by client)
- Supports both C-accounts and G-accounts
- Requires fee sponsorship
- Full transaction signing: Signs the entire transaction, spending sequence number.
- Simpler approach
- No fee sponsorship needed
- Lower throughput (one tx/ledger per client)
- Only supports G-accounts
The x402 protocol uses approach #1 for broader wallet support (C-accounts and G-accounts). Approach #2 may be added later for non-sponsored flows.