Wallet Architecture

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.

Agent Wallet uses a progressive architecture: start with the simplest wallet type and add capabilities only when you need them. Most agent use cases — 90% or more — work perfectly with a basic EOA wallet. Smart Accounts and Delegated wallets exist for advanced scenarios, but you shouldn’t reach for them until your use case demands it.

​

Level 1: EOA Wallet

Every user gets an EOA (Externally Owned Account) wallet automatically when they create a District Pass — one for EVM-compatible chains and one for Solana. No deployment, no gas cost, no extra steps. An EOA is a standard blockchain wallet controlled by a private key. In Agent Wallet, that key is generated and stored inside a TEE (Trusted Execution Environment) — never exposed to the host system, never stored in environment variables. Capabilities:

• Hold tokens across all supported EVM chains and Solana
• Send and receive transfers
• Swap between token pairs
• Explore and deploy to yield vaults
• Pay Prism merchants via commerce protocols
• Full access through MCP, CLI, AI Assistant, and Web App

Best for: The vast majority of agent use cases. Testing, prototyping, production agents with moderate transaction volumes, personal wallets. Limitations: Single signer (the TEE-held key), gas must be paid individually per transaction, no programmable on-chain rules.

​

Level 2: Smart Account

A Smart Account is a lightweight ERC-4337 compatible smart contract account deployed on-chain, owned by your EOA wallet. It’s based on Alchemy’s widely-used and audited LightAccount contract. The key distinction: your EOA wallet doesn’t go away. It continues to function as before. The Smart Account is an additional on-chain account that your EOA controls as its owner. What this unlocks:

• Batch transactions — execute multiple operations in a single atomic transaction
• Gas abstraction — sponsor gas fees or pay gas in tokens other than the chain’s native token
• Session keys — grant time-limited, scoped access to specific operations
• Programmable rules — on-chain logic that governs what the account can do
• ERC-4337 compatibility — works with any platform or DeFi protocol that supports account abstraction

Deployment:

• Self-service — deploy via MCP Server, AI Assistant, or Web App
• You choose which chain(s) to deploy on (usually one or two chains where you need Smart Account features)
• Your EOA wallet must hold enough native tokens (ETH, MATIC, etc.) on that chain to pay for the contract deployment gas
• EVM only — Solana is not supported for Smart Accounts

Best for: Production agents that benefit from batched operations, gas abstraction, or session keys. Multi-step workflows where atomicity matters.

​

Level 3: Delegated Wallet

A Delegated wallet is the same Smart Account contract with additional capabilities for granular spending control. Think of it as Level 2 with fine-grained permissions layered on top. What delegation adds:

• Spending limits — cap how much an agent can spend per transaction, per day, or per time window
• Token restrictions — limit which tokens the account can interact with
• Operation scoping — restrict the types of operations allowed
• Multi-party control — require multiple approvals for high-value operations

Best for: High-value deployments, enterprise scenarios, and situations where you need precise control over what an agent is allowed to do on-chain.

​

Choosing the Right Level

The general guidance: start with EOA. If you find yourself needing batch transactions, gas abstraction, or session keys, consider a Smart Account. If you need on-chain spending controls or multi-party approval, look at Delegated.

​

How Upgrade Works

Upgrading doesn’t replace your EOA — it adds a Smart Account alongside it:

1. Your EOA wallet stays as-is — same address, same balances, same functionality
2. You deploy a Smart Account on your chosen chain(s) via MCP, AI Assistant, or Web App
3. Your EOA becomes the owner of the Smart Account contract
4. You now have two accounts: your original EOA and the new Smart Account
5. Assets on the EOA remain on the EOA — you move what you need to the Smart Account

The Smart Account has its own address on each chain where it’s deployed. You fund it by transferring from your EOA or from external sources. Moving from Smart Account to Delegated is a configuration change on the same contract — no redeployment needed.