Skip to main content
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

SituationUse a sub-account?
Standard one-shot transactionsNo, use the main account.
Long-running session with frequent signingYes, reduces popup fatigue.
Per-application spending caps or allowlistsYes.
Cross-application identityNo. The main account is shared; sub-accounts are per-application.