exact: a fixed price
- The service asks for a fixed amount.
- The buyer signs exactly that amount.
- Periplo verifies it and settles that same amount.
For requests with a known price, like one API call at a flat rate.
x402 · Stellar testnet
x402 payments on Stellar that charge only for what's used.
Periplo is an open-source, non-custodial x402 facilitator: in x402, the facilitator is the service that verifies and sends the payment the buyer signs. With upto, the buyer signs a spending ceiling once and only the real usage settles; the contract enforces the ceiling and its balance is zero after every settlement.
We're proposing upto for Stellar inside the x402 standard, so any facilitator can use it the same way (open PR, x402-foundation/x402#3098)
Testnet only. Periplo does not operate on mainnet yet.
01
How it works
A service answers HTTP 402 with its price. The buyer signs a payment; Periplo checks it and submits it to Stellar. Two schemes cover two ways of charging.
upto: pay for real usage
- The buyer signs a spending ceiling once.
- The service measures what was actually used.
- Only the real amount is settled; the contract refunds the rest in the same transaction.
For usage you only know afterwards: tokens generated, seconds of access, rows returned.
Who controls the funds
The buyer signs each payment with their own key. The facilitator only pays network fees, refuses to start with a key that can move user funds, and is never the source or signer of a buyer's payment.
Read the threat modelDiscovery included
Resources settled through Periplo can be cataloged so agents can find them by searching, not by knowing the URL in advance.
Where upto runs today
upto settles against the UptoSettlement contract on testnet. The public facilitator only advertises the schemes listed in its live status below.
02
Evidence on testnet
Real stellar:testnet transactions, each one linked to the block explorer so you can check it yourself.
Periplo's first full pipeline: a payment signed with @x402/stellar, verified and settled by Periplo's facilitator core.
View transaction: 83d2aa3b60…d89f33Partial settlement: the buyer signed a 0.1 PTEST ceiling and the facilitator settled 0.04 PTEST.
View transaction: cc46374e34…c5d218Zero settlement: a 0.05 PTEST ceiling settled at 0, the full ceiling returned to the buyer; a replay with the same nonce was rejected.
View transaction: 2138c0418a…03d358Periplo's first payment between an external seller and an independent buyer, neither of them this project, in testnet USDC.
View transaction: 4befe51d2c…7904fdInteroperability: a payment built with the same client code, verified and settled through x402.org's independent reference facilitator.
View transaction: 43bd169873…dc7c8fFour concurrent settlements in the same ledger, each from a different account of the channel-account pool.
View transaction: 33a6791890…0b3764Metered API: a 0.1 PTEST ceiling for up to 20 rows; 10 rows were returned, so 0.05 PTEST was settled and the rest refunded.
View transaction: cf33b51350…533823The same contract, in testnet USDC: a 0.10 USDC ceiling and 0.05 USDC settled, the rest refunded. The asset travels inside each signed authorization, so the contract was not redeployed.
View transaction: d554adfb8f…c5cafb
06
Client library
periplo is the npm package behind these examples: sign an upto ceiling as a buyer, or advertise one and settle real usage as a seller.
npm i periplo
import { createUptoStellarPayer, payAndFetch } from "periplo";
const payer = createUptoStellarPayer(buyerSecret, "stellar:testnet", {
facilitatorBaseUrl: "https://periplo-testnet.fly.dev",
maxSpendPerAuthorization: 1_000_000n, // 0.1 USDC, 7 decimals
});
const response = await payAndFetch(resourceUrl, payer);03
Facilitator live status
Read from the public deployment's /supported and /status endpoints when you open this page. periplo-testnet.fly.dev
Contacting the facilitator…
04
Upstream contributions
Bugs Periplo found and fixes it proposed in the libraries it builds on. The state of each one comes from the GitHub API, not from memory.
State checked against the GitHub API on .
Merged: 3Closed as resolved: 10Open: 10Closed without merge: 1Closed as not planned: 1
Pull requests (9)
- Mergedstellar/stellar-dev-skill#103fix: point ECOSYSTEM_CARDS copyValue at raw content, not GitHub's blob HTML page
- Mergedx402-foundation/x402#3228fix(e2e): scope EVM/SVM client signer derivation to selected families
- Mergedx402-foundation/x402#3336fix(stellar): include feeBumpSigner in facilitator-safety checks
- Openx402-foundation/x402#3098docs: add upto scheme implementation spec for Stellar
- Openx402-foundation/x402#3138fix(bazaar): use raw resource URL as canonical for opaque-origin schemes
Show 4 more
- Openx402-foundation/x402#3215fix(core): derive one wildcard pattern per namespace, not one for the whole registration
- Openx402-foundation/x402#3338fix(core): enforce settlement override ceiling against PaymentRequirements.amount
- Openx402-foundation/x402#3339docs(stellar): cross-reference areFeesSponsored's unsupported-false limitation on the constructor
- Closed without mergestellar/js-stellar-sdk#1672fix(contract): walk every CAP-71 delegate node, not just the top level
Issues (16)
- Closed as resolvedOpenZeppelin/stellar-contracts#839Signer::Delegated + ContextRuleType::CallContract: __check_auth traps (UnreachableCodeReached) on a real signed auth entry (asking for help diagnosing, not sure yet if it's our construction or a coverage gap)
- Closed as resolvedOpenZeppelin/stellar-contracts#863Signer::Delegated: recording-mode simulation never surfaces the delegate's signing requirement (likely explains #839's trap)
- Closed as resolvedStellarCN/py-stellar-base#1215authorize_entry(): sequential CAP-71 delegate signing silently invalidates an earlier signature on expiration mismatch
- Closed as resolvedstellar/js-stellar-sdk#1681AssembledTransaction.signAuthEntries can't represent a non-master-key signer for a plain Address credential, in two separate ways
- Closed as resolvedstellar/js-stellar-sdk#1683authorizeEntry's bare-signature fallback ignores forAddress, so a signer targeting a non-top-level address gets verified against the wrong public key
Show 11 more
- Closed as resolvedx402-foundation/x402#3169isValidRouteTemplate's traversal/scheme-injection checks decode routeTemplate once, so double percent-encoding bypasses both
- Closed as resolvedx402-foundation/x402#3187[Bug]: e2e client eagerly derives EVM+SVM signers regardless of --families, crashing single-family conformance runs
- Closed as resolvedx402-foundation/x402#3270HTTPFacilitatorClient.settle()/verify() discard the EXTENSION-RESPONSES header instead of returning it
- Closed as resolvedx402-foundation/x402#3332@x402/stellar: feeBumpSigner documented as a facilitator address by getSigners() but excluded from every facilitator-safety check
- Closed as resolvedx402-foundation/x402#3334@x402/core: settlePayment() settlement-override resolution never enforces its own documented ceiling against PaymentRequirements.amount
- Openstellar/js-stellar-sdk#1655needsNonInvokerSigningBy()/signAuthEntries() only see the top-level node of a SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES entry, so an outstanding delegate signature is never reported
- Openx402-foundation/x402#3121[Bug]: extractDiscoveryInfo builds a broken canonical URL for mcp://tool/{toolName} resources
- Openx402-foundation/x402#3172x402Facilitator.derivePattern() silently drops wildcard coverage when a single facilitator registers networks from multiple CAIP-2 namespaces
- Openx402-foundation/x402#3333@x402/stellar: areFeesSponsored: false accepted with no validation, silently breaks 100% of settlements against the official client
- Openx402-foundation/x402#3341Spec: batch-settlement on Stellar needs a different voucher-signing mechanism than upto (require_auth caps expiration at 180 days)
- Closed as not plannedstellar/js-stellar-sdk#1699XdrLargeInt.toU128()/.toU256()/.toU64() silently wrap negative values instead of throwing RangeError
05
Open source
All of Periplo is public under Apache-2.0: the facilitator, the discovery catalog, the contracts and this site.