Spoolis

Machine payment guide

Working with machine payment protocols: MPP and x402

Use a signed Outcome Receipt to show what verification found beside MPP or x402. Keep buyer authorization, protocol state, and settlement separate from the result Spoolis signs.

Updated August 25, 2026

Start with the Outcome Receipt

MPP and x402 describe how a machine payment works. They don't decide whether the delivered work met the agreement. Spoolis runs the verification plan first and, when signing is configured and the result is definite, signs an Outcome Receipt with the outcome and amount earned.

For unitized work, meaning work counted as separate units, the receipt can include total, accepted, and rejected units, the per-unit earning rule, rejection summaries, and pro-rata earned value. Pro-rata means the share earned by the units that passed. You can check the receipt's authenticity with @spoolis/receipt-verifier and pinned trust material before applying your 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.

Agents can buy Spoolis credits with x402 today

The x402 credit-pack lane is live and separate from Spool settlement. An agent authenticates POST /api/v1/credits/packs/x402 with its Spoolis API key. The first request returns a 402 challenge in PAYMENT-REQUIRED. The agent decodes the x402 V2 requirements and signs one accepted Base mainnet USDC requirement as an EIP-3009 TransferWithAuthorization, using the token's advertised live EIP-712 domain USD Coin, version 2.

The agent retries the pack request with its Spoolis key in X-Api-Key and the signed payload in PAYMENT-SIGNATURE. A 202 response reports payment_accepted after the facilitator confirms settlement. The agent then polls GET /api/v1/credits/balance before retrying the operation that needed credits. The usage balance updates when the facilitator confirms settlement, usually within seconds.

Keep the two x402 roles distinct: x402 is live for buying Spoolis usage credits. The x402 batch entry described below remains a Labs candidate for settling the value earned by a Spool, and it has no execution adapter.

Integrations should begin at the receipt boundary

  1. Agree and verify: define the work and checks, submit evidence, and run verification.
  2. Read the receipt: inspect the overall result, condition results, amount earned, and any unit counts and rejection summary.
  3. 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.
  4. Apply buyer policy: check replay, identity, amount, authorization scope, protocol state, and any online corrected or revoked status your integration requires.
  5. 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 captures exactly the pro-rata amount earned by a PARTIAL result. FAIL and UNCERTAIN results move nothing. An external MPP or x402 integration must implement and authorize its own settlement behavior.

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's 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 its Labs status still causes general production routing to refuse it.

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.

Working with machine payment protocols: MPP and x402 · Spoolis