Overview
Spend Permissions let you designate a trusted spender that can spend tokens on behalf of your Smart Account. This enables use cases like subscription payments, agentic payments, algorithmic trading, automated payouts, and allowance management. Spend Permissions utilize the Spend Permission Manager contract deployed on Base and other networks.Use cases
- Subscription payments - Enable recurring payments for SaaS, content subscriptions, or membership fees
- Agentic payments - Delegate your actions to an agent with spending limits for autonomous operations
- Algorithmic trading - Allow trading bots to execute trades within predefined limits
- Automated payouts - Schedule regular distributions or reward payments
- Allowance management - Give team members or family controlled access to funds
How it works
There are two parties involved in a spend permission:- Account - The smart account that creates the spend permission and approves it onchain.
- Spender - The entity that can spend tokens on behalf of the account within the limits defined by a spend permission. Can be a Smart Account or a regular account.
Anatomy of a spend permission
These are the main components of a spend permission:- Spender - The entity that can spend tokens on behalf of the account.
- Token - The token that the spend permission is for, and the amount of that token that the spender is allowed to spend.
- Time period - The time period for which the spend permission is valid.
- Salt - A random value used to differentiate between spend permissions with the same parameters. The SDK will generate a random salt for you, but you can also specify your own.
- Extra Data - Arbitrary data that can be used to store additional information about the spend permission.
Spender
The spender is specified in thespender
field of the spend permission. It can be the address of any account, whether it’s a Smart Account or a regular account.
Token
The token is specified in thetoken
field of the spend permission, and the amount allowed to spend is specified in the allowance
field.
Spend permissions support both native tokens and ERC-20 tokens. When using the CDP SDK, you have two options for specifying tokens:
- Convenient shortcuts - Use
"eth"
for native ETH or"usdc"
for USDC, and the SDK will handle the conversion to the correct token address. This shortcut is only supported on Base or Base Sepolia. - ERC-20 contract addresses - For other tokens, specify the token contract address as a string (e.g.,
"0x4200000000000000000000000000000000000006"
for WETH).
allowance
field, using the smallest unit of the token. For example, if the token is ETH, the allowance is specified in wei, and if the token is USDC, the allowance is specified in the smallest unit of USDC (6 decimals).
Time period
The time period is specified using theperiodInDays
field for simple day-based periods, or the period
, start
and end
fields for more complex time controls.
The periodInDays
field provides a convenient way to specify common time periods (e.g., periodInDays: 1
for daily limits, periodInDays: 7
for weekly limits).
For more advanced control, the start
and end
fields specify when the spend permission is valid. This means that the spender can spend the amount specified in the allowance
field after the start
time and before the end
time; attempting to spend outside of this time range will fail.
The
period
field specifies a rolling window of time in seconds in which the spender can spend the amount specified in the allowance
field. This allows you specify things like “the spender can spend up to 0.00001 ETH per day” or “the spender can spend up to 100 USDC per week”.Prerequisites
Smart Accounts must have spend permissions enabled at the time of creation. You cannot create spend permissions on accounts that were created without spend permissions enabled.
If you’re new to Embedded Wallets, start with the Quickstart and React Hooks first.
CDPHooksProvider
to enable spend permissions for smart accounts:
enableSpendPermissions
is set to true
, the created smart accounts will support spend permissions functionality.
Create a spend permission
UseuseCreateSpendPermission
to create a spend permission that allows a spender to withdraw tokens from the embedded wallet within defined limits:
Creating a spend permission is a user operation that requires gas. You can use the CDP Paymaster on Base networks by setting
useCdpPaymaster: true
, or provide your own paymasterUrl
for gas sponsorship.Common patterns
Here are some common patterns for creating spend permissions:List spend permissions
UseuseListSpendPermissions
to retrieve spend permissions. The hook automatically detects and lists permissions for the authenticated user’s smart account.
The
useListSpendPermissions
hook automatically lists spend permissions for your current Smart Account.The hook accepts an optional configuration object:network
: The network to fetch spend permissions on. Defaults to “base-sepolia”pageToken
: Token for pagination to fetch the next page of results
spendPermissions
: Array ofSpendPermissionResponseObject
where each object contains:permission
: The actual spend permission detailspermissionHash
: Unique identifier for the permissionrevoked
: Boolean indicating if the permission has been revokedcreatedAt
: Timestamp when the permission was creatednetwork
: The network where the permission exists
hasNextPage
: Boolean indicating if more results are availablenextPageToken
: Token to fetch the next page of results
refetch
: Function to refresh the list of spend permissionsstatus
: Current status (“idle” | “pending” | “success” | “error”)error
: Error object if the request fails
Revoke spend permissions
UseuseRevokeSpendPermission
to revoke an existing spend permission. The hook returns status
, data
, and error
values for tracking the revocation process:
Revoking a spend permission is a user operation that requires gas. You can use the CDP Paymaster on Base networks by setting
useCdpPaymaster: true
, or provide your own paymasterUrl
for gas sponsorship.The
revokeSpendPermission
function returns:userOperationHash
: The hash of the user operation that revokes the permission
- Call
useWaitForUserOperation()
with the user operation hash to wait for the revocation to complete.
Complete example with list and revoke
Here’s a complete example that lists permissions and allows revoking specific ones:Click here to view the complete example
Click here to view the complete example
For spenders: Using permissions
Once an embedded wallet creates a spend permission, the designated spender can spend tokens using the CDP APIs as shown here Using a spend permission.Supported networks
Spend permissions are currently supported on:Testnets
Base Sepolia, Ethereum Sepolia
Mainnets
Arbitrum, Avalanche, Base, Ethereum, Optimism, Polygon
The Spend Permission Manager contract is deployed at
0xf85210B21cC50302F477BA56686d2019dC9b67Ad
on all supported networks.Questions? Contact us in the #embedded-wallets channel on Discord.
What to read next
- Smart Accounts: Learn about smart accounts and their capabilities
- React Hooks: Explore all available hooks for embedded wallets
- Paymaster: Understand gas sponsorship for user operations