@financedistrict/fdx 0.1.0

package/.eslintrc.cjs

@@ -0,0 +1,26 @@
+module.exports = {
+  root: true,
+  env: {
+    es2022: true,
+    node: true,
+  },
+  extends: ['eslint:recommended', 'plugin:import/recommended', 'plugin:prettier/recommended'],
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'script',
+  },
+  plugins: ['import', 'prettier'],
+  rules: {
+    'prettier/prettier': 'error',
+    'import/order': [
+      'error',
+      {
+        'newlines-between': 'always',
+        alphabetize: {
+          order: 'asc',
+          caseInsensitive: true,
+        },
+      },
+    ],
+  },
+};

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "endOfLine": "lf"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Finance District
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# FDX — Agent Wallet CLI
+
+[![npm version](https://img.shields.io/npm/v/@financedistrict/fdx)](https://www.npmjs.com/package/@financedistrict/fdx)
+[![CI](https://github.com/financedistrict-platform/fd-agent-wallet-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/financedistrict-platform/fd-agent-wallet-cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A command-line interface to the [Finance District](https://fd.xyz) MCP wallet server. Gives AI agents crypto wallet capabilities — hold, send, swap, and earn yield on assets across multiple chains — without managing private keys.
+
+## Why FDX?
+
+FDX is designed for AI agents and agent frameworks that need wallet tooling but don't natively support the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Instead of integrating an MCP client, agents invoke `fdx call <method>` from the command line and parse JSON output.
+
+- **No Key Management** — OAuth 2.1 secured. 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. One wallet, all chains.
+- **DeFi Enabled** — Transfer, swap, and earn yield through integrated DeFi protocols.
+- **Smart Accounts** — Account abstraction with multi-signature support (ERC-4337).
+
+## Quick Start
+
+```bash
+npm install -g @financedistrict/fdx
+```
+
+Run the setup (opens browser for OAuth):
+
+```bash
+fdx setup
+```
+
+Check that authentication succeeded:
+
+```bash
+fdx status
+```
+
+To remove stored credentials:
+
+```bash
+fdx logout
+```
+
+## Authentication
+
+FDX uses OAuth 2.1 with [Microsoft Entra External ID](https://learn.microsoft.com/en-us/entra/external-id/). Authentication is always tied to a user identity — the agent acts as a delegate on the user's behalf.
+
+### Interactive flow (default)
+
+```bash
+fdx setup
+```
+
+Opens the authorization URL in your browser. After consent, the browser redirects back to `localhost:6260` and the CLI completes the flow automatically. Requires a browser on the same machine and an available local port.
+
+### Device authorization flow (headless)
+
+```bash
+fdx setup --device
+```
+
+Designed for environments without a browser redirect — Docker containers, CI pipelines, remote servers, and autonomous agents. The CLI retrieves a short one-time code and prints it alongside the verification URL:
+
+```
+──────────────────────────────────────────────────────────
+  Verification URL: https://microsoft.com/devicelogin
+  Enter code:       ABCD-1234
+──────────────────────────────────────────────────────────
+```
+
+Open the URL on any device (or have your agent navigate to it), enter the code, and complete sign-in. The CLI polls in the background and stores the token once authorization is confirmed.
+
+### 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
+fdx logout
+```
+
+Removes the stored access and refresh tokens from the OS credential store and clears them from `~/.fdx/auth.json`. Client registrations (DCR) are preserved so the next `fdx setup` skips re-registration and goes straight to authentication.
+
+## Usage
+
+Invoke any MCP tool via the CLI:
+
+```bash
+# Check wallet overview
+fdx call getWalletOverview --chainKey ethereum
+
+# Send tokens
+fdx call transferTokens --chainKey ethereum --recipientAddress 0xABC... --amount 0.1
+
+# Discover yield strategies
+fdx call discoverYieldStrategies --chainKey base
+```
+
+All output is JSON, making it easy for agents to parse:
+
+```bash
+fdx call getMyInfo | jq '.email'
+```
+
+Run `fdx call` without arguments to see all available methods.
+
+## SDK Usage
+
+FDX can also be used as a Node.js library:
+
+```js
+const { createClientFromEnv } = require('@financedistrict/fdx');
+
+const client = createClientFromEnv();
+const result = await client.getWalletOverview({ chainKey: 'ethereum' });
+console.log(result.data);
+```
+
+## Configuration
+
+| Environment Variable | Description        | Default                                |
+| -------------------- | ------------------ | -------------------------------------- |
+| `FDX_MCP_SERVER`     | MCP server URL     | `https://mcp.fd.xyz`                   |
+| `FDX_REDIRECT_URI`   | OAuth callback URI | `http://localhost:6260/oauth/callback` |
+| `FDX_STORE_PATH`     | Token store path   | `~/.fdx/auth.json`                     |
+| `FDX_LOG_PATH`       | Log file path      | `~/.fdx/fdx.log`                       |
+| `FDX_LOG_LEVEL`      | Log verbosity (`debug`\|`info`\|`warn`\|`error`\|`off`) | `info` |
+
+## Documentation
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — System design overview
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — Running from source
+- [docs/UNINSTALL.md](docs/UNINSTALL.md) — Removal instructions
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/financedistrict-platform/fd-agent-wallet-cli/issues)
+- **Source**: [GitHub Repository](https://github.com/financedistrict-platform/fd-agent-wallet-cli)
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/bin/commands/call.js

@@ -0,0 +1,62 @@
+const { createSpinner } = require('nanospinner');
+const pc = require('picocolors');
+
+const { createClientFromEnv } = require('../../src');
+const { parseArgs } = require('../../src/utils/args');
+
+const METHODS = [
+  'getMyInfo',
+  'getAppVersion',
+  'helpNarrative',
+  'onboardingAssistant',
+  'reportIssue',
+  'getWalletOverview',
+  'getAccountActivity',
+  'deploySmartAccount',
+  'manageSmartAccountOwnership',
+  'transferTokens',
+  'swapTokens',
+  'discoverYieldStrategies',
+  'depositForYield',
+  'withdrawFromYield',
+  'authorizePayment',
+  'getX402Content',
+];
+
+module.exports = async function call(argv) {
+  const method = argv[0];
+
+  if (!method || !METHODS.includes(method)) {
+    console.log(`Usage: fdx call ${pc.cyan('<method>')} [--param value ...]`);
+    console.log('');
+    console.log(pc.dim('Methods:'));
+    for (const m of METHODS) {
+      console.log(`  ${m}`);
+    }
+    process.exit(1);
+  }
+
+  const args = parseArgs(argv.slice(1));
+  const client = createClientFromEnv();
+
+  const spinner = createSpinner(`Calling ${pc.cyan(method)}...`).start();
+
+  try {
+    const result = await client[method](args);
+
+    if (result.error) {
+      spinner.error({ text: `${method} failed` });
+      console.error(JSON.stringify({ error: result.error }, null, 2));
+      process.exit(1);
+    }
+
+    spinner.success({ text: `${method}` });
+    console.log(JSON.stringify(result.data, null, 2));
+  } catch (error) {
+    spinner.error({ text: `${method} failed` });
+    console.error(pc.red(error.message));
+    process.exit(1);
+  } finally {
+    await client.close().catch(() => {});
+  }
+};

package/bin/commands/logout.js

@@ -0,0 +1,12 @@
+const pc = require('picocolors');
+
+const { createClientFromEnv } = require('../../src');
+
+module.exports = async function logout() {
+  const client = createClientFromEnv();
+
+  await client.logout();
+
+  console.log(pc.green('Logged out.') + ' Credentials removed.');
+  console.log(`  Run ${pc.cyan('"fdx setup"')} to authenticate again.`);
+};

package/bin/commands/setup.js

@@ -0,0 +1,148 @@
+const http = require('http');
+const { URL } = require('url');
+
+const { createSpinner } = require('nanospinner');
+const pc = require('picocolors');
+
+const { createClientFromEnv } = require('../../src');
+
+module.exports = async function setup({ device = false } = {}) {
+  const client = createClientFromEnv();
+
+  console.log(pc.bold(`FDX - Setup${device ? ' (Device Flow)' : ''}`));
+  console.log('');
+  console.log(`${pc.dim('MCP Server:')}   ${client.authClient.mcpServerUrl}`);
+  if (!device) {
+    console.log(`${pc.dim('Redirect URI:')} ${client.authClient.redirectUri}`);
+  }
+  console.log(`${pc.dim('Store Path:')}   ${client.authClient.storePath}`);
+  console.log('');
+
+  let tokens;
+
+  if (device) {
+    const initSpinner = createSpinner('Registering device client...').start();
+    await client.initializeForDevice();
+    initSpinner.success({ text: `Client ID: ${pc.cyan(client.authClient.deviceClientId)}` });
+    console.log('');
+
+    const deviceSpinner = createSpinner('Requesting device code...').start();
+    const deviceInfo = await client.startDeviceFlow();
+    deviceSpinner.success({ text: 'Device code received' });
+
+    console.log('');
+    console.log(pc.bold('─'.repeat(58)));
+    console.log(`  ${pc.dim('Verification URL:')} ${pc.underline(deviceInfo.verificationUri)}`);
+    console.log(`  ${pc.bold('Enter code:')}       ${pc.cyan(pc.bold(deviceInfo.userCode))}`);
+    console.log(pc.bold('─'.repeat(58)));
+    console.log('');
+
+    const pollSpinner = createSpinner('Waiting for authorization...').start();
+    tokens = await client.pollDeviceToken({
+      deviceCode: deviceInfo.deviceCode,
+      interval: deviceInfo.interval,
+    });
+    pollSpinner.success({ text: 'Authentication successful' });
+  } else {
+    const initSpinner = createSpinner('Registering client...').start();
+    await client.initialize();
+    initSpinner.success({ text: `Client ID: ${pc.cyan(client.authClient.clientId)}` });
+    console.log('');
+
+    const port = new URL(client.authClient.redirectUri).port || 6260;
+    const { url, state, codeVerifier } = await client.getAuthorizationUrl();
+
+    console.log('Open this URL in your browser:');
+    console.log('');
+    console.log(pc.underline(url));
+    console.log('');
+
+    const callbackSpinner = createSpinner('Waiting for callback...').start();
+
+    const callback = await waitForCallback(port, client.authClient.redirectUri);
+    callbackSpinner.success({ text: 'Callback received' });
+
+    if (callback.state !== state) {
+      console.error(pc.red('OAuth state mismatch — possible CSRF attack. Aborting.'));
+      process.exit(1);
+    }
+
+    const tokenSpinner = createSpinner('Exchanging code for token...').start();
+    tokens = await client.exchangeCodeForToken({ code: callback.code, state, codeVerifier });
+    tokenSpinner.success({ text: 'Authentication successful' });
+  }
+
+  console.log('');
+  console.log(`  ${pc.dim('Token Type:')}  ${tokens.token_type}`);
+  console.log(`  ${pc.dim('Expires In:')}  ${tokens.expires_in}s`);
+  console.log(
+    `  ${pc.dim('Has Refresh:')} ${tokens.refresh_token ? pc.green('yes') : pc.yellow('no')}`,
+  );
+  console.log('');
+  console.log(
+    pc.green('Done.') +
+      ' You can now use ' +
+      pc.cyan('"fdx call <method>"') +
+      ' to invoke MCP tools.',
+  );
+};
+
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function waitForCallback(port, redirectUri) {
+  const callbackPath = new URL(redirectUri).pathname;
+
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost:${port}`);
+
+      if (url.pathname === callbackPath) {
+        const code = url.searchParams.get('code');
+        const error = url.searchParams.get('error');
+        const errorDescription = url.searchParams.get('error_description');
+
+        if (error) {
+          res.writeHead(400, { 'Content-Type': 'text/html' });
+          res.end(
+            `<html><body><h1>Error: ${escapeHtml(error)}</h1><p>${escapeHtml(errorDescription || '')}</p></body></html>`,
+          );
+          server.close();
+          clearTimeout(timer);
+          reject(new Error(`${error}: ${errorDescription}`));
+          return;
+        }
+
+        if (code) {
+          const callbackState = url.searchParams.get('state');
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end('<html><body><h1>Success</h1><p>You can close this window.</p></body></html>');
+          server.close();
+          clearTimeout(timer);
+          resolve({ code, state: callbackState });
+          return;
+        }
+      }
+
+      res.writeHead(404);
+      res.end('Not Found');
+    });
+
+    const TIMEOUT_MS = 5 * 60 * 1000;
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new Error('OAuth callback timed out after 5 minutes'));
+    }, TIMEOUT_MS);
+
+    server.listen(port, '127.0.0.1', () => {});
+    server.on('error', (err) => {
+      clearTimeout(timer);
+      reject(new Error(`Callback server error: ${err.message}`));
+    });
+  });
+}

package/bin/commands/status.js

@@ -0,0 +1,58 @@
+const pc = require('picocolors');
+
+const { createClientFromEnv } = require('../../src');
+
+module.exports = async function status() {
+  const client = createClientFromEnv();
+  const storePath = client.authClient.storePath;
+  const mcpServer = client.authClient.mcpServerUrl;
+
+  let state;
+  try {
+    state = await client.getTokenState();
+  } catch (error) {
+    console.log(pc.red('Status: not configured'));
+    console.log(`  ${pc.dim('MCP server:')}  ${mcpServer}`);
+    console.log(`  ${pc.dim('Store path:')} ${storePath} (${error.message})`);
+    process.exit(1);
+  }
+
+  if (!state.authenticated) {
+    console.log(pc.yellow('Status: not authenticated'));
+    console.log(`  ${pc.dim('MCP server:')}  ${mcpServer}`);
+    console.log(`  ${pc.dim('Store path:')} ${storePath}`);
+    console.log(`  Run ${pc.cyan('"fdx setup"')} to authenticate.`);
+    process.exit(1);
+  }
+
+  const statusLabel = state.expired ? pc.yellow('token expired') : pc.green('authenticated');
+  console.log(`Status: ${statusLabel}`);
+  console.log(`  ${pc.dim('MCP server:')}    ${mcpServer}`);
+  console.log(`  ${pc.dim('Store path:')}    ${storePath}`);
+  console.log(`  ${pc.dim('Client ID:')}     ${state.clientId || 'unknown'}`);
+  console.log(
+    `  ${pc.dim('Token expires:')}  ${state.expiresAt ? new Date(state.expiresAt).toISOString() : 'unknown'}`,
+  );
+  console.log(
+    `  ${pc.dim('Has refresh:')}   ${state.hasRefresh ? pc.green('yes') : pc.yellow('no')}`,
+  );
+  console.log(
+    `  ${pc.dim('Credentials:')}   ${state.usingCredentialStore ? pc.green('OS credential store') : pc.yellow('plaintext file')}`,
+  );
+
+  if (state.expired && !state.hasRefresh) {
+    console.log('');
+    console.log(
+      pc.red('Token expired and no refresh token.') +
+        ` Run ${pc.cyan('"fdx setup"')} to re-authenticate.`,
+    );
+    process.exit(1);
+  }
+
+  if (state.expired && state.hasRefresh) {
+    console.log('');
+    console.log(
+      pc.dim('Token expired but refresh token available. Will auto-refresh on next call.'),
+    );
+  }
+};

package/bin/fdx.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+require('dotenv').config({ path: require('path').resolve(process.cwd(), '.env') });
+
+const { Command } = require('commander');
+const pc = require('picocolors');
+
+const pkg = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('fdx')
+  .description('Agent wallet CLI — Finance District MCP wallet client')
+  .version(pkg.version)
+  .enablePositionalOptions()
+  .addHelpText(
+    'after',
+    [
+      '',
+      `${pc.dim('Environment:')}`,
+      `  FDX_MCP_SERVER     MCP server URL (default: https://mcp.fd.xyz)`,
+      `  FDX_REDIRECT_URI   OAuth callback URI (default: http://localhost:6260/oauth/callback)`,
+      `  FDX_STORE_PATH     Token store path (default: ~/.fdx/auth.json)`,
+      `  FDX_LOG_PATH       Log file path (default: ~/.fdx/fdx.log)`,
+      `  FDX_LOG_LEVEL      Log verbosity: debug|info|warn|error|off (default: info)`,
+    ].join('\n'),
+  );
+
+program
+  .command('setup')
+  .description('Run OAuth 2.1 authentication flow')
+  .option('--device', 'Use device authorization flow (no browser redirect required)')
+  .action(async (opts) => {
+    await require('./commands/setup')(opts);
+  });
+
+program
+  .command('status')
+  .description('Check authentication status')
+  .action(async () => {
+    await require('./commands/status')();
+  });
+
+program
+  .command('logout')
+  .description('Remove stored credentials')
+  .action(async () => {
+    await require('./commands/logout')();
+  });
+
+program
+  .command('call')
+  .description('Invoke an MCP tool')
+  .argument('<method>', 'tool name to invoke')
+  .allowUnknownOption()
+  .allowExcessArguments(true)
+  .passThroughOptions()
+  .action(async (method, _opts, cmd) => {
+    await require('./commands/call')([method, ...cmd.args.slice(1)]);
+  });
+
+program.parseAsync().catch((error) => {
+  console.error(pc.red(error.message));
+  process.exit(1);
+});