FibX

FibX

一款用于 Base、HyperEVM 和 Monad 上 DeFi 操作的命令行工具和 MCP 服务，由 Fibrous 聚合服务提供支持。可通过 WalletConnect 使用自己的钱包签名、使用 Privy 服务端钱包签名，或导入密钥签名——所有方式都受限于存储在你本机上的签名策略。

功能

• 多链支持：Base、HyperEVM 和 Monad
• 投资组合：跨链投资组合概览，包含美元估值和 DeFi 仓位
• 代币兑换：通过 Fibrous 聚合服务进行最优路由，并自动设置滑点
• 转账：发送 ETH 或任意 ERC-20 代币
• Aave V3：在 Base 上进行供应、借款、还款、提款和浏览市场
• MCP 服务：内置 AI Agent 集成，支持 Cursor、Claude Desktop 和 Antigravity（19 个工具）
• 聊天中的 FibX 应用：在可呈现 MCP Apps 界面的宿主（例如 Claude Desktop）中，open_fibx 会显示钱包、余额、签名策略，以及内嵌 Fibrous 路由的兑换表单——由模型打开界面，然后由你按下 Simulate and Swap
• Agent Skills：通过 fibx-skills 提供基于提示词的 AI 技能
• 使用自己的钱包：通过 WalletConnect 配对，并在手机上批准每笔交易
• Privy 服务端钱包：在服务端进行签名——CLI 接收已签名的交易载荷或签名，而非 Privy 应用凭据或原始密钥
• 导入私钥：使用现有钱包，并通过 AES-256-GCM 加密在本地存储
• 本地签名策略：由你管理的文件——按链设置原生代币金额上限、允许的链、允许的目标地址和有效期；所有三种方式在每次签名前都会执行此策略（Privy 还会额外执行其服务端策略）
• 预检：在底层 RPC 支持的情况下，交易流程会验证执行情况或估算执行结果
• 模拟运行模式：--simulate 可预览写入操作而不广播交易；有可用数据时会附带 Gas 估算
• JSON 输出：使用 --json 标志进行脚本编写和管道处理
• 零依赖安装：通过 tsup 打包为单文件——运行 npx fibx 几乎无需等待

支持的链

链	原生代币	Aave V3
Base	ETH	✅
HyperEVM	HYPE	—
Monad	MON	—

安装

通过 npx 直接运行（无需安装）：

npx fibx status

或全局安装：

npm install -g fibx

要求

• Node.js >= 18
• 正在运行的 fibx-server 实例（Privy 钱包操作所必需；导入私钥时不需要）

快速开始——3 分钟完成首次兑换

步骤 1：获取价格报价（无需身份验证）

立即试用 FibX——无需注册、无需钱包、无需密钥：

npx fibx quote 0.01 ETH USDC              # Check price on Base
npx fibx quote 100 USDC DAI --chain base   # Compare pairs
npx fibx quote 0.5 MON USDC --chain monad  # Check Monad prices

步骤 2：进行身份验证（二选一）

选项 A — 邮箱登录（Privy 服务端钱包，无需管理密钥）：

npx fibx auth login [email protected]          # Sends OTP to your email
npx fibx auth verify [email protected] 123456  # Verify & create wallet

选项 B — 导入私钥（使用现有钱包）：

npx fibx auth import                       # Paste your key (encrypted at rest)

步骤 3：执行

npx fibx trade 0.01 ETH USDC               # Execute the swap
npx fibx balance                            # Check your balances

就是这么简单。从零开始，三步完成首次兑换。

用法

选择 FibX 的签名方式

运行 fibx auth setup，它会询问你。三种方式只有一处不同：

方式	密钥由谁持有	你离开后是否继续运行	受谁限制
auth connect	你的自有钱包	否	你，在手机上
auth login	Privy	是	Privy 的签名策略
auth import	这台机器	是	你设置的本地策略

如果要保留自己的钱包，同时让 FibX 在无人值守时运行，就需要 ERC-7715；但钱包尚未通过 WalletConnect 提供该功能。fibx auth setup 会说明最接近的可选方案。

**安全提示：**使用 auth import 时，你的私钥会使用 AES-256-GCM 加密后静态存储。加密密钥会按机器自动生成，并存储在操作系统的配置目录中（例如 Linux 上的 ~/.config/fibx-nodejs/encryption-key）。你也可以在 CI/Docker 环境中设置 FIBX_SESSION_SECRET 环境变量。

连接自己的钱包

npx fibx auth connect

通过 WalletConnect 将 FibX 与你已有的钱包配对，例如 MetaMask、Rabby、Rainbow、Phantom。终端会显示二维码；用手机扫描即可。之后，每笔交易都需要在你的钱包中批准，因此密钥始终不会离开钱包。

你要交易的链必须已添加到钱包中，并且配对时会获准使用该链。如果你尝试在当前会话未包含的链上签名，FibX 会在联系钱包前停止，并指出该链：在钱包中添加该链，然后再次运行 npx fibx auth connect，以便将新链纳入会话。

使用 --json 时，输出为 NDJSON——每行一份 JSON 文档，而非整个运行过程只输出一份文档：配对 URI 会先以 {"uri":"wc:..."} 的形式打印，脚本可在等待期间处理它；钱包批准后，结果会作为单独的紧凑 JSON 行打印。

npx fibx auth logout 会在双方结束连接：它会通知钱包丢弃会话，让 FibX 不再显示在已连接的应用列表中，并从磁盘中删除配对密钥和会话。

已发布的程序包内置了一个共享的 WalletConnect 项目 ID，因此无需设置即可使用。由于 CLI 没有可供加入允许列表的来源，该 ID 必须公开，因此唯一实际风险是第三方消耗配额。如果配对因配额问题开始失败，请在 cloud.reown.com 创建免费项目，并将 FIBX_WC_PROJECT_ID 设置为你自己的 ID。

auth login（电子邮件 OTP）和 auth import（私钥）保持不变，仍可使用。

签名策略

fibx policy 会限制 FibX 获准签署的内容，无论密钥采用上表中的哪种存储方式 — 每次本地密钥、Privy 或 WalletConnect 交易前，都会先评估客户端策略上限：

npx fibx policy show                    # Print the active policy

npx fibx policy set base.maxValue 0.05
npx fibx policy set allowedChains base,monad
npx fibx policy set base.allowedDestinations 0xYourColdWallet,0xTheRouter
npx fibx policy set expiry 2026-12-31   # UTC midnight starting that day

npx fibx policy clear base.maxValue     # Remove one rule
npx fibx policy clear                   # Remove the whole policy (asks first)

保护本地密钥的本地策略仅供参考：任何能读取密钥的人都能编辑策略，因此它无法抵御恶意软件。它能限制的是 Agent — 行为异常的模型，或受提示词注入影响的模型。

请了解每条规则的限制范围，因为它们并不相同：

• maxValue 限制单笔交易的原生价值 — Base 上的 ETH、HyperEVM 上的 HYPE、Monad 上的 MON。它不限制代币。ERC-20 转账会以携带 value: 0 的代币合约调用形式提交给策略，因此策略看不到转账金额：base.maxValue 0.05 不会限制 fibx send 50000 USDC 0xsomewhere、交易中的代币部分，也不会限制 Aave 借款。要限制代币价值，需要代币精度和代币注册表，本次版本尚未提供。
• allowedDestinations 通过限制资金可流向的位置来限制代币。如果担心 Agent 将持仓转移到别处，应设置此项。请注意，将代币合约加入允许列表以便交易时批准该代币，也意味着允许转出该代币。
• allowedChains 和 expiry 的作用与字面含义一致。策略过期或无法解析时，将拒绝所有操作，而不是放行。

全局选项

选项	说明	默认值
-c, --chain <name>	目标链（base、hyperevm、monad）	base
--json	以 JSON 格式输出结果	false

余额

npx fibx balance
npx fibx balance --chain hyperevm

投资组合

汇总跨链投资组合视图，含 USD 估值：

npx fibx portfolio           # Table output across all chains
npx fibx portfolio --json    # Structured JSON for scripting

显示 Base、HyperEVM 和 Monad 上的所有代币持仓及其 USD 价值。包括 DeFi 仓位（Aave V3 抵押品/债务）和投资组合净资产总额。代币价格由 Fibrous 实时提供。

发送

npx fibx send 0.001 0xRecipient           # Send native token on Base (ETH)
npx fibx send 10 0xRecipient USDC         # Send ERC-20 on Base
npx fibx send 1 0xRecipient --chain monad # Send MON on Monad
npx fibx send 0.1 0xRecipient --simulate  # Preview without sending

报价

无需身份验证即可获取兑换价格：

npx fibx quote 0.01 ETH USDC                  # Price check on Base
npx fibx quote 1 MON USDC --chain monad         # Check Monad prices
npx fibx quote 0.1 ETH USDC --json             # JSON output for scripts

无需钱包或身份验证。 使用 quote 查询价格，再使用 trade 执行交易。

兑换

npx fibx trade <amount> <from> <to>
npx fibx trade 0.0001 ETH USDC
npx fibx trade 20 USDC DAI
npx fibx trade 1 MON USDC --chain monad
npx fibx trade 0.1 ETH USDC --simulate   # Preview without broadcasting

选项：--slippage <n>（默认值：0.5%）、--approve-max、--simulate、--json

注意： trade 命令会自动检测 Wrap（Native -> Wrapped）和 Unwrap（Wrapped -> Native）操作，并直接通过合约调用执行，绕过聚合器路由以节省 Gas。

交易状态

npx fibx tx-status <hash>
npx fibx tx-status 0x123...abc --chain monad

钱包信息

npx fibx address    # Print active wallet address
npx fibx wallets    # Show active wallet details

Aave V3（Base）

npx fibx aave status               # Account health
npx fibx aave markets              # List all active reserves with APY & TVL
npx fibx aave supply 1 ETH         # Auto-wraps ETH -> WETH and supplies
npx fibx aave supply 100 USDC      # Supply ERC-20
npx fibx aave borrow 50 USDC       # Borrow
npx fibx aave repay 50 USDC        # Repay
npx fibx aave repay max ETH        # Auto-wraps ETH and repays full WETH debt
npx fibx aave withdraw max ETH     # Withdraws WETH and auto-unwraps to ETH
npx fibx aave supply 1 ETH --simulate  # Preview without broadcasting

注意： supply、repay 和 withdraw 在 Base 上支持自动 ETH <-> WETH 包装/解包。

配置

设置自定义 RPC URL，以避免公共端点的速率限制：

npx fibx config set-rpc base https://mainnet.base.org
npx fibx config get-rpc base
npx fibx config reset-rpc base   # Reset single chain to default
npx fibx config reset-rpc        # Reset all chains to default
npx fibx config list

热重载： 配置更改会自动生效 — 无需重启 CLI 或 MCP 服务。

AI Agent 集成

MCP 服务

fibx 内置了 MCP 服务，可供 Cursor、Claude Desktop 和 Antigravity 等 AI 编辑器使用。有关设置和可用工具，请参阅 MCP.md。

npx fibx mcp-start

MCP 服务提供 19 个工具：FibX 应用（open_fibx、list_tokens）、只读查询、三个交易工具，以及会话和策略管理。所有写入操作都支持 simulate=true 预览，不会广播交易；仅在可用时返回 Gas 估算。

在可渲染 MCP Apps UI 的宿主中 — 目前包括 Claude Desktop — open_fibx 是入口：询问钱包、余额、价格或兑换信息，整个应用便会以内嵌方式打开，并根据对话预先填入信息。它不会自行执行任何操作；模拟和兑换都需要你点击按钮。在仅支持文本的宿主中，同一调用会返回 JSON 快照，供模型总结，后续操作则由无头工具完成。

Agent Skills

对于基于提示词的 Agent 集成（Claude Code、Cursor 等），请参阅 fibx-skills 仓库。

安全性

让 AI Agent 操作钱包需要模型之外的控制措施。 fibx 结合了签名层策略、服务端验证、客户端提示和明确的预览。 这些控制措施可以降低风险，但服务凭据、MCP 客户端配置和部署策略仍属于信任边界的一部分：

层级	功能
Privy 签名策略	默认策略允许列表中配置的链，限制每笔交易的原生代币 value，并禁止导出密钥。Privy 在签名时评估策略；fibx-server 凭据和任何自定义策略仍是关键的信任边界。
fibx-server 架构	/sign/* 只接受 CLI 生成的精确交易结构 — 未知字段、合约创建和未提供服务的链都会在到达 Privy 前被拒绝。
MCP 工具注释	每个交易类工具都会声明 destructiveHint: true；兼容的客户端可能会根据客户端行为和配置，利用此提示请求确认。
模拟	--simulate 可预览写入操作，而不会广播。某些路径还会返回 Gas 估算值；其他路径则只返回操作元数据。
本地密钥存储	导入的私钥使用 AES-256-GCM 加密后静态存储，并使用每台机器独有的密钥；该密钥以 0600 权限存储在 OS 配置目录中。

钱包策略限制按部署配置 — 请参阅 fibx-server 钱包策略文档。

注： 策略会在创建钱包时附加。引入策略前配置的钱包在迁移前仍会在没有策略的情况下继续签名。

架构

此仓库包含 CLI 和 MCP 服务。三个同级仓库共同构成完整技术栈：

仓库	角色
fibx（此仓库）	CLI + stdio MCP 服务，以单个无依赖包的形式发布
fibx-server	代理 Privy 的 Hono 后端 — 保存应用密钥，因此 CLI 无需处理，并负责钱包签名策略
fibx-skills	面向 Claude Code、Cursor 及其他支持技能的 Agent 的基于提示词的 Agent Skills
fibx-telegram-bot	通过 MCP 驱动此 CLI 的 Telegram 机器人；每位活跃用户使用一个进程和单独的配置路径

src/
├── commands/           # CLI commands (auth, policy, trade, send, aave, config)
├── mcp/                # Modular MCP server
│   ├── server.ts       # Entry point + MCP_INSTRUCTIONS
│   ├── ui.ts           # The ui://fibx/app.html resource (the built widget, inlined)
│   ├── tools/          # Tool registrations (app, auth, wallet, trade, defi, policy)
│   └── handlers/       # Tool implementations
├── services/           # Business logic (chain, fibrous, auth, policy, walletconnect, defi, portfolio)
└── lib/                # Shared utilities (errors, fetch, format, crypto)
ui/
├── src/                # The FibX app widget — Preact, one document, no network
└── dev-host/           # A local MCP Apps host for the widget: fixtures, or a bridge to the real server

此组件由 Vite 构建为单个 HTML 文档，并通过 tsup 嵌入 dist/index.js，因此发布的包仍是单个文件，且没有运行时依赖。

开发

pnpm install
pnpm dev          # run the CLI from source
pnpm test         # vitest unit tests
pnpm typecheck    # tsc --noEmit
pnpm lint         # eslint
pnpm format:check # prettier
pnpm build        # vite (the app widget) then tsup, to dist/
pnpm dev:ui       # the app widget in a local host, against fixtures — no wallet needed

pnpm dev:ui:bridge 使用真正的 MCP 服务运行同一个主机；在那里进行的 Swap 是真实交易。

相关链接

• Fibrous Finance — 为兑换提供支持的 DEX 聚合器
• FibX Agent 文档
• npm 包
• MCP 注册表条目 — finance.fibrous/fibx

许可证

MIT