> ## Documentation Index
> Fetch the complete documentation index at: https://docs.startale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-accounts

> Create per-application sub-accounts for the user's smart account. Useful for session keys and scoped permissions.

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

```ts theme={null}
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

```ts theme={null}
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.

```ts theme={null}
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.

<Note>
  Sub-accounts share the user's authentication. They cannot exist without a connected main account.
</Note>

## 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. |