metamask-agent-wallet

MetaMask Agentic CLI Skill

本 skill 记录了 mm CLI 的功能范围，涵盖 MetaMask Agent Wallet 身份验证、钱包生命周期、余额查询、代币转账、消息与类型化数据签名、原始交易、链发现、市场数据、代币发现、代币化现实世界资产、AI 市场与资产摘要、永续合约交易、预测市场交易、预测交易/赎回历史、代币兑换、跨链桥、DeFi 赚取/收益金库，以及 EVM calldata 解码。

使用路由表选择相关的参考文件。CLI 行为位于 references/ 中。可重复的操作模式位于 workflows/ 中。

命令路由

将用户意图匹配到命令和参考文件，然后在构建命令之前阅读参考文件。如果意图跨越多个领域，请按依赖顺序依次加载它们。

用户意图	命令	参考
查看身份验证状态	mm auth status	auth.md
登录 MetaMask Agentic CLI	mm login	auth.md
选择钱包模式并设置策略	mm init	auth.md
显示当前初始化设置	mm init show	auth.md
使用 MetaMask Mobile 扫描二维码登录	mm login qr	auth.md
通过浏览器登录（Google 或 Email）	mm login browser	auth.md
登出	mm logout	auth.md
重置 CLI 会话	mm reset	auth.md
显示 CLI 配置	mm config get	auth.md
设置 CLI 配置	mm config set	auth.md
设置 BYOK 助记词加密密码	mm wallet password set	auth.md
更改 BYOK 助记词加密密码	mm wallet password change	auth.md
移除 BYOK 助记词加密密码	mm wallet password remove	auth.md
解读原始 CLI 错误代码	AuthError, ValidationError, WALLET_ERROR	errors.md
检查 CLI、技能、环境和会话的运行状况	mm doctor	doctor.md
列出已安装的 CLI 插件	mm plugins	plugins.md
检查已安装的 CLI 插件	mm plugins inspect	plugins.md
安装 CLI 插件	mm plugins install	plugins.md
更新 CLI 插件	mm plugins update	plugins.md
卸载 CLI 插件	mm plugins uninstall	plugins.md
移除所有用户安装的 CLI 插件	mm plugins reset	plugins.md
链接本地插件目录以进行开发	mm plugins link	plugins.md
启用或禁用插件测试版	mm config set experimentalPlugins	plugins.md
将 EVM calldata 解码为易读的意图	mm decode	decode.md
创建钱包	mm wallet create	wallet.md
列出所有钱包	mm wallet list	wallet.md
切换当前钱包	mm wallet select	wallet.md
显示当前钱包详情	mm wallet show	wallet.md
显示当前钱包地址	mm wallet address	wallet.md
查看当前钱包余额	mm wallet balance	wallet.md
显示用于为当前钱包注资的二维码和地址	mm wallet add-fund	wallet.md
显示当前交易模式	mm wallet trading-mode get	wallet.md
将交易模式设为 guard 或 beast	mm wallet trading-mode set	wallet.md
查看钱包策略	mm wallet policy get	wallet.md
设置钱包策略	mm wallet policy set	wallet.md
显示项目策略模板	mm wallet policy template	wallet.md
签署纯文本消息	mm wallet sign-message	signing.md
签署 EIP-712 类型化数据	mm wallet sign-typed-data	signing.md
发送原始 EVM 交易	mm wallet send-transaction	transaction.md
转移原生代币或 ERC-20 代币	mm transfer	transfer.md
列出 CLI 支持的链	mm chains list	chain.md
列出待处理的钱包请求	mm wallet requests list	polling.md
监视钱包轮询 ID	mm wallet requests watch	polling.md
查询现货或历史价格	mm price ...	market-data.md
发现代币、代币网络或代币元数据	mm token ...	market-data.md
列出代币化现实世界资产，例如股票、ETF 和 CEF	mm token rwas	market-data.md
获取精选的 AI 市场动态	mm pulse	market-data.md
获取单项资产的 AI 生成摘要	mm pulse asset	market-data.md
获取 AI 生成的全市场概览	mm pulse market	market-data.md
列出永续合约市场	mm perps markets	perps.md
查看永续合约账户余额	mm perps balance	perps.md
列出未平仓的永续合约仓位	mm perps positions	perps.md
列出账户的资金费支付记录	mm perps funding	perps.md
显示市场资金费率历史记录	mm perps funding-rates	perps.md
获取永续合约订单报价	mm perps quote	perps.md
列出挂单中的永续合约订单	mm perps orders	perps.md
开立永续合约仓位	mm perps open	perps.md
平掉永续合约仓位	mm perps close	perps.md
修改杠杆、止盈或止损	mm perps modify	perps.md
取消挂单中的永续合约订单	mm perps cancel	perps.md
将 USDC 存入永续合约平台	mm perps deposit	perps.md
从永续合约平台提取 USDC	mm perps withdraw	perps.md
在现货账户和永续合约账户之间转移 USDC	mm perps transfer	perps.md
列出永续期货平台	mm perps list-venues	perps.md
列出平台可用的 DEX	mm perps dexs	perps.md
列出钱包的金库权益	mm perps vault list	perps.md
显示 Hyperliquid 金库详情	mm perps vault info	perps.md
将 USDC 存入 Hyperliquid 金库	mm perps vault deposit	perps.md
从 Hyperliquid 金库提取 USDC	mm perps vault withdraw	perps.md
显示 Hyperliquid 账户模式	mm perps account mode get	perps.md
切换 Hyperliquid 账户模式	mm perps account mode set	perps.md
设置 Predict 交易模式	mm predict mode	predict.md
一次性 Predict 设置	mm predict setup	predict.md
创建或刷新 Predict 凭证	mm predict auth	predict.md
修复 Predict 授权	mm predict approve	predict.md
检查 Predict 后端状态和账户设置	mm predict status	predict.md
检查你的 IP 是否因地理限制而无法访问 Polymarket	mm predict geoblock	predict.md
列出预测市场	mm predict markets list	predict.md
搜索预测市场	mm predict markets search	predict.md
查看预测市场详情	mm predict markets get	predict.md
列出 Polymarket 事件	mm predict events list	predict.md
查看 Polymarket 事件详情	mm predict events get	predict.md
列出 Polymarket 事件系列	mm predict series list	predict.md
查看 Polymarket 事件系列详情	mm predict series get	predict.md
列出 Polymarket 标签	mm predict tags list	predict.md
查看 Polymarket 标签详情	mm predict tags get	predict.md
预览预测订单费用	mm predict quote	predict.md
下达预测市场订单	mm predict place	predict.md
取消预测订单	mm predict cancel	predict.md
查看预测市场仓位	mm predict positions	predict.md
查看未结预测订单	mm predict orders	predict.md
显示完整的 Predict 投资组合快照	mm predict portfolio	predict.md
列出可赎回的获胜仓位	mm predict redeem list	predict.md
赎回获胜仓位	mm predict redeem	predict.md
查看 Predict 存款钱包余额	mm predict balance	predict.md
为 Predict 存款钱包注资	mm predict deposit	predict.md
从 Predict 存款钱包提取 pUSD	mm predict withdraw	predict.md
获取预测订单簿	mm predict book	predict.md
监视 Predict 作业	mm predict watch	predict.md
列出 Predict 交易或赎回历史记录	mm predict history	predict.md
查看特定市场的 Predict 历史记录	mm predict history get	predict.md
按哈希查询交易	mm tx	tx-history.md
列出当前钱包的近期交易	mm tx history	tx-history.md
获取兑换或跨链桥报价	mm swap quote	swap.md
执行代币兑换或跨链桥操作	mm swap execute	swap.md
查看兑换或跨链桥状态	mm swap status	swap.md
将代币跨链桥接到另一条链	mm swap execute	swap.md
支付 HTTP 402 / x402 付费墙请求	python3 scripts/x402_pay.py	x402.md
支付受 x402 限制的 MCP 工具调用	python3 scripts/x402_pay.py	x402.md
列出收益金库和 APY	mm earn markets	earn.md
查看收益金库仓位	mm earn positions	earn.md
向收益金库存入代币	mm earn supply	earn.md
从收益金库提取代币	mm earn withdraw	earn.md

工作流

CLI 行为位于 references/。可重复的模式位于 workflows/。当用户的请求是一个模式，而不是单条命令时，加载相应的工作流文件。

模式	工作流
首次设置与入门	onboarding.md
登录流程	login.md
故障排查决策	troubleshooting
Swap 报价-复核-执行流程	swap.md
Bridge 报价-复核-执行流程	bridge.md
开仓永续合约流程	perps-open-position.md
平仓永续合约流程	perps-close-position.md
修改永续合约仓位流程	perps-modify-position.md
Predict 首次设置与凭据	predict-setup.md
从 Predict 钱包存入或提取 pUSD	predict-funding.md
搜索和浏览预测市场	predict-markets.md
报价并下单预测订单	predict-place-order.md
查看或取消 Predict 订单和仓位	predict-manage-orders.md
查看 Predict 投资组合并兑换奖金	predict-portfolio.md
查看 Predict 交易与兑换历史	predict-history.md
Token 发现、价格和市场数据	market-data.md
提供 Token 以赚取收益	earn-supply.md
从收益金库提取 Token	earn-withdraw.md
支付 HTTP 402（x402）付费墙请求	x402-pay.md
支付 x402 门控的 MCP 工具调用	x402-mcp.md

全局标志

每条 mm 命令都接受以下标志：

标志	短标志	描述
--format	-f	输出格式：text、json 或 toon。在 TTY 中默认为 text，通过管道时为 json
--json		--format=json 的简写
--toon		--format=toon 的简写
--verbose	-v	在 stderr 上显示调试日志。用于故障排查

除非用户明确要求其他格式，否则对命令输出始终使用 --toon。

mm plugins 命令是例外。它们来自 oclif，不接受任何这些全局标志，因此 mm plugins --toon 会报错 Nonexistent flag: --toon。在此处请使用 --json 或纯文本。参见 plugins.md。

预检

在会话中的首次 CLI 操作之前，按顺序运行以下检查。

1. 版本兼容性

此技能针对 @metamask/agent-wallet v7.3.0 编写，版本由 frontmatter 中的 cliVersion 指定。CLI 要求 Node.js 22.18 或更高版本；在较旧的运行时中，每条命令都会在 CLI 加载前以 UNSUPPORTED_NODE 退出，退出码为 1。检查已安装的版本：

mm --version

已安装的版本是 @metamask/agent-wallet/ 后面的值，例如 @metamask/agent-wallet/7.3.0 darwin-arm64 node-v22.18.0。将其 major.minor 与固定的 cliVersion 对比。也可以检查最新发布版本（尽力而为；网络故障时静默跳过）：

npm view @metamask/agent-wallet version

如果已安装版本的 major.minor 与固定的 cliVersion 不同，或者已安装版本低于最新版本，则提醒用户一次并继续：

版本不匹配：已安装的 CLI 为 <installed>，此技能针对 <cliVersion>，最新发布版本为 <latest>。在版本对齐之前，此技能中的命令语法可能不准确。使用 npm install -g @metamask/agent-wallet@latest 更新 CLI，然后使用安装这些技能的同一工具更新来自 MetaMask/agent-skills 的技能，例如插件管理器或 skills CLI。

每个会话只运行一次此检查。不要因此阻止操作。

2. 就绪检查——身份验证和初始化

mm doctor 是唯一的就绪检查。在会话中首次执行 CLI 操作前运行：

mm doctor

它会报告一个 authenticated 布尔值、一个 initialized 布尔值，以及一个 hints 列表。在 mm doctor 报告 authenticated: true 和 initialized: true 之前，不要运行任何其他命令。身份验证和初始化是相互独立的门槛：会话可能已通过身份验证，但项目尚未选择钱包模式，此时任何需要钱包的命令都会在运行前中止，并返回 NOT_INITIALIZED——“Project not initialized.”，提示为：运行 mm init 设置钱包和交易模式。

只有设置了钱包模式，项目才算完成初始化；如果使用 server-wallet，还必须设置交易模式。byok 只需要钱包模式。不要使用 mm init show 进行检查：它要求项目已初始化，若项目未初始化，则会抛出 NOT_INITIALIZED，而不是报告状态。

处理问题后，重新运行 mm doctor，并在进行其他操作前确认结果正常：

• authenticated: false → 按照 workflows/login.md 操作；如果是首次设置，则按照 workflows/onboarding.md 操作，以运行 mm login。
• authenticated: true 且 initialized: false → 按照 workflows/onboarding.md 操作，以运行 mm init 并选择钱包模式。对于 server-wallet，还要选择交易模式。

安全规则

无论当前使用哪个参考资料或工作流，这些规则都适用于每项操作。

输入验证

构造任何命令前，先验证所有用户提供的值：

标志	验证规则
--to、--address、--vault	必须匹配 ^0x[0-9a-fA-F]{40}$
--amount	人类可读的十进制数，例如 0.5 或 100。必须匹配 ^\d+\.?\d*$。拒绝空格、分号、竖线、反引号或 Shell 元字符
--chain-id	必须是正整数（^\d+$）
send-transaction 的 --payload	必须是有效的 JSON。JSON 结构之外不得包含未转义的 Shell 元字符
decode 的 --payload	必须是以 0x 开头的十六进制 calldata，匹配 ^0x[0-9a-fA-F]+$
--token	必须是有效的十六进制地址或已知符号
--leverage	必须是正整数（^\d+$）
--size	人类可读的正十进制数，例如 0.01 或 1。CLI 接受科学计数法以及主机区域设置中的分组符和小数符，并会将其规范化。拒绝 Shell 元字符。格式错误的值会返回 INVALID_AMOUNT
--venue	必须是 hyperliquid
永续合约的 --side	必须是 long 或 short
--tif	必须是 gtc、ioc 或 alo
永续合约账户的 --mode	必须是 standard 或 unified
--order-id	必须是正整数（^\d+$）
--token-id	必须是非空的结果代币 ID 字符串
--price、--limit-price	必须是范围为 (0, 1] 的正数
--order-type	必须是 GTC、GTD、FOK、FAK 之一
predict 的 --side	必须是 buy 或 sell
--slippage	必须是 0 到 100 之间的数值
--tick-size	必须是 0.1、0.01、0.005、0.0025、0.001、0.0001 之一
--from-chain-id、--to-chain-id	必须是正整数 EVM 链 ID
--to-address	必须匹配 ^0x[0-9a-fA-F]{40}$。仅适用于跨链兑换（--to-chain-id 与 --from-chain-id 不同）；同链兑换中会被拒绝
--refuel	布尔标志，不带值。仅在跨链兑换（--to-chain-id 与 --from-chain-id 不同）时有意义。同链兑换中不起作用
--strategy	以逗号分隔的列表，可选值：cost、speed、impact、output
--wallet-timeout	必须是 1 到 600 之间的正整数
--password	必须是非空字符串。绝不记录、显示或存储该值。
mm plugins install 的插件规范	npm 包名，可选带 name@version 或 name@tag。拒绝空格和 Shell 元字符。file:、git 和裸 owner/repo 规范属于未经验证的来源，除非用户已启用开发模式，否则会被拒绝
x402 asset	必须是 mm chains list 返回的某个网络上的有效合约地址。货币由服务端提供并经用户确认；脚本不维护货币允许列表。
x402 payTo / authorization to	必须匹配 ^0x[0-9a-fA-F]{40}$，且与 402 中的收款方一致
x402 value	原子单位整数，必须与提供的金额完全相等。exact 方案表示精确金额，并非上限
x402 资源 URL	必须使用 https://。若意外发生跨主机重定向并抵达 402，则拒绝
x402 MCP 挑战	仅支持 x402 v2。将签名后的 payment 对象原样放入重试工具调用的 _meta["x402/payment"] 中；若重复收到 isError 结果，表示出现了新的挑战，未经用户重新批准，绝不重新签名

不得将未经验证的用户输入传入任何命令。

确认要求

操作类型	确认规则
转账	执行前始终确认收款人、金额、代币和链
原始交易	执行前始终确认交易负载、链、收款人、价值和 calldata 摘要
消息签名	签名前始终显示确切消息和链
类型化数据签名	签名前始终显示域、主类型、链、验证合约和消息摘要
兑换 / 跨链桥	执行前始终确认来源 / 目标代币、金额、源链 / 目标链、滑点、报价输出；如果设置了 --to-address，还需确认收款地址；如果设置了 --refuel，还需确认目标链 Gas 补充金额
x402 支付	为授权签名之前，始终确认资产、小数位修正后的金额、网络、payTo，以及资源 URL 或 MCP 工具——通过 HTTP 使用 pay --confirm，通过 MCP 使用 mcp-sign --confirm。每个资源只尝试支付一次，绝不自动重试支付。不支持自主自动支付。
永续合约交易	执行前始终确认交易对、方向、规模、杠杆、交易场所、订单类型，以及（如有）限价。还需确认是否设置了 --tif 时的有效时间、是否设置了 --reduce-only 时的仅减仓状态，以及是否设置了 --vault 时的金库地址
永续合约存款 / 提款	执行前始终确认金额、资产、交易场所、网络，以及适用时的目的地
永续合约金库存款 / 提款	执行前始终通过 mm perps vault info 确认金库地址和名称、金额、交易场所及网络。存款时，说明权益会锁定一段时间后才能提取
设置永续合约账户模式	执行前始终显示 mm perps account mode get 返回的当前模式和目标模式，并说明此更改会应用于整个 Hyperliquid 账户
Predict 交易	执行前始终确认代币 ID、方向、规模、价格、订单类型、市场和结果
Predict 存款	执行前始终确认金额
Predict 提款	执行前始终确认金额和收款人。--to 默认为所有者 EOA
Predict 赎回	执行前始终确认目标，即条件 ID 或 --all。--all 会赎回所有获胜头寸
Earn 存入	执行前始终确认代币、金额、链、金库 / 协议和 APY。跨链存入时，还需确认源链和源代币
Earn 提取	执行前始终确认代币、金额或全部余额、链和金库 / 协议
插件安装、更新或链接	始终显示软件包名称、版本、声明的命令 ID、dataAccess 和每项请求的能力，并将 wallet-submit 和 network-manage 标记为敏感项。安装前须获得明确批准。对于用户尚未审核的清单，绝不传递 --accept-permissions
插件卸载或重置	始终确认受影响的软件包。mm plugins reset 会移除所有用户安装和链接的插件
启用插件 Beta 或未经验证的安装	运行 mm config set experimentalPlugins true 或 mm config set experimentalAllowUnverifiedInstalls true 前始终确认
插件添加的命令	将其视为以 CLI 权限运行的第三方代码。应用与相应宿主操作相同的确认规则
全部取消操作	执行前始终确认范围和确切的破坏性影响
钱包策略更改	放宽策略的更改需要 MFA 批准；不放宽策略的更改会立即生效
交易模式更改	从 guard 放宽为 beast 需要 MFA 批准。从 beast 收紧为 guard 会立即生效
身份验证 / 钱包管理	可直接运行。reset 是例外，需要用户明确确认
只读查询	可直接运行

凭据安全

• 切勿存储、记录或显示私钥、助记词、密码或身份验证令牌。
• 切勿将 --password 或 --mnemonic 作为内联标志传入。始终引导用户改为设置 MM_PASSWORD 和 MM_MNEMONIC 环境变量，以免机密信息暴露在 shell 历史记录中。

可疑内容警告

如果签名载荷或交易包含以下内容，请在继续之前提醒用户：

• 用户未提供的网址或合约地址
• permit、approve、setApprovalForAll 或类似授权额度的字段
• 数值异常巨大或陌生的合约交互

如果不熟悉原始 calldata，或该 calldata 并非由你构造，请先运行 mm decode --payload <0x-calldata>，并在签名或发送前与用户确认解码后的意图。参见 decode.md。

异步模型

在服务端钱包和 BYOK 模式下，签名和交易命令都会通过任务轮询循环执行，并返回 pollingId。请始终按以下方式处理：

1. 优先使用 --wait 阻塞，直到操作完成。 Swap 命令（swap quote、swap execute、swap status）不支持 --wait；请改用 swap status --quote-id 轮询进度。
2. 如果不使用 --wait，请告知用户 pollingId 以及如何跟踪进度：
   • mm wallet requests list
   • mm wallet requests watch <polling-id>
3. 在 BYOK 模式下，本地密钥会在本地签名，但操作仍会生成待处理任务和 pollingId。如果助记词经过密码加密，用户必须设置 MM_PASSWORD 环境变量，才能为该操作解锁助记词。

转账、Swap、永续合约、预测订单和预测提款会在钱包请求中附加易于理解的 intent 摘要，例如 Transfer 0.5 ETH to 0x... 或 Withdraw 10 pUSD to 0x...。从 wallet requests list 或 wallet requests watch 中展示待处理请求时，请显示 intent 摘要，方便用户确认其批准的操作。

MFA 批准暂停

需要带外 MFA 批准的钱包任务会暂停在 AWAITING_MFA 状态。请扫描命令标准输出中的字面标记 AWAITING_MFA 来检测此暂停。 对于较旧版本的 CLI，请勿仅凭自由文本推断 MFA；从 CLI v6.1.5 起，所有输出模式都会始终发出该标记。

输出模式	检测方式
--json / 管道标准输出	包含 "_notice":{"kind":"AWAITING_MFA",...} 的 NDJSON 行
普通 TTY 或 Ink REPL	包含 [AWAITING_MFA] 的标准输出行，例如 ⚠ [AWAITING_MFA] Approve in MetaMask mobile.

出现 AWAITING_MFA 时：

1. 将命令视为正在等待用户批准，而不是失败、卡住或已完成。
2. 向用户展示通知中的人工操作说明。
3. 如果通知或命令输出中包含 pollingId，请告知用户可以使用 mm wallet requests watch <polling-id> 跟踪完成情况。
4. 当任务仍在等待处理时，不要重试同一钱包操作。
5. 对于 mm swap execute、mm earn supply 或 mm earn withdraw，如果 MFA 暂停时尚无哈希，命令可能会返回 EXECUTE_FAILED，并附带说明批准仍在等待中以及 mm wallet requests watch <polling-id> 的消息——这仍然是 MFA 暂停，并非缺少哈希。

有关批准界面和恢复步骤，请参见 troubleshooting.md。

响应风格

• 静默路由。不要宣布正在加载哪个参考资料。
• 原样展示命令的错误。不要掩盖或改写错误。
• 如果命令失败，请检查 mm <command> --help，并据此提供指导。