Skip to content

Add stellar checkout to pay for x402-protected resources - #2886

Open
fnando wants to merge 9 commits into
mainfrom
checkout-x402
Open

fnando wants to merge 9 commits into
mainfrom
checkout-x402

Conversation

@fnando

@fnando fnando commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

What

Adds stellar checkout <URL>, an x402 client. When the server responds with a 402, it builds and auth-signs a SEP-41 transfer and retries the request with the payment proof. The facilitator then submits it and pays the fees. Options: --max-amount sets a spend cap (default 1), --build-only prints the proof without paying, and --output json returns a receipt. Errors give the facilitator's reason, or name the account with a missing trustline or a low balance.

$ stellar checkout http://localhost:3001/protected/testnet --source payer
ℹ️ Received 402 Payment Required; building payment…
🌎 Submitting payment…
✅ Payment settled: f356e17b167823a4dda898b398e9f8ad3d111805c29840d3a12f7d50e1aa8811
🔗 https://stellar.expert/explorer/testnet/tx/f356e17b167823a4dda898b398e9f8ad3d111805c29840d3a12f7d50e1aa8811
<!DOCTYPE html>
...

Why

It lets Stellar users pay for x402-protected resources from the CLI with their existing identities and networks.

Close #2621

Known limitations

Only the exact scheme with fee-sponsoring facilitators is supported, and muxed payers aren't. Tested end to end against stellar/x402-stellar on testnet, which needs @x402/* ≥ 2.29.

@github-project-automation github-project-automation Bot moved this to Backlog (Not Ready) in DevX Nov 4, 2026
@fnando fnando moved this from Backlog (Not Ready) to In Progress in DevX Nov 4, 2026
@fnando
fnando requested review from leighmcculloch and marcelosalloum and a balanced review from Copilot November 4, 2026 19:56

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved critical flaws can authorize transfers beyond the spend cap, exhaust client memory, and corrupt downloaded binary resources.

7 open issues
What changed in this PR

Adds stellar checkout <URL> to fetch x402-protected resources using existing Stellar identities and network configuration. Payments use authorization-signed SEP-41 transfers that a fee-sponsoring facilitator submits.

Changes:

  • Adds challenge selection, spend-cap enforcement, payment-proof construction, and HTTP replay.
  • Supports build-only proofs, JSON receipts, and payment failure diagnostics.
  • Registers the command, documents its options, and adds unit tests.
File Description
FULL_HELP_DOCS.md Documents checkout usage and options.
cmd/​soroban-cli/​src/​env_vars.rs Registers the checkout spend-cap environment variable.
cmd/​soroban-cli/​src/​commands/​pay/​payment.rs Builds payment proofs and diagnoses transfer failures.
cmd/​soroban-cli/​src/​commands/​pay/​mod.rs Coordinates checkout, proof output, and receipts.
cmd/​soroban-cli/​src/​commands/​pay/​http.rs Fetches resources and replays requests with payment proofs.
cmd/​soroban-cli/​src/​commands/​pay/​challenge.rs Parses challenges, selects payment options, and decodes settlements.
cmd/​soroban-cli/​src/​commands/​pay/​cap.rs Parses and enforces display-unit spending limits.
cmd/​soroban-cli/​src/​commands/​mod.rs Registers and dispatches the checkout command.
cmd/​soroban-cli/​src/​commands/​contract/​invoke.rs Adds authorization-only transaction construction for payment proofs.
cmd/​soroban-cli/​src/​cli.rs Integrates checkout with structured JSON error output.

Review effort: Balanced

Comment thread cmd/soroban-cli/src/commands/pay/cap.rs Resolved
Comment thread cmd/soroban-cli/src/commands/pay/mod.rs Resolved
Comment thread cmd/soroban-cli/src/commands/pay/mod.rs Resolved
@fnando

fnando commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

@leighmcculloch @marcelosalloum can i get some 👀 on this?

@marcelosalloum marcelosalloum left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great job working on this 👏.

I left some comments below, happy to review again once they've been addressed.

Comment on lines +91 to +98
if self.sign_with_ledger {
return Ok(Some(Signer {
kind: SignerKind::Ledger(LedgerEntry {
hd_path: self.hd_path.unwrap_or_default(),
public_key: None,
}),
print: print.clone(),
}));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

stellar checkout --sign-with-ledger panics before it uses the device. This branch creates the Ledger entry with public_key: None. Then sign_soroban_authorizations calls get_public_key() on each signer. For Ledger, that function calls .expect() on the public key.

Comment on lines +143 to +152
/// Number of ledgers to add to the current ledger so the authorization signature
/// stays valid for at least `max_timeout_seconds`.
fn expiry_ledgers(max_timeout_seconds: u64) -> u32 {
// Round up so a short timeout still yields at least one ledger of validity.
let ledgers = max_timeout_seconds
.max(1)
.div_ceil(ESTIMATED_LEDGER_CLOSE_SECONDS)
.max(1);
u32::try_from(ledgers).unwrap_or(u32::MAX)
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The server sets maxTimeoutSeconds, and the CLI does not set a maximum for it. If the value is very large, the auth entry expires at ledger u32::MAX. Also, with_time_bounds sets the transaction max_time to u64::MAX. Thus, a person can send the signed transfer at any time in the future. The facilitator compares the expiry only with the same server value, so the client must set the limit.

Comment on lines +66 to +71
pub async fn get(url: &str, payment_signature: Option<&str>) -> Result<Response, Error> {
let client = reqwest::Client::builder().build().map_err(Error::Client)?;
let mut request = client.get(url);
if let Some(signature) = payment_signature {
request = request.header(PAYMENT_SIGNATURE_HEADER, signature);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The client follows redirects with the default request policy. On a redirect to a different host, this policy removes only the standard credential headers, for example Authorization and Cookie. It keeps PAYMENT-SIGNATURE. Thus, a redirect on the paid request sends the signed payment to a different host.

Comment on lines +245 to +254
pub struct Settlement {
#[serde(default)]
pub transaction: Option<String>,
#[serde(default)]
pub network: Option<String>,
#[serde(rename = "errorReason", default)]
pub error_reason: Option<String>,
#[serde(rename = "errorMessage", default)]
pub error_message: Option<String>,
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The x402 SettlementResponse has a success field, but Settlement does not read it. If a 2xx response contains success: false in PAYMENT-RESPONSE, the CLI shows "✅ Payment settled" and gives a receipt.

Comment on lines +125 to +132
pub fn amount_raw(&self) -> Result<i128, Error> {
let raw = self
.amount
.as_deref()
.or(self.max_amount_required.as_deref())
.ok_or(Error::MissingAmount)?;
raw.parse::<i128>()
.map_err(|_| Error::InvalidAmount(raw.to_string()))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The client should reject negative amounts

Comment on lines +67 to +85
let client = reqwest::Client::builder().build().map_err(Error::Client)?;
let mut request = client.get(url);
if let Some(signature) = payment_signature {
request = request.header(PAYMENT_SIGNATURE_HEADER, signature);
}
let response = request.send().await.map_err(|source| Error::Request {
url: url.to_string(),
source,
})?;
let status = response.status().as_u16();
let headers = response.headers().clone();
let body = response
.bytes()
.await
.map_err(|source| Error::Request {
url: url.to_string(),
source,
})?
.to_vec();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The client has no request timeout. Also, it reads all of the body into memory with no size limit. A slow or malicious server can stop the CLI or use all of the memory. Plz add a timeout and a content length cap

Comment on lines +47 to +49
/// Maximum amount to pay, in the asset's display units (e.g. `1` = 1.0 USDC,
/// roughly $1). Aborts before signing if the challenge asks for more. Set to
/// `none` to disable the cap.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, we should consider fetching the decimals from the asset contract if we're not already doing that.

The helper text could mention what 1.0 USDC would look like in a contract invocation (10000000 stroops)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if this conversion was an option and we still allowed people to rely on stroops (raw amounts)?

Comment on lines +37 to +38
#[error("the server's 402 response carried no payment declaration")]
MissingChallenge,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this is only for x402, but I'd like to mention MPP would have WWW-Authenticate: Payment … method="stellar" rather than PAYMENT-REQUIRED. My point is that this error could mention either that x402 is not supported or that the 402 response is not a protocol supported by the CLI client.

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

Labels

None yet

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

stellar checkout: x402 / MPP client

3 participants