Skip to main content

​
Wallet Architecture

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.
The EOA wallet is your starting point and remains functional even after you deploy a Smart Account. It becomes the owner of the Smart Account contract.

​
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.
Smart Accounts are currently available to select pilot users only. If you’re interested in early access, contact us.

​
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.
Delegated wallets are currently available to select pilot users only.

​
Choosing the Right Level

Use CaseRecommendedWhy
Testing and prototypingEOAZero setup, works immediately
Single agent, standard operationsEOAMore than sufficient — most agents live here
Agent doing swaps, transfers, yieldEOAAll capabilities are available at Level 1
Batched multi-step operationsSmart AccountAtomic execution, gas savings
Gas sponsorship for agentsSmart AccountPay gas in stablecoins or sponsor from another account
Time-limited agent accessSmart AccountSession keys scope what the agent can do and when
Controlled spending budgetsDelegatedOn-chain spending limits beyond the “pocket money” approach
Enterprise with approval workflowsDelegatedMulti-party control, granular permissions
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.