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

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',
  // Set up Sub Account support with a signer function
  toSubAccountSigner: 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

// 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

// 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

You can add owners to a Sub Account by providing either an address or a public key.

// 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 created, you can use it to sign and send transactions:

// 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,
  toSubAccountSigner: () => 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.setSigner(toSubAccountSigner)

Sets the signer function for Sub Account operations.

Parameters:

• toSubAccountSigner: Function that returns a Promise resolving to a signer object

Technical Details

Sub accounts are implemented as smart contract wallets that support multiple owners. The SDK provides a wrapper around the low-level RPC methods used to interact with these accounts:

• wallet_addSubAccount: Creates a new Sub Account
• wallet_connect: Connects to an existing Sub Account
• wallet_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