Skip to main content
By the end of this page your endpoint prices with upto instead of exact, so a buyer authorizes a spending ceiling once and only the actual usage settles, enforced on chain by a Soroban contract. This uses @rail402.dev/scheme-upto-stellar.

exact versus upto

exact is for a price you know up front. The buyer authorizes and settles exactly that amount. It fits a fixed-price call, like one quote for one fee. upto is for a charge you do not know until the work is done. The buyer authorizes a ceiling, and the facilitator settles only the actual amount, up to that ceiling, in a single settlement. It fits metered services: token billing, per-unit compute, pay-for-what-you-read.

Register the server scheme

Register UptoStellarServerScheme on your resource server alongside or instead of the exact scheme, then price the route with scheme: "upto". The price.amount is the ceiling, the most a single call can settle.
server.js
The buyer signs an authorization for the ceiling. When the call completes, the facilitator submits a settlement for the actual usage, which the contract accepts once and only once, never above the ceiling.

The on-chain guarantee

upto ships a Soroban contract, deployed on testnet at CCMM3FMGEH7FHRYXZ3WQDQCTIWDXGZBGW7D4UT7NKH34SUQACYC3U54X, that enforces two properties a bare SEP-41 allowance cannot: the settled amount never exceeds the authorized ceiling, and a single authorization settles exactly once. The facilitator advertises the contract in its /supported response under extra.uptoContract, so a buyer can check which contract it is trusting before it signs.
upto composes with an OpenZeppelin smart-account spending policy. The policy reserves the ceiling on enforce, and after settlement the contract calls the policy’s release to reconcile the reservation down to the actual charge, so a buyer’s budget is never held above what it actually spent. See Concepts: upto.

Next steps

upto on chain

The contract, the ceiling and single-settlement guarantees, and smart-account reconciliation.

exact scheme

The fixed-price scheme, for when you know the amount up front.

Get discovered

An upto listing is cataloged the same way as any other resource.

Buyer quickstart

See the buyer authorize a ceiling and pay only for what it used.

When it fails

An over-ceiling settlement, a replayed authorization, or an expired authorization are each refused with a machine-readable code and a non-null reason. See Errors.