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 — auth and limits

• Multi-chain — how one address spans six chains

• Address Screening — automatic OFAC checks on every counterparty