Skip to main content

​
Multi-Agent Setup

When you move beyond a single agent, each agent should have its own wallet. This guide covers architecture patterns, budget management, and operational practices for multi-agent deployments.

​
Why Separate Wallets?

Each agent gets its own wallet for four reasons:
  1. Isolation — a compromised or misbehaving agent can only affect its own wallet, not others
  2. Clear audit trail — every transaction is attributed to a specific agent’s wallet address
  3. Individual budgets — each agent gets funded according to its role and risk profile
  4. Independent control — you can pause, refund, or shut down one agent without affecting the rest
Shared wallets make it impossible to attribute spending, enforce per-agent budgets, or contain damage from a single agent’s failure.

​
Architecture Patterns

​
Independent Agents

Each agent has its own wallet and operates on its own tasks. No coordination between agents. 
Agent Alpha (research)   → Wallet A ($50)
Agent Beta (trading)     → Wallet B ($500)
Agent Gamma (payments)   → Wallet C ($200)
Best for: Different agents doing different things with different risk profiles.

​
Team of Agents

Multiple agents serve one workflow, each handling a specific role. Each has its own wallet scoped to its function. 
Analyst Agent    → Wallet (read-only balance checks)
Executor Agent   → Wallet ($1,000 for swaps and transfers)
Reporter Agent   → Wallet (no funds needed — read-only)
Best for: Complex workflows where different agents need different financial capabilities.

​
Scaled Fleet

Many identical agents doing the same task in parallel, each with their own wallet. 
Data Agent 1  → Wallet ($50)
Data Agent 2  → Wallet ($50)
Data Agent 3  → Wallet ($50)
...
Data Agent N  → Wallet ($50)
Best for: Parallel processing where each agent buys data, pays for API access, or executes trades independently.

​
Setting Up Multiple Wallets

Each wallet is tied to a District Pass. For multi-agent setups, each agent connects with its own credentials.

​
MCP Configuration

Each agent gets its own MCP connection, authenticated with its own District Pass: 
// Agent Alpha
{
  "mcpServers": {
    "finance-district": {
      "type": "streamable-http",
      "url": "https://mcp.fd.xyz"
    }
  }
}
Each agent authenticates independently via OAuth PKCE. The wallet associated with each District Pass is isolated and independent.

​
FDX CLI Configuration

For agents using the FDX CLI, each authenticates separately: 
# Agent Alpha's environment
fdx setup
# Authenticates with Agent Alpha's District Pass

# Agent Beta's environment
fdx setup
# Authenticates with Agent Beta's District Pass

​
Budget Management

Apply the pocket money philosophy per agent:
Agent 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 agent gets only what it needs. A research agent doesn’t need the same budget as a trading agent. Refill rather than pre-fund. Keep balances low and refill when needed. Each refill is a checkpoint to review the agent’s activity. Monitor on-chain. Check each agent’s wallet address on a block explorer to review spending patterns and verify the agent is operating as expected.

​
Monitoring

With each agent having its own wallet address, monitoring is straightforward:
  • Per-agent activity — look up each wallet address on the relevant block explorer
  • Balance tracking — check balances via MCP, CLI, or block explorer
  • Spending patterns — review transaction history to verify agents are operating within expectations
For fleet deployments, you can script balance checks across all agent wallets: 
#!/bin/bash
AGENTS=("agent-alpha" "agent-beta" "agent-gamma")
for agent in "${AGENTS[@]}"; do
    echo "=== $agent ==="
    fdx call getWalletOverview --chainKey ethereum
done

​
Scaling Considerations

Start small. Deploy one or two agents, validate the workflow, then scale. Identical configurations. For fleet patterns, use the same agent code with different wallet credentials. The only difference between agents should be their District Pass. Graceful shutdown. Before decommissioning an agent, withdraw its remaining funds. The wallet and its on-chain history remain accessible even after the agent stops operating.