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

# Finance District 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 <method>` or `fdx prism <method>` 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.

<Info>
  For full documentation, architecture details, and development instructions,
  see the [FDX GitHub
  repository](https://github.com/financedistrict-platform/fd-agent-wallet-cli).
</Info>

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

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

<Warning>
  `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.
</Warning>

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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:

```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.