> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.shredpay.xyz/agent-wallet/concepts/sub-wallets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.