Sub Accounts
Overview
The Coinbase Wallet SDK now supports Sub Accounts, allowing apps to create and manage additional smart contract accounts for users. Sub Accounts can have multiple owners and operate as smart contract wallets with enhanced security and flexibility.
Getting Started
Installation
npm install @coinbase/wallet-sdk@canary
Basic Setup with Sub Account Support
The following code shows how to initialize the SDK with Sub Account support. The configuration includes:
appName
: Your application's name that will be displayed to usersappLogoUrl
: URL to your application's logopaymasterUrls
: Optional configuration for gasless transactions on supported networkssubAccounts
: Configuration for Sub Account support, including thetoOwnerAccount
function that provides authentication
import { createCoinbaseWalletSDK, getCryptoKeyAccount } from '@coinbase/wallet-sdk';
// Initialize the SDK with Sub Account support
const sdk = createCoinbaseWalletSDK({
appName: 'My Dapp',
appLogoUrl: 'https://example.com/logo.png',
paymasterUrls: {
84532: 'https://<base-paymaster-url>',
},
// Set up Sub Account support with a signer function
subAccounts: {
toOwnerAccount: async () => {
// Return a signer that can be used to authenticate operations
return await getCryptoKeyAccount();
},
},
});
// Get the provider for regular wallet operations
const provider = sdk.getProvider();
Creating a Sub Account
To create a new Sub Account, you need to specify the type of account and provide the initial owner's key.
The example below shows how to create a Sub Account using WebAuthn keys,
but other types of keys are also supported as specified in the Sub Account Methods section
(i.e. address
, p256
, webcrypto-p256
, webauthn-p256
).
// Create a new Sub Account with WebAuthn keys
const account = await sdk.subaccount.create({
type: 'create',
keys: [
{
type: 'webauthn-p256',
// The public key of the owner, this can be retrieved from the account object
key: '0x7da44d4bc972affd138c619a211ef0afe0926b813fec67d15587cf8625b2bf185f5044ae96640a63b32aa1eb6f8f993006bbd26292b81cb07a0672302c69a866',
},
],
});
console.log('Sub account created:', account.address);
Getting a Sub Account
The get()
method is used to retrieve the current Sub Account. If no Sub Account exists for the current domain, it will create a new one. This method is essential for ensuring you're always working with the correct Sub Account.
// Get the current Sub Account if it exists, otherwise connect to one
const account = await sdk.subaccount.get();
console.log('Sub account address:', account.address);
Adding an Owner to a Sub Account
Sub Accounts support multiple owners, which can be added either by their Ethereum address or public key. This flexibility allows for different types of ownership models, such as:
- Adding existing Ethereum accounts as owners
- Adding WebAuthn-based owners for enhanced security
- Supporting both types of owners simultaneously
// Add an owner using an address
await sdk.subaccount.addOwner({
chainId: 84532, // Base Sepolia
address: '0xE3cA9Cc9378143a26b9d4692Ca3722dc45910a15',
});
// Or add an owner using a public key
const { account } = await getCryptoKeyAccount();
await sdk.subaccount.addOwner({
chainId: 84532, // Base Sepolia
publicKey: account.publicKey,
});
Using a Sub Account for Transactions
Once a Sub Account is set up, you can use it to perform blockchain transactions. The example below demonstrates how to sign a message using the Sub Account.
// Connect to the Sub Account
const account = await sdk.subaccount.get();
// Use the provider to send transactions from the Sub Account
const provider = sdk.getProvider();
const signature = await provider.request({
method: 'personal_sign',
params: ['0x48656c6c6f2c20776f726c6421', account.address],
});
API Reference
SDK Configuration
createCoinbaseWalletSDK({
appName: string,
appLogoUrl: string,
subAccount: {
toOwnerAccount: () => Promise<{ account: { publicKey: string; address?: string } }>,
},
});
Sub Account Methods
sdk.subaccount.create(account)
Creates a new Sub Account.
Parameters:
account
: An object with details about the account to createtype
: 'create' | 'deployed' | 'undeployed'keys
: Array of key objects (for 'create' type)type
: 'address' | 'p256' | 'webcrypto-p256' | 'webauthn-p256'key
: Hex string of the public key
Returns: Promise<SubAccountInfo>
sdk.subaccount.get()
Gets the current Sub Account, or connects to one if none exists.
Returns: Promise<SubAccountInfo>
sdk.subaccount.addOwner(options)
Adds an owner to a Sub Account.
Parameters:
options
: Object with details about the owner to addchainId
: Chain ID (number)address
: Address of the owner (optional)publicKey
: Public key of the owner (optional)
Returns: Promise<string>
- Response from the smart contract call
sdk.subaccount.setToOwnerAccount(toOwnerAccount)
Sets the signer function for Sub Account operations.
Parameters:
toOwnerAccount
: Function that returns a Promise resolving to a signer object
Ethereum JSON-RPC Provider Methods
Sub accounts are implemented as smart contract wallets that support multiple owners. The SDK provides a wrapper around the low-level Remote Procedure Call (RPC) methods used to interact with these accounts:
wallet_addSubAccount
: Creates a new Sub Accountwallet_connect
: Connects to an existing Sub Accountwallet_sendCalls
: Sends transactions from a Sub Account
Each Sub Account can have multiple owners identified by either their address or public key. When performing operations with a Sub Account, the appropriate owner is used to sign the transaction.
Requirements
- Coinbase Wallet SDK v4.4.0-canary or higher
- An app connected to an EVM-compatible chain