The upto scheme#

Status: designed and specified, not yet built. Tranche 2 work. No Stellar upto specification exists today — authoring one is part of the deliverable.

Why it matters#

The exact scheme assumes the price is known before the work happens. For a great many of the services agents actually want to buy, it isn’t.

An LLM endpoint cannot know its token count until generation completes. A query engine cannot know its cost until it knows how many rows it scanned. A rendering service cannot know its cost until it knows the complexity of the scene. These sellers have two bad options under exact: quote a worst-case price and overcharge nearly every request, or quote after the fact and hope the buyer pays.

upto fixes this. The payer authorises a ceiling; the seller charges the actual cost, up to that ceiling. The buyer’s exposure is bounded and known in advance; the seller charges what the work was worth.

For metered AI services — which is a large fraction of what agent-to-agent commerce will consist of — this is not a nice-to-have. It is the difference between x402 being usable and not.

The scheme exists for EVM and SVM. There is no Stellar specification. Writing one is a deliverable of this grant, submitted upstream to the x402 Foundation.

Why SEP-41 alone is not enough#

The obvious implementation is the familiar ERC-20 pattern: the payer calls approve for the cap, and the facilitator later calls transfer_from for the actual amount. SEP-41 provides both.

It does not work, for two reasons.

approve does not bind the recipient. A SEP-41 approval authorises a spender to move funds. It does not constrain where those funds go. Once approved, the facilitator can transfer the payer’s tokens to any destination it chooses, up to the allowance. The buyer’s trust assumption changes from “this facilitator might fail to settle” to “this facilitator can take my money.” That is a materially worse trust model than exact, where the recipient is bound inside the signed authorization entry — and it would be a strange regression for the more sophisticated scheme to be the less safe one.

approve does not guarantee single settlement. An allowance persists until spent or revoked. Nothing in SEP-41 prevents a facilitator from drawing against it repeatedly — several charges against a single authorisation, each individually under the cap. A per-request payment protocol needs each authorisation to be consumable exactly once, and a bare allowance cannot express that.

There is a third, subtler problem: a lingering allowance is standing risk. Even an honest facilitator that never misuses it leaves the payer exposed to whatever compromises that facilitator later suffers. The Soroban ecosystem already treats stale approvals as a known hazard.

Conclusion: upto on Stellar requires a contract. I could ship a contract-free version built on raw allowances. I am choosing not to, because it would be a weaker trust model presented as an equivalent feature, and an integrator would have to read the implementation carefully to discover that. The honest design costs one small contract and an audit.

The contract#

A minimal, single-purpose contract. Deliberately small: it holds no funds, has no admin, and its entire job is to enforce two invariants the token standard cannot.

The payer’s authorization entry authorises an invocation of:

settle_upto(payer, payee, asset, cap, nonce)

Because this is a Soroban authorization entry, the payer’s signature binds all of those arguments — including payee. The recipient is inside the signed material, exactly as it is under exact. The facilitator cannot redirect the payment.

The contract enforces:

Nonce-once. Each (payer, nonce) pair may settle exactly once. A replayed authorisation is rejected on-chain, not merely by facilitator-side bookkeeping. This is the guarantee a bare allowance cannot provide, and putting it on-chain means it holds even if the facilitator is compromised or buggy.

Actual ≤ cap. The settled amount may not exceed the authorised ceiling. Enforced by the contract, not by the facilitator’s honesty.

Recipient binding. Inherited from the authorization entry: the transfer goes to the payee the payer signed for, or the invocation fails.

The trust model that results is worth stating explicitly, because it is the point of the design: a compromised Turnpike can fail to settle a payment, or settle it for less than the cap. It cannot redirect funds, cannot exceed the cap, and cannot settle twice. Those are properties of the ledger, not promises from me.

Apache-2.0, like everything else.

Specification work#

The contract needs a specification, and the specification does not exist. The Tranche 2 deliverable includes authoring scheme_upto_stellar.md and submitting it upstream to x402-foundation/x402, covering:

  • The authorization-entry shape and the exact arguments it binds
  • Settlement semantics, including the nonce-once guarantee and its rationale
  • Cap enforcement and the handling of partial settlement
  • Error semantics — every failure named, so implementations reject consistently
  • Reference contract interface, so other implementations can interoperate

This is the deliverable with the longest reach beyond Turnpike itself. A specification is used by implementations that have nothing to do with Turnpike; a facilitator serves only its own users. I would rather the Stellar upto scheme exist as a well-specified, interoperable standard than as a Turnpike feature.

Completion is measured by the PR being opened against the protocol repository with a public discussion link, not by a document existing in my own repo.

Audit#

The contract expands the audit surface from “an off-chain service” to “an off-chain service plus one on-chain contract.” That is a real cost and I am accounting for it rather than eliding it.

Security audits are provided through the SDF Audit Bank at Tranche 3 and are correctly excluded from my budget. What is budgeted is engineering time to remediate findings, gated as a release blocker: all critical and high findings resolved or formally accepted before mainnet, with the remediation summary published.