Overview
By default, when a user uses their Base Account within their app, the user must authorize every signature and transaction via a passkey prompt. This may be interruptive for your app’s user experience, particularly for use cases that require a high-volume of signatures or transactions, such as gaming. Sub Accounts enable you to create an Ethereum account derived from the parent Base Account that is specific to your app, with its own address, signing capabilities, and transaction history. This Sub Account is owned by another wallet, such as an embedded wallet or a local account, and can be configured to not require an explicit (passkey) confirmation from the user on every signature and transaction. Sub accounts can even transact with the balance of the parent account using Spend Permissions, allowing users to spend this balance without explicit passkey prompts.Usage
To set up Sub Accounts in your app that can be controlled by an embedded wallet, follow the guide below.1. Set up your React app
First, follow the React Quickstart to get your app instrumented with Privy’s basic functionality. Make sure you have updated your@privy-io/react-auth
SDK to the latest version.
Next, configure your React app to:
- Show the Base Account as one of the external wallet options that users can use to connect to your application. To do so, pass
'base_account'
to theconfig.appearance.walletList
array. - Create embedded wallets automatically on login by setting
config.embedded.ethereum.createOnLogin
to'all-users'
.
2. Create or get a Sub Account
Next, after the user logs in, create a new Sub Account or get the existing Sub Account for the user that is tied to your app’s domain. To start, get the connected wallet instances for your user’s embedded wallet and Base App by searching for the entries withwalletClientType: 'privy'
and walletClientType: 'base_account'
respectively in your useWallets
array:
wallet_getSubAccounts
RPC method. If the user does not have an existing Sub Account, create a new one for them using the wallet_addSubAccount
RPC:
3. Configure the SDK to use the embedded wallet for Sub Account operations
Next, configure the Base Account SDK to use the embedded wallet to control Sub Account operations. This allows the embedded wallet to sign messages and transactions on behalf of the Sub Account, avoiding the need for a separate passkey prompt. Use theuseBaseAccountSdk
hook from Privy’s React SDK to access the instance of the Base Account SDK directly, and use the SDK’s subAccount.setToOwnerAccount
method to configure the embedded wallet to sign on behalf of the Sub Account’s operations.
As a parameter to this method, pass a function that returns a Promise
for a viem LocalAccount
representing the user’s embedded wallet. You can use Privy’s toViemAccount
utility method to do so.
4. Sign messages and send transactions with the Sub Account
Lastly, you can sign and send transactions with the Sub Account using the Base Account’s EIP1193 provider. To ensure that signatures and transactions come from the Sub Account, for each of the following RPCs:personal_sign
: pass the Sub Account’s address, not the parent Base Account’s address, as the second parameter.eth_signTypedData_v4
: pass the Sub Account’s address, not the parent Base Account’s address, as the first parameter.eth_sendTransaction
: setfrom
in the transaction object to the Sub Account’s address, not the parent Base Account’s address.
You can combine Sub Accounts with Spend
Permissions to allow the Sub
Account to spend from the balance of the parent Base Account in
eth_sendTransaction
requests.