Give AI agents narrowly-scoped authority without giving them permanent control of funds.
The MVP supports two models that share the same permission concepts: who can act, where, how much, how long, and how many times. Mode B permissions can also pay x402 services in USDC (see "Mode B — token permissions (x402)").
One wallet represents one mission.
Fields:
- owner
- agent
- allowedTarget
- maxSpend
- expiresAt
- used
- cancelled
Invariants:
- only the configured agent may execute
- one successful execution maximum
- only the configured target may be called
- value cannot exceed the mission budget
- execution stops after expiry
- owner can reclaim leftovers after execution or expiry
- owner can cancel an unused mission, which voids it and refunds the balance
Best for: maximum isolation between jobs.
One persistent wallet holds funds and can contain many independent permissions.
Each permission contains:
- agent
- allowedTarget
- maxSpend (cumulative)
- spent
- expiresAt
- maxUses
- uses
- revoked
- asset (
address(0)= native ETH; otherwise an EIP-3009 token such as USDC)
Invariants:
- permissions are independent
- only the permission's agent can use it
- a native permission can call only its allowed target (
execute); a token permission cannotexecute - cumulative spend cannot exceed maxSpend
- permissions can promise more than the wallet holds; a native purchase larger than the wallet's ETH balance reverts
InsufficientFunds(nothing is consumed) - uses cannot exceed maxUses
- expired or revoked permissions cannot execute or approve payments
- revoking one permission does not affect others
- the owner can withdraw ETH (
withdraw) and tokens (withdrawToken) without destroying the wallet - the owner can hand the wallet to a new owner (
transferOwnership)
Best for: agents that perform repeated jobs from a shared wallet.
A permission with a non-zero asset lets the agent pay x402 services from the wallet. x402 on EVM is a USDC
transferWithAuthorization (EIP-3009) signed by the payer; here the payer is the wallet contract, which answers ERC-1271.
allowedTargetis the only payee, oraddress(0)for any payee (the agent's screening decides who).approvePayment(permissionId, payTo, amount, validAfter, validBefore, nonce): agent only. Applies every check above (budget, uses, expiry, revoked) plus: token permission only,payTo != address(0), payee matches if pinned, a window that can settle now (validAfter < validBeforeandvalidBefore > block.timestamp, elseInvalidAuthorizationWindow),validBefore <= expiresAt, and a nonce not already approved by any permission. Spend and uses are consumed here, before any signature exists. The wallet computes the exact EIP-712 digest on-chain (from the token'sDOMAIN_SEPARATOR,from = address(this)) and records it inapprovedDigest;approvedNonce[nonce] = permissionId + 1lets a payee find the approving agent.isValidSignature(hash, signature)(ERC-1271) returns the magic value only for an approved digest. The signature bytes are ignored; callers pass more than 65 bytes so x402 facilitators take the contract-signer path.- An approval pays exactly one authorization: the digest binds wallet, payee, amount, validity window, nonce and token,
and the token's own nonce tracking plus
approvedNonceprevent replay.
Known limitations:
- An approved but unsettled authorization stays valid until
validBefore, even if the permission is revoked later (the agent caps that window at 15 minutes). - Token scoping comes only from the asset's
DOMAIN_SEPARATOR(). A token contract that returns another token's separator (say, real USDC's) makes approvals under its permission valid for that other token, beyond the other permission's budget. The owner must only whitelist genuine EIP-3009 tokens. BindingisValidSignaturetomsg.sender == assetwould close this, but it would also break off-chain ERC-1271 verification (facilitators call it viaeth_call), so it is not done.
A native (ETH) permission can carry up to 4 plugins ("hooks"): contracts implementing IPermissionHook.beforeExecute.
createPermissionWithHooks(agent, allowedTarget, maxSpend, expiresAt, maxUses, asset, hooks): owner only. Each hook is{hook, config};configis that plugin's settings for this permission. Rejected: a token permission (HooksNeedNativePermission), a hook with no code (InvalidHook), the same hook twice (DuplicateHook), more than 4 (TooManyHooks).HookAttached(permissionId, hook, config)is emitted per hook;hooksOf(permissionId)lists them.- Plugins are fixed at creation. To change the rules, revoke the permission and issue a new one.
executeorder: built-in checks and consumption (_consume), native and target checks, every plugin'sbeforeExecutein order, the merchant call. A plugin holds the purchase by reverting; the wallet wraps the reason asHookRejected(hook, reason)so a plugin can't pass off one of the wallet's own errors, and the whole purchase (including consumption) is rolled back.approvePayment(x402) does not run plugins.executecan't be re-entered (Reentered), so plugins run once per purchase.- Trust model: plugins are code the owner chose. They are called with the wallet as
msg.sender, key their state by(msg.sender, permissionId), and must not call back into the wallet.
- Config:
abi.encode(uint256 threshold)in wei. A purchase withvalue <= thresholdpasses. A larger one is held withApprovalRequired(requestKey)unless the owner approved that exact purchase. requestKey = keccak256(abi.encode(wallet, permissionId, target, value, keccak256(data))), exposed asrequestKey(...).approve(wallet, permissionId, target, value, data, validUntil): the wallet's current owner only; the plugin must be attached to that permission;validUntilat mostMAX_APPROVAL_TTL(1 day) ahead. EmitsApproved.- An approval is used once:
beforeExecutedeletes it and emitsApprovalUsed. If the merchant call then fails, the whole purchase rolls back and the approval stays. - Per purchase: the threshold applies to each purchase on its own. Splitting a large order into small ones is not caught; only the card's budget and uses bound it.
- A fake wallet can only approve requests keyed by its own address.
- An approval recorded before
transferOwnershipstays usable until it expires (at most a day), like the permission itself. The config is fixed, so a config that isn't exactly one word (owner mode) or four words (passkey mode) can never be approved; the app only builds those two shapes. - Passkey mode: config
abi.encode(threshold, x, y, rpIdHash)with the owner's passkey (P-256 public key). Then onlyapproveWithPasskey(wallet, permissionId, target, value, data, validUntil, auth)approves, andapproverevertsPasskeyRequired: the owner's account key alone can't approve. Anyone may submit the signature.authis a WebAuthn assertion (soladyWebAuthnAuth) overchallenge(...) = keccak256(abi.encode(chainid, hook, requestKey, nonces[requestKey], validUntil)); it must have user verification,authenticatorData[0:32] == rpIdHash, and a low-s signature, verified with the P-256 precompile (0x100). Each passkey approval bumpsnonces[requestKey], so a signature can't be replayed. The origin inclientDataJSONis not checked;rpIdHashbinds the passkey to one site. - The plugin's constructor requires the P-256 precompile (or solady's fallback verifier), so both demo scripts start
Anvil with
--hardfork osaka(a fork of Base Sepolia doesn't get the precompile otherwise).
MissionFactory.createMissiondeploys and funds one Mode A wallet.ReusableWalletFactory.createWalletdeploys a Mode B wallet owned by the caller.ReusableWalletFactory.createWalletFor(owner, agent, asset, maxSpend, expiresAt, maxUses)deploys a Mode B wallet for any owner with one "any payee" permission (id 0). The factory owns the wallet only within that call. It is permissionless (the demo uses it to create a wallet for a flagged owner), so it emitsWalletCreatedFor(owner, wallet, creator)rather thanWalletCreated: a UI that binds wallets to their owner by event must only trustWalletCreated.
- every execution carries a
memo(the agent's goal), emitted inExecuted - demo targets are
Merchantcontracts exposing an on-chain catalog (items()) andbuy(itemId, quantity)at exact catalog price
Create mission -> fund wallet -> agent executes -> authority consumed -> second attempt fails.
Create reusable wallet -> fund once -> create Permission A and Permission B -> agents execute independently -> revoke/exhaust one permission -> wallet and other permissions remain active.
Agent requests a paid endpoint -> 402 -> Intercepta screens payee, token and authorization -> PAY/CAP: approvePayment then the facilitator settles; HOLD: owner approves or rejects; REFUSE: nothing is signed. The service separately screens the paying wallet, its owner and its agent before it settles.