Finance District CLI

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 <method> or fdx prism <method> from the command line and parse JSON output. FDX also powers the Agent Wallet CLI 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.

Quick Start

Install globally:

npm install -g @financedistrict/fdx

fdx register --email you@example.com

Enter the 8-digit OTP sent to your email:

fdx verify --code 12345678

Check that authentication succeeded:

fdx status

For subsequent sessions, sign in with:

fdx login --email you@example.com
fdx verify --code 12345678

To remove stored credentials:

fdx logout

Watch this install and login flow at 09:20 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)

fdx register --email you@example.com
# Check your inbox for an 8-digit OTP
fdx verify --code 12345678

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

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:

# 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:

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 <method> was deprecated in v0.4.0 and now exits with an error. Use fdx wallet <method> for wallet tools or fdx prism <method> for Prism tools.

Services

# 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:

Environment variables (highest priority — see fdx --help for the full list)
Persistent config file at ~/.fdx/config.json
Built-in defaults (lowest priority)

Inspect current config

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

fdx config set <key> <value>

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

fdx config get <key>
fdx config unset <key>

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:

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

#!/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.

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.

Getting Started

Concepts

AI Integration

Advanced

Resources

Quick Start

Authentication

Register (first time)

Token storage

Logging out

Usage

Services

Configuration

Inspect current config

Persist a value

Read or remove a persisted value

Supported keys

Using FDX with Agent Frameworks

Tool-calling agents

Script-based automation

FDX vs. MCP Server

​Quick Start

​Authentication

​Register (first time)

​Login (returning users)

​Token storage

​Logging out

​Usage

​Services

​Configuration

​Inspect current config

​Persist a value

​Read or remove a persisted value

​Supported keys

​Using FDX with Agent Frameworks

​Tool-calling agents

​Script-based automation

​FDX vs. MCP Server

Quick Start

Authentication

Register (first time)

Login (returning users)

Token storage

Logging out

Usage

Services

Configuration

Inspect current config

Persist a value

Read or remove a persisted value

Supported keys

Using FDX with Agent Frameworks

Tool-calling agents

Script-based automation

FDX vs. MCP Server