Overview
Smart accounts (ERC-4337) are smart contract wallets that unlock account abstraction features for your users:- Batch multiple calls in a single action
- Optional gas sponsorship via paymasters (gasless UX)
If you’re new to Embedded Wallets, start with the Quickstart and React Hooks first.
Embedded Wallets do not support the Policy Engine. Embedded Wallets can use Paymaster allowlists today; Smart Account spend permissions are coming soon.
Prerequisites
- A CDP Portal account and project
- Node.js 22+ and a package manager (npm, pnpm, or yarn)
- Basic familiarity with React and TypeScript
- A CDP project with Embedded Wallets enabled
- Your app domain allowlisted
@coinbase/cdp-core
and@coinbase/cdp-hooks
installed
Enable smart accounts
Configure theCDPHooksProvider
to create a smart account for new users on sign in.
- When
ethereum.createOnLogin
is set to"smart"
, new users receive both an EOA and a smart account.
basePath
(API base URL override)useMock
(local mock mode)debugging
(verbose logging)
Access the user’s smart account
UseuseCurrentUser
to access the authenticated user’s accounts. The first smart account is available as currentUser.evmSmartAccounts?.[0]
.
useEvmAddress()
to get the primary EVM address; it returns the smart account if one exists, otherwise the EOA.
Send a user operation
Smart accounts submit ERC-4337 user operations rather than standard EOA transactions. UseuseSendUserOperation
to submit one or more calls. This hook returns status
, data
, and error
values which you can use to track the status of the user operation.
For gas sponsorship with a Paymaster, either set
useCdpPaymaster: true
(uses the CDP Paymaster on Base) or provide a custom paymasterUrl
.Batch calls
Provide multiplecalls
to batch actions in a single user operation. Calls execute in order and revert atomically on failure.
Encode contract calls
To interact with contracts, passdata
using an ABI-encoded payload. This example encodes an ERC-20 transfer
using viem
:
Gas sponsorship with paymaster
Use a paymaster to sponsor gas so users can transact without holding ETH.- Add
paymasterUrl
tosendUserOperation
- Or set
useCdpPaymaster: true
to use the CDP Paymaster
Spend permissions APIs for Embedded Wallets are coming soon.Questions? Contact us in the #embedded-wallets channel on Discord.
Reference
Resource | Description |
---|---|
useCurrentUser | Get the current authenticated user |
useEvmAddress | Primary EVM address (Smart Account if present, else EOA) |
useSendUserOperation | Send a user operation; hook returns status/data |
sendUserOperationOptions | Options for sending a user operation |
sendUserOperationResult | Result fields for sendUserOperation |
ethereum.createOnLogin | Config: “eoa” or “smart” |
User type | user.evmAccounts[] , user.evmSmartAccounts[] |
Hooks README | Package overview and usage |