upto scheme is a metered payment: the buyer authorizes a spending ceiling, and only the actual usage settles, never more than the ceiling.
It is the fit for a service whose price is not known until after the work runs, such as token billing or per-request metering. For a fixed price known up front, use The exact scheme.
exact versus upto
How a payment settles
1
The seller states a ceiling
The
402 terms carry a scheme of upto and a maximum amount. This is the most the call can cost.2
The buyer authorizes up to the ceiling
The buyer signs a Soroban authorization entry against the
upto contract, permitting a settlement of any amount up to the ceiling, once.3
The work runs and the actual cost is known
The seller measures the usage. The actual charge is at most the ceiling.
4
The contract settles the actual amount
The facilitator calls the contract’s
settle with the actual amount. The contract enforces that it does not exceed the ceiling, moves exactly that amount, and marks the authorization consumed so it cannot settle twice.Why a Soroban contract ships
Theupto guarantees cannot be met by SEP-41 allowances alone. An approve / transfer_from allowance lets a spender move up to an approved amount, but it cannot bind the settlement to one specific recipient, and it does not enforce a single settlement. A stale allowance can be drawn more than once, and toward any recipient the spender chooses.
So upto ships a Soroban contract that enforces the two properties the scheme requires:
Ceiling binding
The contract refuses any
settle above the authorized ceiling.Single settlement
The authorization is consumed on first settlement, so it cannot be replayed.
CCMM3FMGEH7FHRYXZ3WQDQCTIWDXGZBGW7D4UT7NKH34SUQACYC3U54X. The facilitator advertises it, so a client can discover the address it must authorize against:
Shipping a contract widens the audit scope compared to
exact, which ships none. The single-use window is enforced on chain by ledger-bounded expiration, so an authorization cannot outlive the record that makes it single-use.Composing with smart-account spending policies
An agent buying from many services wants a budget it cannot exceed, checked on the ledger rather than in the client. Theupto contract composes with an OpenZeppelin smart-account spending policy to give that, using a reserve-then-reconcile pattern.
1
enforce reserves the ceiling
When the authorization is created, the policy’s
enforce reserves the full ceiling against the account’s budget. The worst case is booked up front, so a second request cannot double-spend the same budget.2
release reconciles to the actual charge
After settlement, the contract calls the policy’s
release with the actual amount. The policy refunds the unspent difference, and the budget ends at the real charge, not the ceiling.enforce reserves the ceiling, a budget that ends at the actual charge is only reachable if release ran. See Stellar essentials for what a smart account is, and Meter usage with upto for the wiring.
Using it
upto lives in @rail402.dev/scheme-upto-stellar. The buyer registers UptoStellarClientScheme; the seller registers UptoStellarServerScheme; the facilitator registers UptoStellarFacilitatorScheme.
Next steps
The exact scheme
The fixed-price counterpart.
Stellar essentials
Smart accounts and spending policies.
Packages
The upto package API and contract addresses.
Conformance
Settled upto transactions on testnet.