Skip to content
Get help

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 users
  • appLogoUrl: URL to your application's logo
  • paymasterUrls: Optional configuration for gasless transactions on supported networks
  • subAccounts: Configuration for Sub Account support, including the toOwnerAccount 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 create
    • type: '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 add
    • chainId: 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:

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