Payment paths

How a path is chosen

The referee first validates that the amount is a non-negative safe integer and the currency is a three-letter uppercase code. It then considers the actor, configured adapters, adapter readiness, and the buyer's declared machine capabilities.

• In demo mode, it chooses the simulated adapter. Demo is a mode, not a rail, and no money moves.
• For a person, it chooses a configured production adapter that supports human payment methods.
• For an agent, it requires a configured machine adapter whose declared capability matches the buyer and whose readiness is production.

valid input + compatible configured production path -> choose path
no qualifying path -> return refusal + reasons

Honest refusal

The referee does not switch actors, custody models, or environments to make a transaction appear supported. It refuses when no machine adapter is configured, the buyer did not declare a matching capability, a matching adapter is not production ready, or no production adapter supports the person's payment method. Simulated settlement is never a fallback outside demo mode.

The payment layer model

1. Outcome Receipt: the signed Spoolis record of what was earned.
2. Authorization: the buyer or payment authority decides what may be spent.
3. Execution: the buyer's wallet, marketplace, payment rail, or configured adapter moves or records value according to its own rules.

The lower-level in-band attestation is an implementation detail that supports the Outcome Receipt. Spoolis does not become the wallet, payment provider, or settlement network. Spoolis does not operate the underlying card network, bank network, blockchain, or stablecoin.

Current production paths

Production payment execution is adapter-based. Availability depends on the account, participants, and configured capabilities.

• Card settlement (Stripe): a capped manual-capture authorization; the adapter acts on the verification result under Stripe's rules.
• Onchain wallet authority (Base mainnet, USDC), direct mode: after the verdict, the principal signs exact EIP-3009 payloads for the earned amount and quoted fee. The principal stays online for this step. Spoolis never takes possession of funds.
• Onchain wallet authority (Base mainnet, USDC), unattended mode: a per-Spool principal-signed spend permission lets the immutable OutcomeSettlement contract pull and forward exactly the attested earned amount and quoted fee. The contract has no owner, admin, pause, or upgrade path and is not designed to retain a balance.

See wallet authority for setup, bounds, expiry, and revocation.

Paying Spoolis for verification

Credits are optional. Direct x402 verification requires no account, API key, or prepaid balance.

• Pay per verification (x402): send a one-shot verification to POST /api/v1/verify/x402. The response is an x402 V2 challenge for Base mainnet USDC; sign it, retry with the payment, and the signed Outcome Receipt comes back in the same call. No account, API key, or prepaid balance is required. A successful paid call returns HTTP 201 with the receipt in the body, so treat any 2xx status as success. If the paid retry times out or returns an ambiguous result, replay the same signed payment: replays of the same settlement are idempotent and return the same receipt. Never sign a fresh authorization to retry, because a fresh signature is a second real payment.
• Credits (optional): a prepaid usage balance for account-based use. Useful for teams, predictable billing, and fewer microtransactions. Every paid run is quoted before it starts and the free monthly allowance is used first.
• MPP: agents can top up the usage balance over MPP where that lane is enabled.

Three separate money concepts apply, and only the first is what you pay to run a verification:

• Verification usage fee: the per-run fee, paid from the allowance, the usage balance, or a direct x402 payment. It is never taken out of settlement.
• Settlement commission: a separate quoted fee on some full Spools, shown in the transaction quote before anyone commits. On the wallet (CDP) lane it is collected at settlement.
• Seller settlement: independent from how you pay Spoolis. Funds remain with the buyer until a verified Outcome allows settlement under the configured payment path.

Buying usage credits

Usage credits are separate from settlement for a Spool. An account owner can use Stripe Checkout. An agent can buy a $5, $10, or $20 pack through MPP when that lane is enabled, or through the live x402 credit-pack endpoint with Base mainnet USDC.

For x402, send an API-key-authenticated POST /api/v1/credits/packs/x402, read the x402 V2 requirement from PAYMENT-REQUIRED, and sign one accepted EIP-3009 TransferWithAuthorization requirement using the live USDC EIP-712 domain USD Coin, version 2. Retry with the key in X-Api-Key and the signed payload in PAYMENT-SIGNATURE. After the 202 payment_accepted response, poll GET /api/v1/credits/balance. The usage balance updates when the facilitator confirms settlement, usually within seconds.

Fees

The quoted Spoolis fee on a full Spool is quoted before work and does not change with partial outcomes. Partial outcomes change the seller's earned value only.

On the wallet (CDP) lane, the quoted fee is collected on settlement.

Payment and network costs are passed through and are separate from the Spoolis fee.

How payment acts on the result

External systems can verify or read the Outcome Receipt and act on the result themselves. Where supported, configured adapters may automate execution. Unsupported flows fail closed, with no silent substitution of another payment rail.