Authenticating with the Finance District Agent Wallet
When the wallet is not signed in (detected via fdx status or when wallet operations fail with authentication errors), use the fdx CLI to authenticate via OAuth 2.1.
Authentication requires a browser — the agent guides the human through the flow, but the human must complete the browser-based authorization step.
Checking Authentication Status
CODEBLOCK0
Displays the MCP server URL, token state, expiry, and whether a refresh token is available.
Authentication Flow
FDX supports two OAuth flows depending on the environment:
Browser Flow (default)
Use when the human has a browser available on the same machine:
CODEBLOCK1
This will:
- 1. Register a client with the MCP server
- Print an authorization URL
- Start a local callback server on port 6260
- Wait for the human to complete browser authorization
- Exchange the authorization code for tokens
Tell your human: "Please open the URL in your browser and authorize the wallet. I'll wait for the callback."
Device Flow
Use when the human cannot open a browser on the same machine (e.g. remote server, headless environment):
CODEBLOCK2
This will:
- 1. Register a device client with the MCP server
- Display a verification URL and a user code
- Poll for authorization completion
Tell your human: "Please go to the verification URL on any device, enter the code shown, and authorize. I'll wait here."
Logging Out
CODEBLOCK3
Removes stored credentials. The human will need to run fdx setup again to re-authenticate.
Example Session
CODEBLOCK4
Token Lifecycle
- - Tokens auto-refresh on subsequent
fdx call commands if a refresh token is available - If the token is expired and no refresh token exists, the human must run
fdx setup again - Token state is stored locally (default:
~/.fdx/auth.json)
Environment Variables
| Variable | Description | Default |
|---|
| INLINECODE6 | MCP server URL | INLINECODE7 |
| INLINECODE8 |
OAuth callback URI |
http://localhost:6260/oauth/callback |
|
FDX_STORE_PATH | Token store file path |
~/.fdx/auth.json |
Error Handling
- - "not authenticated" — Run
fdx setup to authenticate - "token expired" with refresh token — Will auto-refresh on next call; no action needed
- "token expired" without refresh token — Run
fdx setup again - "OAuth state mismatch" — Possible CSRF; restart with INLINECODE14
- "Callback server error" — Port 6260 may be in use; try
--device flow instead
技能名称: authenticate
详细描述:
使用金融区代理钱包进行身份验证
当钱包未登录时（通过 fdx status 检测，或钱包操作因身份验证错误失败时），使用 fdx CLI 通过 OAuth 2.1 进行身份验证。
身份验证需要浏览器——代理会引导人类完成流程，但人类必须完成基于浏览器的授权步骤。
检查身份验证状态
bash
fdx status
显示 MCP 服务器 URL、令牌状态、过期时间以及是否有可用的刷新令牌。
身份验证流程
FDX 根据环境支持两种 OAuth 流程：
浏览器流程（默认）
当人类在同一台机器上有可用的浏览器时使用：
bash
fdx setup
这将：
- 1. 向 MCP 服务器注册客户端
- 打印授权 URL
- 在端口 6260 启动本地回调服务器
- 等待人类完成浏览器授权
- 将授权码兑换为令牌
告诉你的用户： 请在浏览器中打开该 URL 并授权钱包。我将等待回调。
设备流程
当人类无法在同一台机器上打开浏览器时使用（例如远程服务器、无头环境）：
bash
fdx setup --device
这将：
- 1. 向 MCP 服务器注册设备客户端
- 显示验证 URL 和用户代码
- 轮询授权完成状态
告诉你的用户： 请在任何设备上访问验证 URL，输入显示的代码并进行授权。我将在此等待。
登出
bash
fdx logout
删除存储的凭据。人类需要再次运行 fdx setup 以重新进行身份验证。
示例会话
bash
检查当前状态
fdx status
如果未通过身份验证，开始登录
fdx setup
人类完成浏览器授权...
确认身份验证成功
fdx status
令牌生命周期
- - 如果存在可用的刷新令牌，令牌将在后续的 fdx call 命令中自动刷新
- 如果令牌已过期且没有刷新令牌，人类必须再次运行 fdx setup
- 令牌状态存储在本地（默认：~/.fdx/auth.json）
环境变量
| 变量 | 描述 | 默认值 |
|---|
| FDXMCPSERVER | MCP 服务器 URL | https://mcp.fd.xyz |
| FDXREDIRECTURI |
OAuth 回调 URI | http://localhost:6260/oauth/callback |
| FDX
STOREPATH | 令牌存储文件路径 | ~/.fdx/auth.json |
错误处理
- - 未通过身份验证 — 运行 fdx setup 进行身份验证
- 令牌已过期 且有刷新令牌 — 下次调用时将自动刷新；无需操作
- 令牌已过期 且无刷新令牌 — 再次运行 fdx setup
- OAuth 状态不匹配 — 可能存在 CSRF；重新运行 fdx setup
- 回调服务器错误 — 端口 6260 可能已被占用；尝试使用 --device 流程
