Skip to main content

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.

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: 
{
  "mcpServers": {
    "finance-district": {
      "type": "streamable-http",
      "url": "https://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 RoleSuggested FundingRefill Strategy
Research / data buying$10–50Per session
API access payment$50–200Weekly
Active trading$500–2,000Based on performance
Payment processingTask-appropriatePer 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.
Last modified on April 2, 2026