> For the complete documentation index, see [llms.txt](https://developers.shredpay.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.shredpay.xyz/agent-wallet/concepts/sub-wallets.md).

# Sub-wallets

Every agent gets its own wallet — distinct from the user's main ShredPay wallet, isolated from other agents, and disposable.

## Mental model

```
ShredPay user
    │
    ├── main wallet           (user controls — receives deposits, settles payments)
    │
    └── agent sub-wallets     (one per agent / use case)
            │
            ├── sub_wallet_1   ← API key A  ← agent #1 (e.g. trading bot)
            ├── sub_wallet_2   ← API key B  ← agent #2 (e.g. yield manager)
            └── sub_wallet_3   ← API key C  ← agent #3 (e.g. read-only dashboard)
```

A sub-wallet is a real on-chain address. It has its own balances and signs its own transactions.

## Properties

| Property    | Notes                                                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Address** | One EVM address used across all six supported chains. Returned by `GET /api/wallet/address`.                                         |
| **Owner**   | The ShredPay user that created it. Visible only to that user in the console.                                                         |
| **Group**   | Sub-wallets are organized under a `group_id`. Today every key maps to exactly one sub-wallet.                                        |
| **Signing** | 2/2 quorum: ShredPay co-signer (P-256) + Privy. Neither party alone can move funds.                                                  |
| **Funding** | Deposit from main wallet via the console. The main → sub transfer goes through the Router contract — full amount lands, no fee skim. |

## Sub-wallet vs. API key

A common point of confusion. They are **separate** concepts:

* A **sub-wallet** is the asset container — the on-chain address.
* An **API key** is the credential that grants access to a sub-wallet.

A sub-wallet can have multiple API keys attached (e.g. one read-only key for a dashboard, one trade key for a bot — both pointing at the same funds). Spend limits live on the **key**, not the wallet.

## Lifecycle

1. **Create** in the Agent Console. Pick a name and (optionally) a group.
2. **Fund** by depositing USDC from your main wallet. You can also send any ERC-20 to the address from outside ShredPay.
3. **Issue API keys** with the permissions you want.
4. **Use** via REST or MCP.
5. **Drain** when done — withdraw funds back to your main wallet from the console.
6. **Archive** — once empty, the sub-wallet can be archived. Archived wallets stop accepting new transactions.

## What sub-wallets do **not** do

* They do not gate which DeFi protocol or which token an agent can interact with. That's the agent's choice. Use **screening** and **per-key limits** for those controls.
* They do not enforce any business policy beyond key-level limits and chain whitelists.

## Related

* [API Keys](/agent-wallet/concepts/api-keys.md) — auth and limits
* [Multi-chain](/agent-wallet/concepts/multi-chain.md) — how one address spans six chains
* [Address Screening](/agent-wallet/concepts/address-screening.md) — automatic OFAC checks on every counterparty