Multi-Wallet Strategy

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?

Blast radius containment — a misbehaving role can only burn its own wallet, not others
Clear audit trail — every transaction is attributed to a specific wallet address and role
Per-role budgets — fund each wallet according to its purpose and risk
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:

{
  "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.

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.

Budget Management

Apply the pocket money philosophy 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:

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

Getting Started

Concepts

AI Integration

Advanced

Resources

Why Separate Wallets?

Architecture Patterns

By Role

By Responsibility

By Scale

Setting Up Multiple Wallets

MCP Configuration

Budget Management

Monitoring

Scaling Considerations

​Why Separate Wallets?

​Architecture Patterns

​By Role

​By Responsibility

​By Scale

​Setting Up Multiple Wallets

​MCP Configuration

​Budget Management

​Monitoring

​Scaling Considerations

Why Separate Wallets?

Architecture Patterns

By Role

By Responsibility

By Scale

Setting Up Multiple Wallets

MCP Configuration

Budget Management

Monitoring

Scaling Considerations