Spoolis docs

Wallet authority

Use your own principal account and credentials to grant bounded, expiring, and revocable authority for production settlement.

View as Markdown

You keep your signing key. The permission grants Spoolis bounded, expiring authority to settle verified outcomes, and you can revoke it.

Spoolis never receives the principal's signing key or payment credentials. Your principal account grants a specific onchain spend permission to the configured spender.

How the authority is bounded

The Base SpendPermissionManager permission identifies the principal account, spender, USDC token, allowance, period, start time, end time, salt, and extra data. Settlement refuses when no matching active permission exists or when the earned amount exceeds the remaining allowance.

The Wallet tab derives and shows the current allowance, period, and expiry from the loaded grant setup. These are current setup defaults, not permanent limits. Read the values shown in Settings, Wallet each time you create a permission.

The Spoolis verification fee is quoted before work and collected on settlement. Network or third-party wallet fees may still apply.

Outcome settlement modes

Outcome settlement exposes one product rail with two recorded execution modes. Both modes are live on Base mainnet. The mode is selected when settlement is authorized and does not change later.

Direct after the verdict

A buyer runtime that declares direct_signer: principal_runtime receives two exact USDC EIP-3009 payloads after verification. It signs the seller and fee legs, then submits both signatures to the Spool endpoint. The seller leg is submitted first. A confirmed seller leg releases the Spool even if the fee leg is still pending. Spoolis retries only the same fee authorization while it remains valid. After it expires, the Spool read response requests a fresh fee signature and does not request or resend the seller leg.

Unattended after a per-Spool grant

A per-Spool SpendPermission binds the principal, seller, token, network, cap, expiry, fee recipient, fee maximum, agreement hash, settlement contract, and contract attestor. The adapter can submit only the verified earned amount and quoted fee within those bindings.

The settlement contract is immutable: it has no owner, no admin functions, no pause, no upgrade path, and no arbitrary withdrawal. It pulls and forwards exact amounts and is not designed to retain a USDC balance after a successful settlement.

Who can hold a per-Spool grant

The principal must be a deployed Coinbase Smart Wallet with the Spend Permission Manager as an owner. The wallet must expose isOwnerAddress(address). The template and authorization paths run this preflight and return a specific error for an externally owned account, an unsupported Coinbase Smart Wallet, or a wallet where the Spend Permission Manager is not an owner.

Per-Spool grant template

Request GET /api/v1/spools/{id}/settlement/grant/template with the buyer's full-scope API key. Sign the returned SpendPermission EIP-712 payload exactly. Submit the complete struct with either its signature or an existing approval transaction hash to POST /api/v1/spools/{id}/settlement/grant. Read it later with GET /api/v1/spools/{id}/settlement/grant.

Set up a production wallet

Complete these steps in the Wallet tab under Settings. Moving to production is an account status change, not a separate integration. Your account must be production-enabled before the production settlement path can be used.

1. Register a principal

Enter the public smart account address that will own the permission. The product registers it for your account through POST /api/account/principal. It must match the configured production network.

2. Grant bounded authority

Select Load grant setup. The Wallet tab shows the configured network, spender, SpendPermissionManager, USDC token, allowance, period, and expiry, plus a guided CDP snippet. Run that snippet in your own environment with your own credentials. Do not send credentials or private keys to Spoolis.

3. Verify status

Select Check permission status. The product calls GET /api/account/spend-permission and shows matching permissions, the amount spent in the current period when available, expiry, and revocation status. A production commit still requires the account enablement status.

Two independent ways authority ends

Expiry

Every permission has an onchain end time. Once that time passes, the authority cannot be used. Expiry is an automatic backstop: authority cannot persist indefinitely, including if Spoolis is unavailable.

Revocation

In Settings, Wallet, select Revoke. The product submits POST /api/account/spend-permission/revoke, and the configured spender submits the onchain spender-side revocation.

The permission is revocable by your principal account onchain (SpendPermissionManager.revoke with the complete permission struct); the practical path depends on your wallet setup. Spoolis publishes the exact call. Use the same account and permission values that created the grant. Revocation ends future authority. It does not reverse a transaction already submitted or completed.

revocation-boundary.txt

expiry: onchain end time passes -> authority cannot be used
service revoke: POST /api/account/spend-permission/revoke -> spender-side onchain revoke
principal-account revoke: SpendPermissionManager.revoke with the complete permission struct; practical path depends on wallet setup

Provider-independent owner revocation

The exact manager call is SpendPermissionManager.revoke(permission), where permission is the complete nine-field struct returned by the grant read endpoint. A generic ERC-4337 wallet sends that calldata through the principal smart account's execute(manager, 0, calldata) function. Use an owner credential, a public bundler, and a self-funded smart account. This path needs no CDP or Spoolis credential.

terminal

node scripts/revoke-spend-permission.mjs --permission permission.json --owner-key $OWNER_PRIVATE_KEY --bundler-url https://your-public-bundler.example --rpc-url https://your-base-rpc.example --entry-point 0x...
# The CLI refuses to run while any CDP_* environment variable is set.

You can also use any ERC-4337 wallet interface that lets an owner call the manager's revoke function with the full struct.

Account routes

POST /api/account/principal registers or replaces the signed-in account's principal.
GET /api/account/spend-permission reads the signed-in account's stored and onchain permission status.
POST /api/account/spend-permission/revoke requests spender-side revocation for a permission owned by the signed-in account.

See API troubleshooting for production wallet refusal messages and remediation.