# Multi-Wallet Strategy Source: https://developers.fd.xyz/agent-wallet/advanced/multi-agent Isolate funds by purpose with separate wallets — per-role budgets, clear audit trails, and independent control. 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: ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "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](/agent-wallet/concepts/trust) 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: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} #!/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. # Agent Frameworks Source: https://developers.fd.xyz/agent-wallet/ai-integration/agent-frameworks Add real crypto wallet capabilities to LangChain, CrewAI, AutoGen, and more — no MCP client required. If your framework supports MCP, connect directly to the Agent Wallet MCP server. If not, wrap the [FDX CLI](/agent-wallet/ai-integration/cli) as a shell tool. Both approaches give the same wallet capabilities. ## Integration Approaches | Framework | MCP Support | Recommended Approach | | - | - | - | | LangChain | Via MCP adapter | MCP native | | CrewAI | Via MCP adapter or shell tools | FDX CLI wrapping | | AutoGen | Via MCP adapter | MCP native | | Semantic Kernel | Via adapter | MCP native | | Custom | Depends on implementation | MCP SDK or FDX CLI | **MCP-native** is preferred when available — it gives the agent direct access to wallet tools through the standard MCP tool-calling interface. **FDX CLI wrapping** works with any framework that can execute shell commands, which covers essentially every agent framework. ## LangChain ### MCP Integration (Recommended) ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} from langchain_mcp_adapters.client import MultiServerMCPClient from langgraph.prebuilt import create_react_agent from langchain_anthropic import ChatAnthropic # Connect to Agent Wallet MCP server async with MultiServerMCPClient( { "finance-district": { "url": "https://wallet-mcp.fd.xyz", "transport": "streamable-http", } } ) as client: tools = client.get_tools() agent = create_react_agent( ChatAnthropic(model="claude-sonnet-4-20250514"), tools ) result = await agent.ainvoke( {"messages": [{"role": "user", "content": "Check my wallet balance"}]} ) ``` ### FDX CLI Tool Wrapper ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} import subprocess import json from langchain.tools import tool @tool def wallet(method: str) -> str: """Execute an FDX wallet command. Pass an MCP method name and arguments. Example: 'getWalletOverview --chainKey ethereum' Run 'fdx wallet' for available methods.""" result = subprocess.run( ["fdx", "wallet"] + method.split(), capture_output=True, text=True ) return result.stdout # Use in an agent agent = create_react_agent(llm, [wallet]) ``` ## CrewAI ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} from crewai import Agent, Task, Crew from crewai.tools import tool import subprocess import json @tool("Agent Wallet") def wallet(method: str) -> str: """Manage crypto wallet via FDX. Pass an MCP method name and arguments. Example: 'getWalletOverview --chainKey ethereum' or 'transferTokens --chainKey ethereum --toAddress 0x... --amount 5 --asset USDC'""" result = subprocess.run( ["fdx", "wallet"] + method.split(), capture_output=True, text=True ) return result.stdout financial_agent = Agent( role="Financial Agent", goal="Manage wallet operations and execute transactions", tools=[wallet], verbose=True ) task = Task( description="Check the wallet balance and swap 10 USDC for ETH if balance allows", agent=financial_agent ) crew = Crew(agents=[financial_agent], tasks=[task]) result = crew.kickoff() ``` ## AutoGen ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} from autogen import ConversableAgent import subprocess import json def wallet_command(method: str) -> str: result = subprocess.run( ["fdx", "wallet"] + method.split(), capture_output=True, text=True ) return result.stdout assistant = ConversableAgent( name="financial_assistant", llm_config={"model": "claude-sonnet-4-20250514"}, ) # Register wallet as a callable function assistant.register_for_llm( name="wallet", description="Execute FDX wallet commands. Pass MCP method name and arguments." )(wallet_command) ``` ## Custom MCP Client For frameworks with direct MCP support or when building your own agent: ```typescript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; async function createMcpClient() { const transport = new StreamableHTTPClientTransport( new URL("https://wallet-mcp.fd.xyz"), ); const client = new Client({ name: "my-agent", version: "1.0.0" }); await client.connect(transport); return client; } // Use in your agent logic const client = await createMcpClient(); // Check balance const result = await client.callTool({ name: "getWalletOverview", arguments: {}, }); // Transfer const transfer = await client.callTool({ name: "transferTokens", arguments: { to: "0x1234...5678", amount: "5", token: "USDC", }, }); ``` See the [MCP SDK documentation](https://modelcontextprotocol.io/docs) for full client implementation details. ## Best Practices **Use MCP when possible.** The MCP approach gives your agent richer context — tool descriptions, parameter schemas, and error details that help the LLM make better decisions. **FDX output is always JSON.** All `fdx wallet` / `fdx prism` output is structured JSON, making it straightforward for agents to parse. **Write clear tool descriptions.** The LLM uses your tool description to decide when and how to call the tool. Be specific about what each command does. **Start with small amounts.** Validate your agent's behavior with a small balance before scaling up funding. **Handle errors gracefully.** Agents should check for insufficient balance, failed transactions, and network errors — and communicate these clearly rather than retrying blindly. # Finance District CLI Skills Source: https://developers.fd.xyz/agent-wallet/ai-integration/agent-skills Give any AI agent crypto wallet and merchant payment capabilities — one skill install, zero code. The Finance District skill follows the [Agent Skills specification](https://agentskills.io/specification) and works with OpenClaw, Claude Code, GitHub Copilot, and 40+ other agentic platforms. Once installed, the skill teaches your agent how to use the [Finance District CLI](/agent-wallet/ai-integration/cli) — giving it wallet management, token transfers, DEX swaps, DeFi yield, x402 payments, and Prism merchant operations through natural language. ## Why a Skill? The skill bridges the gap between the CLI and your agent. Without it, the agent would need to figure out which `fdx` commands exist, what parameters they take, and how to chain them together. The skill provides: * **Tool discovery** — the agent knows which `fdx` commands are available and uses `--help` to learn parameters on demand * **Workflow guidance** — authentication flows, pre-operation checklists, safety confirmations before irreversible operations * **Protocol knowledge** — the full [x402 payment flow](/agent-wallet/concepts/x402-payments), including when to use `authorizePayment` vs `getX402Content` * **Two service areas** — both **Wallet** (`fdx wallet`) and **Prism** (`fdx prism`) operations in a single skill The skill is a single `SKILL.md` file with reference documents. It doesn't add runtime dependencies — it teaches the agent how to use the CLI you've already installed. ## Installation **Step 1:** Install the CLI: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} npm install -g @financedistrict/fdx ``` **Step 2:** Install the skill: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} npx skills add financedistrict-platform/fd-cli-skills ``` That's it. The skill is automatically detected when your agent encounters a relevant task. ## What the Agent Can Do Once the skill is installed, your agent handles all of this through natural language: **Wallet operations:** > "Set up my wallet" — authentication via email OTP > "Show my balance on Base" — balances across all chains > "Send 10 USDC to 0x1234...abcd on Arbitrum" — token transfers with safety confirmations > "Swap 5 USDC for ETH" — DEX swaps with quote-first flow > "Find yield strategies for my USDC" — DeFi discovery, deposit, and withdrawal > "Access the premium API at [https://api.example.com/data](https://api.example.com/data)" — x402 payments **Prism merchant operations:** > "Set up my merchant account" — onboarding and configuration > "Create a new Project" — payment acceptance setup > "Show my payment history" — earnings and settlement details The skill guides the agent to confirm with you before any irreversible operation (transfers, swaps, deposits) and to check balances before executing. ## How It Works The skill is not a wrapper or abstraction layer. It's a set of instructions that teach the agent: 1. **Check prerequisites** — is `fdx` installed? Is the user authenticated? 2. **Use `--help` liberally** — discover tool parameters dynamically rather than hardcoding them 3. **Follow safety patterns** — check balances, confirm with the human, verify chain matches recipient 4. **Handle authentication** — autonomous path (with email inbox access) or human-assisted path 5. **Consult reference docs** — deeper guidance on specific topics (x402 flow, chain capabilities, troubleshooting) loaded only when needed The agent runs `fdx` commands via bash and parses structured JSON output. All wallet operations use `fdx wallet `, all Prism operations use `fdx prism `. ## Skill vs MCP The skill and the [MCP server](/agent-wallet/ai-integration/mcp-server) provide access to the same underlying capabilities. Choose based on your agent's environment: | Approach | How it works | Best for | | - | - | - | | **Skill** | Agent runs `fdx` CLI commands via bash | Agents with shell access — Claude Code, OpenClaw, autonomous agents | | **MCP** | Agent connects to `https://wallet-mcp.fd.xyz` via MCP protocol | MCP-native clients — Claude Code, Cursor, Windsurf | Both can be used together. An agent with both the skill and MCP access has maximum flexibility. Full CLI documentation and configuration Source code and contributing guidelines # Finance District AI Assistant Source: https://developers.fd.xyz/agent-wallet/ai-integration/ai-assistant Manage your crypto by just talking to it — Finance District's AI-powered conversational wallet assistant. The AI Assistant is Finance District's conversational web interface for managing your wallet. Log in, chat in natural language, and your wallet does what you ask — no MCP configuration, no CLI installation, no technical setup. ## Getting Started 1. Go to [apps.fd.xyz](https://apps.fd.xyz) and log in with your District Pass (or sign up if you don't have an account) 2. Navigate to the AI Assistant 3. Start chatting That's it. The AI Assistant connects to the same wallet and capabilities as MCP and CLI — just through a chat interface. See the AI Assistant in action at [01:35](https://youtu.be/JObnfc-jW78?t=95) in the Agent Wallet setup tutorial — looking up wallet addresses and checking balances after a deposit. ## What You Can Do The AI Assistant supports the same wallet capabilities available through MCP and CLI: **Check your wallet:** > "What's my balance?" > "What's my wallet address on Base?" > "Show my recent transactions" **Transfer tokens:** > "Send 5 USDC to 0x1234...5678" > "Transfer 0.01 ETH to alice.eth on Ethereum" **Swap tokens:** > "Swap 10 USDC for ETH" > "How much ETH would I get for 50 USDC?" **Explore yield:** > "What yield opportunities are available for USDC?" > "Put 100 USDC into the best yield option" **Pay merchants:** > "Pay 2 USDC to merchant 0xABC...123" The assistant understands context and can handle multi-step requests: > "Check if I have at least 20 USDC, and if so, swap half of it for ETH" ## Who It's For The AI Assistant serves two audiences: **Developers exploring Agent Wallet** — use it to test wallet capabilities before integrating via MCP or CLI. It's the fastest way to see what the wallet can do without writing configuration. **Non-technical users** — manage your wallet through conversation without needing to understand MCP, command lines, or blockchain details. ## AI Assistant vs. MCP vs. CLI | Feature | AI Assistant | MCP Server | CLI | | - | - | - | - | | Setup required | None — just log in | MCP client config | npm install + auth | | Primary user | Humans | AI agents | Developers, automated agents | | Automation | No — interactive only | Yes | Yes | | Programmable | No | Yes — tool calling | Yes — scriptable | | Best for | Exploration, simple tasks, non-technical users | Primary agent integration | Scripts, agent frameworks, terminal workflows | ## Limitations The AI Assistant is an interactive web interface, not a programmable endpoint: * **Not automatable** — you can't script it or call it from code * **Not for agent integration** — use [MCP Server](/agent-wallet/ai-integration/mcp-server) or [CLI](/agent-wallet/ai-integration/cli) for that * **Session-based** — requires you to be logged in and chatting actively For autonomous agent operations, the MCP Server and CLI are the right tools. # Finance District CLI Source: https://developers.fd.xyz/agent-wallet/ai-integration/cli Run your AI agent's wallet from the terminal — hold, send, swap, and earn yield across chains. Works with OpenClaw, GitHub Copilot, and 40+ agentic platforms. FDX is a command-line interface to the Finance District MCP wallet server. It gives AI agents crypto wallet capabilities — hold, send, swap, and earn yield on assets across multiple chains — without managing private keys. FDX is built for advanced users and environments where agents have access to CLI tooling and bash — Docker containers, CI pipelines, remote servers, and scripted automation. Agents invoke `fdx wallet ` or `fdx prism ` from the command line and parse JSON output. FDX also powers the [Agent Wallet CLI Skills](/agent-wallet/ai-integration/agent-skills), which plug it directly into OpenClaw, GitHub Copilot, and 40+ other agentic platforms. * **No Key Management** — Email OTP authentication. No seed phrases. No private key files. * **Agent-Native** — Structured JSON input/output designed for tool-calling agents. * **Multi-Chain** — Ethereum, BSC, Arbitrum, Base, Solana, Bitcoin, Sui. One wallet, all chains. * **DeFi Enabled** — Transfer, swap, and earn yield through integrated DeFi protocols. For full documentation, architecture details, and development instructions, see the [FDX GitHub repository](https://github.com/financedistrict-platform/fd-agent-wallet-cli). ## Quick Start Install globally: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} npm install -g @financedistrict/fdx ``` Register a new account: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx register --email you@example.com ``` Enter the 8-digit OTP sent to your email: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx verify --code 12345678 ``` Check that authentication succeeded: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx status ``` For subsequent sessions, sign in with: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx login --email you@example.com fdx verify --code 12345678 ``` To remove stored credentials: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx logout ``` Watch this install and login flow at [09:20](https://youtu.be/JObnfc-jW78?t=560) in the Agent Wallet setup tutorial. ## Authentication FDX uses email one-time passcode (OTP) authentication via Microsoft Entra External ID. No browser is required — the entire flow runs headlessly, making it ideal for autonomous agents, Docker containers, CI pipelines, and remote servers. ### Register (first time) ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx register --email you@example.com # Check your inbox for an 8-digit OTP fdx verify --code 12345678 ``` ### Login (returning users) ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx login --email you@example.com # Check your inbox for an 8-digit OTP fdx verify --code 12345678 ``` ### Token storage Tokens are stored in the OS credential store where available: | Platform | Backend | | - | - | | macOS | Keychain (`security` CLI) | | Linux | libsecret (`secret-tool` CLI) | | Windows | DPAPI (encrypted file in `~/.fdx/`) | If no credential store is available (e.g. a minimal container), tokens fall back to plaintext in `~/.fdx/auth.json` with a `SecurityWarning` emitted. Tokens are refreshed automatically using the stored refresh token. ### Logging out ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx logout ``` Removes stored tokens from the OS credential store and clears `~/.fdx/auth.json`. ## Usage Wallet tools use the `fdx wallet` subcommand and Prism tools use `fdx prism`: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} # Check wallet overview fdx wallet getWalletOverview --chainKey ethereum # Send tokens fdx wallet transferTokens --chainKey ethereum --toAddress 0xABC... --amount 0.1 --asset USDC # Discover yield strategies fdx wallet discoverYieldStrategies --chainKey base # List Prism payments fdx prism listPayments ``` All output is JSON, making it easy for agents to parse: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx wallet getMyInfo | jq '.email' ``` Run `fdx wallet` without arguments to see all available wallet methods. Run `fdx services` to see all available services. `fdx call ` was deprecated in v0.4.0 and now exits with an error. Use `fdx wallet ` for wallet tools or `fdx prism ` for Prism tools. ## Services ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} # List all available MCP services and their URLs fdx services ``` Two services are available: | Service | Subcommand | URL | Description | | - | - | - | - | | `wallet` | `fdx wallet` | `https://wallet-mcp.fd.xyz` | Wallet tools (DeFi, transfers, X402) | | `prism` | `fdx prism` | `https://prism-mcp.fd.xyz` | Prism tools (payments, settlements) | ## Configuration FDX reads configuration from three sources, in order of precedence: 1. **Environment variables** (highest priority — see `fdx --help` for the full list) 2. **Persistent config file** at `~/.fdx/config.json` 3. **Built-in defaults** (lowest priority) ### Inspect current config ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx config ``` Prints the resolved values for Entra auth, MCP service URLs, and storage/log paths. Each value is labeled with its source — `(env)`, `(config)`, or `(default)`. ### Persist a value ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx config set ``` Writes the value to `~/.fdx/config.json`. Useful when you don't want to set an environment variable for every session — for example, pointing a long-running agent at a custom gateway URL. ### Read or remove a persisted value ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} fdx config get fdx config unset ``` ### Supported keys | Key | Description | | - | - | | `authority` | Entra External ID authority URL | | `client_id` | Entra application (client) ID | | `scopes` | OAuth scopes requested at sign-in | | `wallet_mcp_url` | Wallet MCP service URL (default: `https://wallet-mcp.fd.xyz`) | | `prism_mcp_url` | Prism MCP service URL (default: `https://prism-mcp.fd.xyz`) | | `store_path` | Token store path (default: `~/.fdx/auth.json`) | | `log_path` | Log file path (default: `~/.fdx/fdx.log`) | | `log_level` | Log verbosity — `debug\|info\|warn\|error\|off` (default: `info`) | ## Using FDX with Agent Frameworks FDX is designed to work with agent frameworks where the agent can execute shell commands. ### Tool-calling agents Most agent frameworks let you define custom tools. Wrap FDX as a shell tool: ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} import subprocess import json def wallet_command(method: str, **kwargs) -> dict: """Execute an FDX wallet command and return JSON result.""" args = ["fdx", "wallet", method] for key, value in kwargs.items(): args.extend([f"--{key}", str(value)]) result = subprocess.run(args, capture_output=True, text=True) return json.loads(result.stdout) # Check wallet overview overview = wallet_command("getWalletOverview", chainKey="ethereum") # Transfer tokens wallet_command("transferTokens", chainKey="ethereum", toAddress="0x1234...5678", amount="5", asset="USDC") ``` ### Script-based automation ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} #!/bin/bash BALANCE=$(fdx wallet getWalletOverview --chainKey base | jq -r '.balances[0].amount') echo "Current balance: $BALANCE" ``` For deeper integration patterns with specific frameworks, see [Agent Frameworks](/agent-wallet/ai-integration/agent-frameworks). ## FDX vs. MCP Server FDX and MCP server connect to the same backend and offer the same capabilities: | Aspect | MCP Server | FDX CLI | | - | - | - | | Interface | MCP protocol (tool calls) | Terminal commands (`fdx wallet` / `fdx prism`) | | Connection | MCP client → server | FDX → MCP client → server | | Best for | AI agents in MCP clients | Scripts, automation, agent frameworks with shell access | | Login | Config file in MCP client | `npm install -g` + `fdx login` | | Auth | OAuth PKCE | Email OTP (Microsoft Entra External ID) | | Output | MCP tool responses | JSON | Choose MCP when your agent or AI client supports MCP natively. Choose FDX when you need terminal access or are integrating with a framework that runs shell commands. # MCP Compatible Clients Source: https://developers.fd.xyz/agent-wallet/ai-integration/mcp-clients Give Claude, Cursor, and your favorite AI tools real crypto wallet capabilities in under 5 minutes. The Agent Wallet MCP server works with any MCP-compatible client. Pick your tool below and you'll be connected in under five minutes. **Server details for all clients:** | Property | Value | | - | - | | URL | `https://wallet-mcp.fd.xyz` | | Transport | Streamable HTTP | | Auth | OAuth PKCE (browser-based authorization) | ## Claude Desktop Claude Desktop (and Claude.ai web) currently have client-side restrictions that limit Agent Wallet MCP functionality. For the full Agent Wallet experience without restrictions, we recommend [Claude Code](#claude-code), Cursor, or any other MCP-compatible client. The configuration below is documented for completeness, but capabilities may be reduced. Edit your Claude Desktop config file: * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "mcpServers": { "finance-district": { "type": "streamable-http", "url": "https://wallet-mcp.fd.xyz" } } } ``` Restart Claude Desktop. On first connection, your browser opens for OAuth authorization. Sign in with your [District Pass](/overview/district-pass) (if you aren't already) and authorize the client to access your Finance District account. Once authorized, the connection persists across sessions. **Verify:** Ask Claude "What Finance District tools do you have?" ## Cursor Open Cursor Settings → MCP Servers → Add new server: ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "mcpServers": { "finance-district": { "type": "streamable-http", "url": "https://wallet-mcp.fd.xyz" } } } ``` Restart Cursor after saving. The browser-based OAuth flow will trigger on first connection. **Verify:** In Cursor's AI chat, ask "What Finance District wallet tools are available?" ## Windsurf Open Windsurf Settings → MCP Configuration: ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "mcpServers": { "finance-district": { "type": "streamable-http", "url": "https://wallet-mcp.fd.xyz" } } } ``` ## Claude Code Claude Code supports MCP servers directly from the command line: ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} claude mcp add finance-district --transport http https://wallet-mcp.fd.xyz ``` This only registers the server — it does **not** authenticate. `claude mcp list` will show `finance-district` as `! Needs authentication`. To complete authorization, either: * Run `/mcp` inside Claude Code, select **finance-district**, and choose **Authenticate**, or * Ask the agent to use a wallet tool — the browser OAuth flow triggers on first use. After you authorize, the status flips to `✔ Connected` and Claude Code can use wallet tools in your coding sessions. ## n8n n8n supports MCP servers as tools for AI Agent nodes: 1. Open your n8n workflow 2. Add or configure an **AI Agent** node 3. In the agent's tool configuration, add an MCP server 4. Set the server URL to `https://wallet-mcp.fd.xyz` with Streamable HTTP transport 5. Configure OAuth authorization — sign in with your District Pass when prompted The agent node can then use wallet capabilities as tools within your n8n workflows. ## Custom MCP Client For developers building their own MCP client or integrating into a custom agent framework, you'll need to handle both the OAuth PKCE authentication flow and **client registration** with the Agent Wallet MCP server. ### Client Registration Before an MCP client can authenticate, it must be registered with the authorization server. The Agent Wallet MCP server supports two registration methods: CIMD lets your client publish its metadata (name, redirect URIs, grant types) as a JSON document at a publicly accessible URL. The authorization server fetches this document to verify your client's identity during the OAuth flow. **How it works:** 1. You host a JSON metadata document at a URL you control (e.g., `https://your-app.com/.well-known/oauth-client`) 2. Your client uses that URL as its `client_id` in the OAuth flow 3. The authorization server fetches the document to validate the client This is the **recommended approach** — no registration step is needed on our side, and you maintain full control of your client metadata. See the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) for the full metadata document schema. DCR ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) allows clients to register programmatically by posting their metadata to a registration endpoint. The server responds with a `client_id` that the client uses for subsequent OAuth flows. DCR on the Agent Wallet MCP server is **restricted to whitelisted clients**. If you need DCR access for your custom client, [reach out to us on Discord](https://discord.gg/fdxyz) to request whitelisting. Popular MCP clients — Claude Desktop, Cursor, Windsurf, Claude Code, and n8n — are already registered and work out of the box. Client registration only applies when you're building a custom MCP client or integrating the Agent Wallet MCP server into your own agent framework. ### Code Example ```typescript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const transport = new StreamableHTTPClientTransport( new URL("https://wallet-mcp.fd.xyz"), ); const client = new Client({ name: "my-agent", version: "1.0.0", }); await client.connect(transport); // Discover available tools const { tools } = await client.listTools(); console.log( "Available tools:", tools.map((t) => t.name), ); // Call a tool const result = await client.callTool({ name: "getWalletOverview", arguments: {}, }); ``` The MCP SDK's Streamable HTTP transport handles the OAuth PKCE flow natively. See the [MCP SDK documentation](https://modelcontextprotocol.io/docs) for full implementation details. ## Troubleshooting **Browser window doesn't open for authentication** * Ensure your MCP client supports OAuth PKCE with Streamable HTTP transport * Some older MCP client versions may not support remote server authentication — update to the latest version **Connection drops after a while** * OAuth tokens refresh automatically. If the refresh fails, restart your client to trigger a new authentication flow **Tools aren't showing up** * Verify the server URL is exactly `https://wallet-mcp.fd.xyz` * Verify the transport type is set to `streamable-http` (not `sse` or `stdio`) * Restart your MCP client after adding the configuration # Finance District MCP Server Source: https://developers.fd.xyz/agent-wallet/ai-integration/mcp-server The fastest way to give any AI agent a production-ready crypto wallet — plug in via MCP and go. The Agent Wallet MCP server is the primary integration point for AI agents. It exposes wallet capabilities as tools that any MCP-compatible client can discover and use — Claude Code, Cursor, Windsurf, n8n, or your own custom agent. The server is **remote and hosted** at `https://wallet-mcp.fd.xyz`. There's nothing to install, no local processes to run, and no infrastructure to manage. ## What is MCP? [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) is an open standard by Anthropic for connecting AI assistants to external tools and data sources. Think of it as a universal adapter — any MCP-compatible client can connect to any MCP server and discover what it can do. Agent Wallet publishes wallet operations as MCP tools. When your AI agent connects, it automatically discovers all available capabilities and can use them through natural language. ## Connection Details | Property | Value | | - | - | | Server URL | `https://wallet-mcp.fd.xyz` | | Transport | Streamable HTTP | | Authentication | OAuth Authorization Code Flow with PKCE | No API keys or bearer tokens to manage. When your MCP client connects for the first time, it triggers an OAuth authorization flow that opens a browser — sign in with your [District Pass](/overview/district-pass) (if you aren't already) and authorize the client to access your Finance District account. ## Connect Add the MCP server to your client and authorize it through the District Pass OAuth flow. Setup instructions for Claude Code, Cursor, Windsurf, n8n, and custom clients are in [MCP Compatible Clients](/agent-wallet/ai-integration/mcp-clients). ## Verify the Connection After configuring your client, verify the agent can reach the wallet: > "What Finance District tools do you have?" The agent should list the available wallet capabilities. Then try: > "What's my wallet balance?" If you see your balance (even if it's zero), the connection is working. Watch this connector setup and verification step by step at [05:56](https://youtu.be/JObnfc-jW78?t=356) in the Agent Wallet setup tutorial. ## Tools Reference The Finance District Wallet MCP server exposes **16 tools** across three categories. MCP clients discover all tool parameters automatically; CLI users can run `fdx wallet --help`. **Wallet Operations (12)** 1. `getWalletOverview` — balances across the Agent Wallet and Smart Accounts 2. `getAccountActivity` — transaction history for one account on one chain 3. `getTokenPrice` — USD price + 24h change for a token 4. `transferTokens` — transfer tokens across EVM, Solana, Bitcoin, and Sui 5. `swapTokens` — quote or execute a token swap (quote-only by default) 6. `discoverYieldStrategies` — discover DeFi yield strategies (**EVM chains only**) 7. `getYieldPositions` — list active yield positions for an account on a chain 8. `depositForYield` — deposit into a yield strategy 9. `withdrawFromYield` — withdraw from a yield position by vault token address 10. `getRedemptionRequests` — track async vault-withdrawal status (Pending / Finalized / Rejected) 11. `resolveNameService` — resolve ENS (.eth), SNS (.sol), Unstoppable Domains 12. `signMessage` — EIP-191 personal\_sign or EIP-712 typed-data signing (EVM) **Payments (2)** 13. `authorizePayment` — build an x402 payment authorization from a 402 response 14. `getX402Content` — fetch from an x402 API and auto-pay on HTTP 402 **Support (2)** 15. `getMyInfo` — authenticated user profile + all wallet addresses (EVM, Solana, Bitcoin, Sui) 16. `reportIssue` — file a bug report (creates a GitHub issue) **Sui: transfers only.** Swap, yield, signing, and Smart Account tools are not supported on Sui. *** ## Authentication Authentication uses **OAuth Authorization Code Flow with PKCE** — the same standard used by major web applications: 1. Your MCP client connects to `https://wallet-mcp.fd.xyz` 2. The server responds with an OAuth authorization URL 3. Your client opens a browser window 4. You sign in with your District Pass (if not already) and authorize the client to access your Finance District account 5. The OAuth flow completes and your client receives a token 6. Subsequent requests use this token automatically **Token refresh** is handled automatically by the OAuth flow. You shouldn't need to re-authenticate unless you explicitly revoke access. **Revoking access** — if you want to disconnect a specific MCP client, you can revoke its OAuth token through the Signer Service web interface. **Client registration** — popular MCP clients (Claude Desktop, Cursor, Windsurf, Claude Code, n8n) are pre-registered and work out of the box. If you're building a custom MCP client, see [Client Registration](/agent-wallet/ai-integration/mcp-clients#client-registration) for supported registration methods. ## Error Handling Common scenarios your agent may encounter: | Error | Meaning | Resolution | | - | - | - | | Authentication failed | OAuth token expired or revoked | Re-authenticate through browser flow | | Insufficient balance | Wallet doesn't have enough tokens for the operation | Fund the wallet with more tokens | | Transaction failed | On-chain error (gas, nonce, network issue) | Retry — transient errors resolve on retry | | Unsupported chain/token | Requested operation on an unsupported chain or token | Check [Supported Networks](/agent-wallet/supported-networks) | All tool responses follow a consistent shape: ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} // Success { "success": true, "data": { ... } } // Failure { "success": false, "error": { "code": "...", "message": "...", "retryable": true, "details": {} } } ``` If `retryable` is `true`, the client may retry the same request once. Otherwise, inputs or state must change before retrying. MCP clients typically display tool errors in the conversation. The agent can often explain what went wrong and suggest a fix. # Commerce Payments Source: https://developers.fd.xyz/agent-wallet/concepts/commerce Agent Wallet handles the payment layer for UCP and x402 commerce. Declare support in your profile, and the wallet signs when it's time to pay. Agent Wallet plugs into two commerce patterns. In both, the wallet's role is the same: sign the payment when asked. | Pattern | Trigger | What the wallet does | | - | - | - | | **x402 Paywall** | Agent hits a paid API | Detects the 402, signs, retries automatically | | **UCP Checkout** | Agent shops at a merchant | Signs the x402 authorization when the agent requests it during checkout | Everything else (discovering merchants, browsing catalogs, creating checkout sessions, submitting the credential) is handled by the agent or its platform. This page covers only the parts where Agent Wallet enters. ## Declare the Handler For UCP merchants to know your agent can pay via Prism, your platform's UCP profile must include the `xyz.fd.prism_payment` handler. ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} { "ucp": { "version": "2026-08-25", "payment_handlers": { "xyz.fd.prism_payment": [ { "id": "xyz.fd.prism_payment", "version": "2026-10-07", "spec": "https://prism-gw.fd.xyz/ucp/prism.md", "schema": "https://prism-gw.fd.xyz/ucp/schema.json", "available_instruments": [{ "type": "x402" }], "config": {} } ] } } } ``` This tells merchants: "this agent can pay with Prism-settled stablecoins." The `spec` and `schema` point to the handler definition so the merchant can validate compatibility. ## Authorize the Payment During a UCP checkout, the merchant returns payment requirements inside the handler's `config`: which chains, tokens, and amounts are accepted. Your agent passes this to the Agent Wallet MCP server, and the wallet: 1. Checks that the agent has sufficient balance on a supported chain 2. Selects a chain/token pair from the merchant's accepted options 3. Signs an ERC-3009 `transferWithAuthorization` inside the TEE 4. Returns the signed credential Before submitting, the agent adds `type: "x402"` to the credential. The instrument uses `handler_id: "xyz.fd.prism_payment"` and `type: "x402"`. The agent never sees private keys. The output is a self-contained x402 payment object that the agent submits back to the merchant to complete the checkout. ## x402 Paywall When your agent requests a Prism-protected resource, the server responds with HTTP `402 Payment Required`. The wallet handles this automatically: it reads the payment requirements, signs, and retries with proof of payment. No extra work from the agent. For more detail on the x402 protocol, see [x402 Payments](/agent-wallet/concepts/x402-payments). ## What the Wallet Handles Across both patterns, the Agent Wallet MCP server is responsible for: * **Payment signing** inside the TEE (private keys never leave the enclave) * **Chain and token selection** from the merchant's accepted options * **Balance validation** before signing * **ERC-3009 authorization** (the x402 payment primitive) Your agent handles the merchant interaction. The wallet handles the money. Connect your agent to the wallet The merchant side of this flow Full UCP checkout flow (protocol-level detail) Both sides of a complete purchase # Security Model Source: https://developers.fd.xyz/agent-wallet/concepts/security Your keys never leave a secure enclave — enterprise-grade, non-custodial security built for autonomous agents. Agent Wallet uses a non-custodial architecture with private keys secured inside AWS Nitro Enclaves. Finance District is an infrastructure provider — we don't hold custody of your wallet or keys. This is by design and architecture. You have full control over your wallet at all times. ## The Problem with Typical Approaches If your AI agent needs a wallet today, you're probably doing one of these: **Environment variables.** Generate a private key, store it in `.env`, use it in your agent code. This is the most common pattern in agent ecosystems — and the most dangerous. One compromised server, one leaked log, one misconfired deploy, and the key is gone. This isn't theoretical — credential leaks and key exposure are already being documented across agent platforms. **Application config.** Private key in a JSON config, YAML file, or secrets manager that the application reads at startup. Better than `.env`, but still accessible to anything with file or process access on the host. **Agent-managed keys.** The agent generates and manages its own key material, typically held in memory or the agent's storage. If the agent is compromised — or if the orchestrator framework has a vulnerability — the key goes with it. All of these patterns share one fundamental flaw: the key exists somewhere the host system can reach it. ## Trusted Execution Environment (TEE) Agent Wallet uses [AWS Nitro Enclaves](https://aws.amazon.com/ec2/nitro/nitro-enclaves/) for key management. Nitro Enclaves are isolated compute environments that run on dedicated, hardened hardware — separate from the host instance's CPU, memory, and storage. **How it works:** 1. Your private key is **generated inside** the Nitro Enclave 2. The key **never leaves** the enclave 3. All transaction **signing happens inside** the enclave 4. The host operating system **cannot access** the enclave's memory or storage 5. Even Finance District infrastructure operators **cannot extract** key material The enclave receives signing requests, performs the cryptographic operation internally, and returns the signed transaction. At no point is the raw private key exposed to any external process, API, or human. ```mermaid theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} flowchart LR A[Agent] -->|Signing Request| S subgraph enclave["AWS Nitro Enclave"] K["Private Key\n(generated here, never leaves)"] --> S[Sign Transaction] end S -->|Signed Transaction| A ``` ### Comparison | Approach | Where Keys Live | Who Can Access | Risk | | - | - | - | - | | Environment variables | Host memory / disk | Anyone with server access | High — one breach exposes keys | | Application config | Config files | App + anyone with file access | High | | Agent-managed | Agent memory / storage | Agent + orchestrator | Medium — agent compromise = key compromise | | **TEE (Agent Wallet)** | **Nitro Enclave** | **Nobody — signing happens inside** | **Low — hardware isolation** | ## Non-Custodial Architecture Finance District is an infrastructure provider, not a custodian. The architecture is non-custodial by design: * **We don't hold your keys.** Keys exist inside Nitro Enclaves. There is no mechanism for Finance District to extract, copy, or use your private keys. * **You have full control.** You can withdraw funds, export your keys, and manage your wallet at any time. * **You can export your keys.** Through the Signer Service web interface, you can request a full key export and back up your private keys independently. This means you are never locked into Finance District infrastructure. This is the same non-custodial model used by other non-custodial infrastructure providers — the platform secures and manages keys on your behalf, but you retain ownership and can take your keys elsewhere at any time. Key export means you can always self-custody. Agent Wallet is infrastructure you choose to use, not a walled garden you're locked into. ## What We Don't Do To be explicit about the security boundaries: * **We don't store keys in environment variables** — keys live in Nitro Enclaves, not on the host * **We don't trust the host environment** — the enclave is isolated from the host OS, memory, and storage * **We don't hold custody** — no Finance District employee or system can access your private keys * **We don't let agents manage key material** — agents call signing operations; they never touch the key itself * **We don't expose raw private keys through any interface** — MCP, CLI, AI Assistant, and Web App all interact with signing as a service, not with keys directly ## Audit Trail Every on-chain transaction your wallet makes is recorded on the blockchain and visible through any block explorer. Agent Wallet does not maintain a separate proprietary logging layer — the blockchain itself is your audit trail. To review your wallet's activity: * Look up your wallet address on the relevant chain's block explorer (Etherscan, Basescan, Solscan, etc.) * Every transaction includes sender, recipient, amount, token, timestamp, and transaction hash * On-chain history is immutable and independently verifiable This means your audit trail doesn't depend on Finance District — it's public, permanent, and cryptographically guaranteed by the blockchain. ## Redundancy and Key Safety The system has built-in redundancy and backup procedures. Simple hardware failures do not result in key loss — the infrastructure is designed to survive individual component failures without interrupting service. If you want additional peace of mind: * **Export your keys** at any time through the Signer Service web interface * **Back up exported keys** using your own secure storage (hardware wallet, encrypted backup, etc.) * **Self-custody as fallback** — exported keys work with any standard wallet software ## Your Controls You — the wallet owner — have full control at all times: * **View activity** — check your transaction history on-chain via block explorers * **Withdraw funds** — move your funds out of the wallet whenever you want * **Export keys** — request a full key export through the Signer Service interface * **Fund conservatively** — the [pocket money approach](/agent-wallet/concepts/trust) is your primary risk control The non-custodial architecture means these controls are inherent to the design, not features that can be revoked. Your wallet is yours. # Trust & Constraints Source: https://developers.fd.xyz/agent-wallet/concepts/trust The 'pocket money' philosophy — sensible constraints for AI agent financial autonomy. How much financial autonomy should you give an AI agent? The answer is simpler than most people think. ## The Pocket Money Philosophy Think of funding an agent wallet like giving pocket money. You put in what's appropriate for the task — not your entire portfolio. The agent operates autonomously within that scope. If something goes wrong, you lose the pocket money, not everything. This is deliberately simpler than: * **Complex policy engines** that require extensive configuration before your agent can do anything * **Role-based permission systems** that add integration overhead and maintenance burden * **Multi-approval workflows** that defeat the purpose of autonomous operation The constraint **is** the balance. If you fund a wallet with \$50, the worst case is losing \$50. No policy engine needed. No configuration. The constraint is immediate, obvious, and enforced by the blockchain itself. Don't give an agent more than you'd be comfortable losing. This one rule handles 90% of trust decisions. ## How to Think About Funding **Start small.** Always. Fund what you need for the immediate task, see how the agent performs, and increase as you gain confidence. **Match funding to the task.** A research agent that buys API access needs \$10–50. A trading agent running a strategy might need \$500. An enterprise payment agent might need more. Let the task dictate the amount. **Refill rather than pre-fund.** It's better to add \$100 five times than to deposit \$500 upfront. Each refill is a checkpoint — a moment to review what the agent did with the previous funds. ## Setting Constraints ### Balance Is the Primary Constraint The amount in the wallet is the most powerful constraint you have. It's: * **Enforced by the blockchain** — the agent literally cannot spend more than what's in the wallet * **Immediately effective** — no configuration, no policy language, no deployment * **Transparent** — you can check the balance at any time via any block explorer * **Universal** — works the same regardless of which interface the agent uses ### Progressive Trust 1. **Small real funds** — Fund with \$10–50. Verify the agent does what you expect. 2. **Working amount** — Once you trust the behavior, fund what the use case actually needs. 3. **Scale up** — Increase funding as the agent proves itself over time. Each step is a conscious decision. There's no automation that escalates trust — you decide when to increase the balance. ## Trust Patterns by Use Case | Use Case | Suggested Funding | Constraints | Wallet Level | | - | - | - | - | | Testing and exploration | Test tokens (free) | None — let it experiment | EOA | | Agent buying API access | \$10–50 | Fund per session | EOA | | Bot making small purchases | \$100–500 | Refill periodically | EOA | | Agent with recurring tasks | \$500–2,000 | Review activity weekly | EOA | | Multi-agent deployment | Per-agent budgets | Individual funding per agent | EOA | | Higher-value production | Task-appropriate | Consider Smart Account for added controls | Smart Account | | Enterprise with approval needs | Custom | Granular permissions, multi-party control | Delegated | Most entries in this table are EOA — because most agent use cases work perfectly with just sensible balance management. ## When Simple Constraints Aren't Enough The pocket money approach works for the vast majority of use cases. But some scenarios call for more: **You need batch transactions or gas abstraction** → [Smart Account](/agent-wallet/wallet-architecture#level-2-smart-account) adds programmable on-chain logic, session keys, and gas sponsorship. **You need on-chain spending limits** → [Delegated wallet](/agent-wallet/wallet-architecture#level-3-delegated-wallet) adds granular spending controls enforced by the smart contract itself. **You need multi-party approval** → Delegated wallets support approval workflows for high-value operations. The key principle: don't over-engineer trust controls before you need them. Start with sensible funding. Upgrade only when the use case genuinely demands it. ## Common Mistakes **Over-funding early.** Developers deposit large amounts "to avoid having to refill." This removes the natural safety net. Fund small, refill often. **Over-engineering controls.** Building complex permission systems before you've validated the agent's behavior. Start with pocket money. Add controls when you have real data on what the agent does. **Under-monitoring.** The pocket money approach doesn't mean "fund and forget." Check your wallet's on-chain activity periodically. Block explorers make this trivial. **Treating all agents the same.** A research agent and a trading agent have very different risk profiles. Fund each according to its purpose, not with a blanket amount. # X402 Payments Source: https://developers.fd.xyz/agent-wallet/concepts/x402-payments Multi-chain, multi-asset x402 payments — Agent Wallet's implementation of the x402 protocol for autonomous agent commerce. Agent Wallet implements [x402 specification v2](https://www.x402.org/) — the open protocol for machine-to-machine stablecoin payments over HTTP. This page covers what Agent Wallet provides and how it differs from other x402 implementations. For a full protocol explainer, see the [x402 official documentation](https://www.x402.org/). ## What Agent Wallet Provides Most x402 implementations support a single stablecoin on a single chain (typically USDC on Base). Agent Wallet supports **multiple assets across multiple chains**: | Stablecoin | Supported Chains | | - | - | | **USDC** | Base | | **FDUSD** | BSC, Arbitrum, Ethereum | **Coming soon:** FDUSD support on SUI. Your agent's wallet needs to hold the required stablecoin on the chain the merchant accepts. When a merchant supports multiple options, the wallet selects the best match from what's available in your balance. ## x402 Tools Agent Wallet provides two tools for x402 payments, available through both the [CLI](/agent-wallet/ai-integration/cli) and the [MCP server](/agent-wallet/ai-integration/mcp-server). Which one to use depends on the agent's environment and capabilities. ### authorizePayment (Recommended) Signs the payment authorization only — the agent handles the HTTP communication with the resource server itself. **How it works:** 1. Agent calls the resource server and receives HTTP `402 Payment Required` with payment requirements (`accepts[]` array with chain, token, amount, recipient) 2. Agent passes the requirements to `authorizePayment` — the wallet selects the best payment option from the agent's balance and signs an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) `transferWithAuthorization` 3. Agent retries the original request with the signed `PaymentPayload` attached 4. The resource server's facilitator verifies and settles the payment on-chain This gives the agent **maximum autonomy**. The agent understands what's happening at each step, makes its own decisions about whether to pay, and handles the HTTP communication directly. The wallet's role is limited to what it should be: signing the payment authorization. EIP-3009 means the payment is **gasless for the payer** — the facilitator executes the on-chain transfer, not the agent's wallet. When using the [Finance District CLI Skills](/agent-wallet/ai-integration/agent-skills), the skill teaches the agent the full x402 protocol flow and guides it to use `authorizePayment` at the right step. ### getX402Content (Fallback) Bundles the entire x402 flow — initial HTTP request, authorization signing, and retry — into a single call. The agent provides the resource URL, and the wallet handles everything internally. Use this when the agent **cannot make HTTP requests directly** (e.g. web-based AI assistants like Claude Desktop or Cursor that have MCP access but cannot execute shell commands or make outbound HTTP calls). ### Choosing the Right Tool | Tool | Agent handles HTTP | Best for | | - | - | - | | **authorizePayment** | Yes | Agents with HTTP access — Claude Code, OpenClaw, autonomous agents, agent frameworks | | **getX402Content** | No | Agents without HTTP access — Claude Desktop, Cursor, web-based assistants | ## Try It Out **With `authorizePayment`:** > "Access the premium data API at [https://api.example.com/market-data](https://api.example.com/market-data)" The agent handles the 402 response, requests payment signing from the wallet, and retries with proof. **With `getX402Content`:** > "Pay for the API at [https://api.example.com/market-data](https://api.example.com/market-data)" The wallet handles the full flow and returns the content. **Direct payment:** > "Pay 2 USDC to 0xABC...123 on Base" The agent can also make explicit payments to known addresses without encountering a 402 flow. ## Agent Wallet + Prism X402 is where the two Finance District products meet: * **Agent Wallet** is the buyer side — your agent has funds and wants to pay for services * **[Prism](/prism/overview)** is the seller side — merchants accept stablecoin payments from AI agents When an Agent Wallet pays a Prism merchant via x402, the transaction stays within one ecosystem. The agent pays, Prism verifies, the merchant gets their funds. Learn how merchants accept agent payments How Prism implements x402 on the merchant side Install the skills that teach agents x402 Official x402 protocol specification # Overview Source: https://developers.fd.xyz/agent-wallet/overview Agent Wallet — AI-native wallet infrastructure. Give your AI agents genuine financial autonomy. Agent Wallet is AI-native wallet infrastructure that gives AI agents their own wallets — not borrowed access to a human's. Every user gets EVM, Solana, Bitcoin, and Sui wallets provisioned automatically at signup, with full capabilities out of the box: transfers, swaps, yield generation, and commerce protocol payments. Private keys are secured in a Trusted Execution Environment (TEE), and the architecture is non-custodial — operators maintain ultimate control at all times. Unlike connecting an AI to an existing human wallet, Agent Wallet is built for agents from day one. It's optimized for agentic workflows, assisted conversations, and autonomous financial operations — so the experience is smooth whether an agent is executing a multi-step trade or a user is chatting with an AI assistant. ## Why AI-Native Matters Today, if your AI agent needs to handle money, you have three options: | Approach | How It Works | Limitation | | - | - | - | | **Human wallet + AI wrapper** | Agent connects to a user's MetaMask or Coinbase via API | No true autonomy — the human remains the wallet owner | | **DIY wallet** | A few lines of code to create an address, keys in env vars | Insecure, limited to basic transfers, no production path | | **AI-native (Agent Wallet)** | Agent gets its own wallet, operates within defined constraints | Genuine autonomy with production-grade security | The DIY approach gets you basic transfers, but swaps, yield, commerce payments, and secure key management aren't included — each one is a significant engineering effort. Agent Wallet provides all of this out of the box, with [TEE-secured key management](/agent-wallet/concepts/security), so you can focus on what your agent does rather than building financial infrastructure. ## Four Interfaces, One Wallet Agent Wallet is infrastructure — a core service exposed through multiple interfaces. All four connect to the same underlying wallet and capabilities. | Interface | Primary User | Best For | | - | - | - | | **[MCP Server](/agent-wallet/ai-integration/mcp-server)** | AI agents and assistants | Any MCP-compatible client — Claude, Cursor, n8n, custom agents | | **[CLI](/agent-wallet/ai-integration/cli)** | Developers and autonomous agents | Terminal-based workflows, scripting, server-side automation | | **[AI Assistant](/agent-wallet/ai-integration/ai-assistant)** | Humans (non-technical) | Conversational web interface for wallet management | | **Web App** | Operators | Traditional wallet UI — manage wallets and view balances | The MCP Server is the primary integration point for AI agents. The CLI is a lightweight wrapper around an MCP client — same capabilities, accessible from the command line. The AI Assistant and Web App serve humans who need to manage or monitor wallets directly. ## Core Capabilities When you sign up, EVM, Solana, Bitcoin, and Sui wallets are provisioned for you automatically — no extra steps required. From there, your agent (or you) can: * **Send & Receive** — Transfer tokens to any address on supported chains * **Check Balances** — View holdings across all provisioned wallets * **Swap** — Exchange between token pairs with best-rate routing * **Earn Yield** — Explore yield opportunities and deploy funds to vaults * **Commerce Payments** — Pay Prism-enabled merchants via x402 and other commerce protocols All capabilities are available through MCP, CLI, and AI Assistant. The Web App provides additional management features like wallet configuration. Agent Wallet supports EVM chains (Ethereum, Base, Polygon, Arbitrum, Optimism, BSC, Avalanche, Linea), Solana, Bitcoin, and Sui. Wallets for all are created by default for every user. ## Get Started Create your first agent wallet and connect via MCP Connect your AI agent to the hosted MCP server Install the CLI for terminal-based agent workflows TEE key management and non-custodial architecture # Quick Start Source: https://developers.fd.xyz/agent-wallet/quickstart Get a non-custodial agent wallet in under 2 minutes. No blockchain knowledge required. Sign up with your email, and EVM, Solana, Bitcoin, and Sui wallets are provisioned automatically — no seed phrases to manage. This guide connects that wallet to your AI client so your agent can start transacting.