exact: precio fijo
- El servicio pide un monto fijo.
- El comprador firma exactamente ese monto.
- Periplo lo verifica y liquida ese mismo monto.
Para solicitudes con precio conocido, como una llamada a una API con tarifa plana.
x402 · Stellar testnet
Pagos x402 en Stellar que cobran solo lo que se usa.
Periplo es un facilitador x402 no custodial y de código abierto: en x402, el facilitador es el servicio que verifica y envía el pago que el comprador firma. Con upto, quien compra firma un techo de gasto una sola vez y solo se liquida el uso real; el contrato hace cumplir el techo y su saldo queda en cero después de cada liquidación.
Estamos proponiendo upto para Stellar dentro del estándar x402, para que cualquier facilitador lo use igual (PR abierto, x402-foundation/x402#3098)
Solo testnet. Periplo no opera en mainnet todavía.
01
Cómo funciona
Un servicio responde HTTP 402 con su precio. El comprador firma un pago; Periplo lo verifica y lo envía a Stellar. Dos esquemas cubren dos formas de cobrar.
upto: pagar el uso real
- El comprador firma un techo de gasto una sola vez.
- El servicio mide lo que realmente se usó.
- Solo se liquida el monto real; el contrato devuelve el resto en la misma transacción.
Para uso que solo se conoce después: tokens generados, segundos de acceso, filas devueltas.
Quién controla los fondos
El comprador firma cada pago con su propia llave. El facilitador solo paga comisiones de red, se niega a arrancar con una llave que pueda mover fondos de usuarios, y nunca es origen ni firmante del pago de un comprador.
Leer el modelo de amenazasDescubrimiento incluido
Los recursos que se liquidan a través de Periplo pueden catalogarse para que los agentes los encuentren buscando, sin conocer la URL de antemano.
Dónde corre upto hoy
upto liquida contra el contrato UptoSettlement en testnet. El facilitador público solo anuncia los esquemas que aparecen en su estado en vivo, más abajo.
02
Evidencia en testnet
Transacciones reales de stellar:testnet, cada una enlazada al explorador de bloques para que la compruebes tú.
Primer flujo completo de Periplo: un pago firmado con @x402/stellar, verificado y liquidado por el núcleo del facilitador de Periplo.
Ver transacción: 83d2aa3b60…d89f33Liquidación parcial: el comprador firmó un techo de 0.1 PTEST y el facilitador liquidó 0.04 PTEST.
Ver transacción: cc46374e34…c5d218Liquidación en cero: un techo de 0.05 PTEST liquidado en 0, con el techo completo devuelto al comprador; un replay con el mismo nonce fue rechazado.
Ver transacción: 2138c0418a…03d358Primer pago a través de Periplo entre un vendedor externo y un comprador independiente, ninguno de los dos este proyecto, en USDC de testnet.
Ver transacción: 4befe51d2c…7904fdInteroperabilidad: un pago construido con el mismo código cliente, verificado y liquidado por el facilitador de referencia independiente de x402.org.
Ver transacción: 43bd169873…dc7c8fCuatro liquidaciones concurrentes en el mismo ledger, cada una desde una cuenta distinta del pool de channel accounts.
Ver transacción: 33a6791890…0b3764API medida: un techo de 0.1 PTEST para hasta 20 filas; se devolvieron 10, así que se liquidaron 0.05 PTEST y el resto se reembolsó.
Ver transacción: cf33b51350…533823El mismo contrato, en USDC de testnet: un techo de 0.10 USDC y 0.05 USDC liquidados, con el resto reembolsado. El activo viaja dentro de cada autorización firmada, así que el contrato no se volvió a desplegar.
Ver transacción: d554adfb8f…c5cafb
06
Librería cliente
periplo es el paquete de npm detrás de estos ejemplos: firma un techo upto como comprador, o anúncialo y liquida el uso real como vendedor.
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 decimales
});
const response = await payAndFetch(resourceUrl, payer);03
Estado en vivo del facilitador
Se lee de los endpoints /supported y /status del despliegue público cuando abres esta página. periplo-testnet.fly.dev
Consultando al facilitador…
04
Contribuciones upstream
Errores que Periplo encontró y arreglos que propuso en las librerías sobre las que se construye. El estado de cada uno viene de la API de GitHub, no de memoria.
Estado verificado contra la API de GitHub el .
Integrado: 3Cerrado como resuelto: 10Abierto: 10Cerrado sin integrar: 1Cerrado como no planeado: 1
Pull requests (9)
- Integradostellar/stellar-dev-skill#103fix: point ECOSYSTEM_CARDS copyValue at raw content, not GitHub's blob HTML page
- Integradox402-foundation/x402#3228fix(e2e): scope EVM/SVM client signer derivation to selected families
- Integradox402-foundation/x402#3336fix(stellar): include feeBumpSigner in facilitator-safety checks
- Abiertox402-foundation/x402#3098docs: add upto scheme implementation spec for Stellar
- Abiertox402-foundation/x402#3138fix(bazaar): use raw resource URL as canonical for opaque-origin schemes
Ver 4 más
- Abiertox402-foundation/x402#3215fix(core): derive one wildcard pattern per namespace, not one for the whole registration
- Abiertox402-foundation/x402#3338fix(core): enforce settlement override ceiling against PaymentRequirements.amount
- Abiertox402-foundation/x402#3339docs(stellar): cross-reference areFeesSponsored's unsupported-false limitation on the constructor
- Cerrado sin integrarstellar/js-stellar-sdk#1672fix(contract): walk every CAP-71 delegate node, not just the top level
Issues (16)
- Cerrado como resueltoOpenZeppelin/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)
- Cerrado como resueltoOpenZeppelin/stellar-contracts#863Signer::Delegated: recording-mode simulation never surfaces the delegate's signing requirement (likely explains #839's trap)
- Cerrado como resueltoStellarCN/py-stellar-base#1215authorize_entry(): sequential CAP-71 delegate signing silently invalidates an earlier signature on expiration mismatch
- Cerrado como resueltostellar/js-stellar-sdk#1681AssembledTransaction.signAuthEntries can't represent a non-master-key signer for a plain Address credential, in two separate ways
- Cerrado como resueltostellar/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
Ver 11 más
- Cerrado como resueltox402-foundation/x402#3169isValidRouteTemplate's traversal/scheme-injection checks decode routeTemplate once, so double percent-encoding bypasses both
- Cerrado como resueltox402-foundation/x402#3187[Bug]: e2e client eagerly derives EVM+SVM signers regardless of --families, crashing single-family conformance runs
- Cerrado como resueltox402-foundation/x402#3270HTTPFacilitatorClient.settle()/verify() discard the EXTENSION-RESPONSES header instead of returning it
- Cerrado como resueltox402-foundation/x402#3332@x402/stellar: feeBumpSigner documented as a facilitator address by getSigners() but excluded from every facilitator-safety check
- Cerrado como resueltox402-foundation/x402#3334@x402/core: settlePayment() settlement-override resolution never enforces its own documented ceiling against PaymentRequirements.amount
- Abiertostellar/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
- Abiertox402-foundation/x402#3121[Bug]: extractDiscoveryInfo builds a broken canonical URL for mcp://tool/{toolName} resources
- Abiertox402-foundation/x402#3172x402Facilitator.derivePattern() silently drops wildcard coverage when a single facilitator registers networks from multiple CAIP-2 namespaces
- Abiertox402-foundation/x402#3333@x402/stellar: areFeesSponsored: false accepted with no validation, silently breaks 100% of settlements against the official client
- Abiertox402-foundation/x402#3341Spec: batch-settlement on Stellar needs a different voucher-signing mechanism than upto (require_auth caps expiration at 180 days)
- Cerrado como no planeadostellar/js-stellar-sdk#1699XdrLargeInt.toU128()/.toU256()/.toU64() silently wrap negative values instead of throwing RangeError
05
Código abierto
Todo Periplo es público bajo Apache-2.0: el facilitador, el catálogo de descubrimiento, los contratos y este sitio.