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

# Multi-Wallet Strategy

> Isolate funds by purpose with separate wallets — per-role budgets, clear audit trails, and independent control.

When a single wallet handles everything — research payments, trading, and merchant settlements — you lose visibility into what's spending what, and a bug in one function can drain funds meant for another. The solution: assign a **separate wallet to each role**.

Each wallet is its own District Pass account, running in its own agent instance. One user orchestrates them all, but each wallet is isolated on-chain.

## Why Separate Wallets?

1. **Blast radius containment** — a misbehaving role can only burn its own wallet, not others
2. **Clear audit trail** — every transaction is attributed to a specific wallet address and role
3. **Per-role budgets** — fund each wallet according to its purpose and risk
4. **Independent control** — pause, drain, or shut down one wallet without touching the rest

A shared wallet makes it impossible to attribute spending, enforce budgets, or contain damage.

## Architecture Patterns

### By Role

Different wallets for different purposes. Each wallet is funded and monitored independently.

```
Research role    → Wallet A ($50)    — buys data, pays APIs
Trading role     → Wallet B ($500)   — executes swaps
Payments role    → Wallet C ($200)   — settles merchant invoices
```

**Best for:** An agent (or set of agents) that handles multiple financial functions with different risk profiles.

### By Responsibility

One workflow, multiple wallets scoped by what each part of the workflow needs to do.

```
Analyst wallet   → read-only (balance checks, no funds needed)
Executor wallet  → $1,000 (swaps and transfers)
Reporter wallet  → read-only (no funds needed)
```

**Best for:** Complex workflows where different steps need different financial capabilities.

### By Scale

Many identical instances doing the same task in parallel, each with its own wallet.

```
Worker 1  → Wallet ($50)
Worker 2  → Wallet ($50)
Worker 3  → Wallet ($50)
...
Worker N  → Wallet ($50)
```

**Best for:** Parallel processing where each instance independently buys data, pays for API access, or executes trades.

## Setting Up Multiple Wallets

Each wallet requires its own **District Pass account**. A single CLI or MCP session authenticates one account at a time, so each wallet runs in a **separate instance** — a separate container, process, or machine.

### MCP Configuration

Every instance uses the same MCP server URL but authenticates with its own District Pass via OAuth PKCE:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "mcpServers": {
    "finance-district": {
      "type": "streamable-http",
      "url": "https://wallet-mcp.fd.xyz"
    }
  }
}
```

Each instance maintains its own OAuth session. Wallets are fully isolated — one instance cannot access another's funds.

<Warning>
  You cannot sign into multiple District Pass accounts within a single CLI or MCP session. Each wallet must run in its own process or environment.
</Warning>

## Budget Management

Apply the [pocket money philosophy](/agent-wallet/concepts/trust) per wallet:

| Wallet Role            | Suggested Funding | Refill Strategy      |
| ---------------------- | ----------------- | -------------------- |
| Research / data buying | \$10–50           | Per session          |
| API access payment     | \$50–200          | Weekly               |
| Active trading         | \$500–2,000       | Based on performance |
| Payment processing     | Task-appropriate  | Per batch            |

**Fund individually.** Each wallet gets only what its role needs.

**Refill rather than pre-fund.** Keep balances low and refill when needed. Each refill is a checkpoint to review activity.

**Monitor on-chain.** Check each wallet address on a block explorer to review spending patterns.

## Monitoring

Each wallet has its own on-chain address, making monitoring straightforward:

* **Per-wallet activity** — look up each address on the relevant block explorer
* **Balance tracking** — check balances via MCP, CLI, or block explorer
* **Spending patterns** — review transaction history to verify each role is operating within expectations

For scaled deployments, script balance checks across all wallets:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
#!/bin/bash
WALLETS=("wallet-research" "wallet-trading" "wallet-payments")
for wallet in "${WALLETS[@]}"; do
    echo "=== $wallet ==="
    fdx wallet getWalletOverview --chainKey ethereum
done
```

## Scaling Considerations

**Start small.** Set up one or two wallets, validate the workflow, then add more.

**Same code, different credentials.** For scaled patterns, each instance runs identical code — the only difference is the District Pass it authenticates with.

**Graceful shutdown.** Before decommissioning a wallet, withdraw remaining funds. The wallet and its on-chain history remain accessible even after the instance stops.