Machine payment guide
Working with machine payment protocols: MPP and x402
Use a signed Outcome Receipt as the verification boundary beside MPP or x402, while keeping buyer authorization, protocol state, and settlement separate from the result Spoolis signs.
Start with the Outcome Receipt
MPP and x402 describe payment mechanics. They do not decide whether delivered work met the agreement. Spoolis runs the verification plan first and, when signing is configured and the result is determinate, issues a signed Outcome Receipt with the outcome and amount earned.
For unitized work, the receipt can include total, accepted, and rejected units, the per-unit earning rule, rejection summaries, and pro-rata earned value. A third party can verify the receipt for authenticity with @spoolis/receipt-verifier and pinned trust material before applying its own protocol and authorization rules.
Do not collapse the layers: a valid receipt proves that the trusted Spoolis key signed that outcome. It does not authorize a wallet, create a voucher, or prove settlement.
MPP and x402 are not general customer paths
MPP sessions and x402 batch are not general customer payment paths in Spoolis. Both are marked Labs in the rail registry. The Tempo MPP session adapter is a testnet implementation behind MACHINE_PAYMENT_LANE=true and is not wired into general adapter selection. x402 is a registry candidate without an execution adapter.
A separate allowlisted Tempo keychain pilot is implemented, but it is not MPP or x402. It uses a buyer-controlled delegated key and an exact-earned testnet transfer on Tempo Moderato. Its registry readiness does not make testnet pathUSD production money.
Integrations should begin at the receipt boundary
- Agree and verify: define the work and checks, submit evidence, and run verification.
- Read the receipt: inspect the overall result, condition results, amount earned, and any unit counts and rejection summary.
- Verify authenticity: validate schema, environment, digests, aggregation, earned-value arithmetic, key identity, and Ed25519 signature with a pinned trust set. This proves the receipt is genuine and unaltered, not that every underlying check is reproducible or that the evidence reflects real-world truth.
- Apply buyer policy: check replay, identity, amount, authorization scope, protocol state, and any online corrected or revoked status your integration requires.
- Execute through the payment system: let the buyer-side runtime create or update the payment instruction that the selected machine-payment system supports.
The current built-in settlement flow automatically executes only an overall pass. It holds partial, fail, and uncertain results. If an external MPP or x402 integration wants to settle the pro-rata amount in a partial unitized receipt, that integration must implement and authorize that behavior itself.
The MPP adapter opens, presents, and releases testnet sessions
The implemented MPP session adapter requires a buyer-owned authority for Tempo Moderato testnet, testnet pathUSD, a USD-equivalent amount from $0.01 through $5.00, and the enabled feature flag.
Authorization opens and verifies a session with enough capacity. On an overall pass, the adapter requires a buyer-supplied voucher whose cumulative amount exactly equals the Spool amount, presents it, and checks that the returned testnet settlement receipt matches. Partial, fail, and uncertain outcomes hold. Cancellation or expiry asks the buyer authority to release the session.
The buyer authority must remain available for presentation or release. The adapter rejects session references, vouchers, or receipts that do not belong to that authority.
The x402 entry models a candidate, not an endpoint
The x402 batch registry entry describes a Labs candidate with agent support, cumulative vouchers, batch settlement, sub-cent accounting, stable-value assets, and a protocol-contract custody model. The policy layer can recommend it for agent work with at least 20 expected increments.
There is no x402 execution adapter in lib/settlement. Treat the registry entry as a modeled candidate, not an endpoint. An x402 capability declaration can explain a match or mismatch in the referee, but the Labs readiness still causes general production routing to refuse it.
What to read next
Read how Spoolis routes a payment for selection, when Spoolis decides and when you decide for authority, and the settlement-path comparison for lifecycle details. Use payment paths for the compact routing model.