morpho-cli

morpho-cli

实验性（pre-v1.0） — 命令语法、响应架构和可用操作可能会发生变化。请始终独立核验关键输出。

查询 Morpho 协议数据并构建未签名交易。所有命令都会将 JSON 输出到 stdout。无需私钥。

npx @morpho-org/cli@latest <command> [options]

支持的链：ethereum、base、arbitrum、optimism、polygon、unichain、worldchain、katana、hyperevm、monad、stable。每条命令都必须指定 --chain。

响应架构

• 读取命令 — 所有读取工具的精确 JSON 结构；包含适用于每个响应的读取约定
• 写入命令 — PreparedOperation 结构、outcome 子架构，以及各 prepare-* 工具的输入结构

快速参考

# Read — query protocol state
npx @morpho-org/cli@latest query-vaults    --chain base [--asset-symbol USDC] [--asset-address 0x...] [--sort apy_desc|apy_asc|tvl_desc|tvl_asc] [--limit 5] [--skip 0] [--fields address,name,symbol,apyPct,tvl,tvlUsd,feePct]
npx @morpho-org/cli@latest get-vault       --chain base --address 0x...
npx @morpho-org/cli@latest query-markets   --chain base [--loan-asset 0x...] [--collateral-asset 0x...] [--sort-by supplyApy|borrowApy|netSupplyApy|netBorrowApy|supplyAssetsUsd|borrowAssetsUsd|totalLiquidityUsd] [--sort-direction asc|desc] [--limit 10] [--skip 0] [--fields supplyApy,borrowApy,totalSupply,totalBorrow,totalCollateral,totalLiquidity,supplyAssetsUsd,borrowAssetsUsd,collateralAssetsUsd,liquidityAssetsUsd]
npx @morpho-org/cli@latest get-market      --chain base --id 0x...
npx @morpho-org/cli@latest get-positions   --chain base --user-address 0x...
npx @morpho-org/cli@latest get-token-balance --chain base --user-address 0x... --token-address 0x...

# Write — prepare unsigned transactions (simulation runs automatically via @morpho-org/evm-simulation)
npx @morpho-org/cli@latest prepare-deposit              --chain base --vault-address 0x... --user-address 0x... --amount 1000
npx @morpho-org/cli@latest prepare-withdraw             --chain base --vault-address 0x... --user-address 0x... --amount max
npx @morpho-org/cli@latest prepare-supply               --chain base --market-id 0x... --user-address 0x... --amount 5000
npx @morpho-org/cli@latest prepare-borrow               --chain base --market-id 0x... --user-address 0x... --borrow-amount 1
npx @morpho-org/cli@latest prepare-repay                --chain base --market-id 0x... --user-address 0x... --amount max
npx @morpho-org/cli@latest prepare-supply-collateral    --chain base --market-id 0x... --user-address 0x... --amount 5000
npx @morpho-org/cli@latest prepare-withdraw-collateral  --chain base --market-id 0x... --user-address 0x... --amount max


# Utility
npx @morpho-org/cli@latest health-check
npx @morpho-org/cli@latest get-supported-chains

写入工作流：准备 → 呈现

每项写入操作都分为两个步骤。模拟会在 prepare-* 内自动运行。

1. 准备 — 运行 prepare-* 命令。CLI 会自动处理代币精度、授权额度、审批和模拟。返回一个 PreparedOperation，其中包含 transactions、summary、warnings、outcome（操作后的状态预览）以及可选的 simulation 块。
2. 核验模拟： 响应中可选的 simulation.transfers 会列出 EVM 模拟观测到的实际转账。配置了 Tenderly（MCP 路径中设置了 TENDERLY_* 环境变量）且运行成功时，还会包含 simulation.assetChanges[] — 每个条目包含 { type, from, to, amount, rawAmount, dollarValue, tokenInfo: { address, symbol, decimals, name } }。有 assetChanges 时，请用它生成更易读的摘要；transfers 是 Agent 端的核验依据。如果没有 simulation，且有 error 级警告（SIMULATION_REVERTED、BUNDLER_RETAINS_FUNDS、SANCTIONED_ADDRESS），则说明该交易包已知有问题 — 不要呈现交易供用户签名。
3. 呈现 — 以表格形式展示摘要、未签名交易列表、操作结果和所有警告（健康因子偏低、流动性不足等）。

每次 prepare-* 调用都会内联运行模拟 — 没有单独的模拟命令。

操作	outcome 结构	需要展示的关键字段
deposit、withdraw（金库）	outcome.vault	sharesReceived、assetsReceived、positionAssets、positionShares
supply、borrow、repay、supply_collateral、withdraw_collateral（市场）	outcome.market	healthFactor、isHealthy、maxBorrowable、utilizationBeforePct → utilizationAfterPct、borrowApyBeforePct → borrowApyAfterPct，以及操作后的 supplied / borrowed / collateral（原始整数形式的字符串 — 除以 10^decimals）

模拟失败

回滚	原因	处理方法
ERC20: insufficient allowance	缺少审批	重新准备 — CLI 应自动包含审批
ERC4626ExceededMaxWithdraw	金库流动性不足	减少金额（见下文）
insufficient balance	用户代币余额不足	告知用户
自定义错误十六进制值	协议特定	使用 get-market 或 get-vault 查询状态以诊断

部分提取

当 prepare-withdraw --amount max 无法提取全部余额时，CLI 会返回一个 PreparedOperation，其 warnings[] 会指出流动性不足。该响应仍然有效——它代表当前可提取的最大金额。

1. 向用户原样展示警告——不要悄悄接受较小的提取金额。
2. 提供两种选择：
   • 接受 CLI 准备的部分金额（检查 outcome.vault.assetsReceived 获取具体金额；也可以重新运行 prepare-withdraw，并将该金额的约 99% 作为安全缓冲，以应对准备与执行之间的利息累积，传入 --amount <value>）。
   • 等待流动性增加——底层市场的借款人偿还借款，或策展人重新分配资产后，锁定的资产便会解锁。
3. 切勿通过解析 summary 字符串来臆造金额——它是面向人的句子，不是机器可读字段。

安全规则

1. 展示前检查模拟结果——检查响应中是否存在 simulation.transfers；如果不存在，且 warnings 包含 error 级别的条目，则暂停并进行诊断后再展示
2. 切勿签名或广播——仅使用未签名的载荷
3. 关注借款的健康因子——低于 1.1 时发出警告
4. 清楚说明流动性限制，尤其是部分提取时

CLI 错误

当 npx @morpho-org/cli@latest 命令失败时，停止操作并向用户报告错误。不要：

• 使用你臆造的不同参数重试
• 转而使用其他工具或 API
• 尝试绕过缺失的必需选项
• 通过 jq 或其他过滤器传递输出——使用 CLI 内置标志（--fields、--sort-by、--limit 等）来调整响应内容

常见错误

• 忘记添加 --chain——每个命令都需要此参数，没有默认值
• 使用链 ID（1、8453）而不是名称（ethereum、base）
• 将 TokenAmount.value 除以 10^decimals——TokenAmount 的值已应用小数位数（USDC 的值 "1000" 表示 $1,000，而不是 1,000 微型 USDC）。*Pct 字段的值已按百分比缩放；*Usd 字段的值已换算为美元。只有 outcome.market.{supplied,borrowed,collateral} 和 outcome.vault.{sharesReceived,assetsReceived,positionShares} 中的原始整数字符串需要在显示时除以 /10^decimals。
• 假定小数位数为 18——USDC/USDT 有 6 位，WBTC/cbBTC 有 8 位。请从响应元数据中读取小数位数；切勿假定。
• 将原始单位作为 --amount 传入——CLI 需要人类可读的数值（1000，而不是 1000000000）
• 忽略缺失的 simulation 字段和 error 级别的警告——展示前先进行诊断
• 根据 TokenAmount.value 重新计算金额——该值已应用小数位数；直接向用户引用即可