Sub-accounts

A sub-account is a deterministic smart account derived from the user’s main account, scoped to a single application. Sub-accounts allow:

Session keys with limited authority.
Per-application spending limits.
Project-scoped activity history without polluting the user’s main account.

List sub-accounts

const { subAccounts } = await provider.request<{ subAccounts: SubAccount[] }>({
  method: 'wallet_getSubAccounts',
})

Returns the array of sub-accounts the current application has previously created for the connected user. Empty if none.

Add a sub-account

const subAccount = await provider.request({
  method: 'wallet_addSubAccount',
  params: [
    {
      version: '1',
      account: { type: 'create' },
    },
  ],
})

The popup asks the user to confirm sub-account creation. Returns { address, chainId?, factory?, factoryData? }.

Send a transaction from a sub-account

To sign a transaction with the sub-account instead of the main smart account, send a wallet_sendCalls request with the from field set to the sub-account address. Gas is sponsored by Startale, so no paymasterService capability is needed.

import { numberToHex } from 'viem'

const { id } = await provider.request({
  method: 'wallet_sendCalls',
  params: [
    {
      version: '1',
      from: subAccountAddress,
      chainId: numberToHex(1868), // Soneium Mainnet
      atomicRequired: true,
      calls: [
        {
          to: '0xRecipient...',
          data: '0x',
          value: '0x0',
        },
      ],
    },
  ],
})

The popup shows the sub-account address as the signer and the user approves once. The SDK takes care of the underlying signing flow, sub-accounts are themselves smart accounts, and the SDK auto-deploys the sub-account on first use if it has not been deployed yet on the target chain.

Sub-accounts share the user’s authentication. They cannot exist without a connected main account.

When to use sub-accounts

Situation	Use a sub-account?
Standard one-shot transactions	No, use the main account.
Long-running session with frequent signing	Yes, reduces popup fatigue.
Per-application spending caps or allowlists	Yes.
Cross-application identity	No. The main account is shared; sub-accounts are per-application.

Setup

Wallet

Payments

Account abstraction

List sub-accounts

Add a sub-account

Send a transaction from a sub-account

When to use sub-accounts

​List sub-accounts

​Add a sub-account

​Send a transaction from a sub-account

​When to use sub-accounts

List sub-accounts

Add a sub-account

Send a transaction from a sub-account

When to use sub-accounts