metamask-agent-wallet

42 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

• skills/metamask-agent-wallet/SKILL.md28 KB5ad19a9693f3upstream ↗

  ---
  name: metamask-agent-wallet
  description: Use when the user asks anything about blockchain wallets, transactions, signing, token transfers, supported chains, wallet balances, perpetual futures trading, funding rates, and Hyperliquid vaults, prediction markets, token swaps, cross-chain bridges, market data, token discovery, tokenized real-world assets, RWAs, AI-generated market and asset summaries via pulse, decoding EVM calldata, DeFi earn/yield vaults, installing or removing third-party `mm` CLI plugins, or authentication via the MetaMask Agentic CLI; also when an HTTP request returns 402 Payment Required / x402, when an MCP tool call returns an x402 payment-required result, or the agent needs to pay for a paywalled API, endpoint, file, tool, or resource. Single entry point for all mm CLI operations. Financial operations are protected by server-enforced access controls including MFA approval, configurable wallet policies, and trading-mode guards (guard/beast) that restrict operation scope independently of the agent.
  license: MIT
  metadata:
    author: metamask
    version: "7.10.0"
    cliVersion: "7.3.0"
  ---
  
  # MetaMask Agentic CLI Skill
  
  This skill documents the `mm` CLI surface for MetaMask Agent Wallet authentication, wallet lifecycle, balance queries, token transfers, message and typed-data signing, raw transactions, chain discovery, market data, token discovery, tokenized real-world assets, AI market and asset summaries, perpetual futures trading, prediction market trading, prediction trade/redeem history, token swaps, cross-chain bridges, DeFi earn/yield vaults, and EVM calldata decoding.
  
  Use the routing table to select the relevant reference file. CLI behavior lives in `references/`. Repeatable operational patterns live in `workflows/`.
  
  ## Command Routing
  
  Match the user's intent to a command and reference file, then read the reference before constructing a command. If intent spans multiple domains, load them sequentially in dependency order.
  
  | User Intent | Command | Reference |
  | --- | --- | --- |
  | Check authentication status | `mm auth status` | [auth.md](references/auth.md) |
  | Login in MetaMask Agentic CLI | `mm login` | [auth.md](references/auth.md) |
  | Choose a wallet mode and set up policies | `mm init` | [auth.md](references/auth.md) |
  | Show current init settings | `mm init show` | [auth.md](references/auth.md) |
  | Sign in via QR code with MetaMask Mobile | `mm login qr` | [auth.md](references/auth.md) |
  | Sign in via browser (Google or Email) | `mm login browser` | [auth.md](references/auth.md) |
  | Sign out | `mm logout` | [auth.md](references/auth.md) |
  | Reset CLI session | `mm reset` | [auth.md](references/auth.md) |
  | Show CLI configuration | `mm config get` | [auth.md](references/auth.md) |
  | Set CLI configuration | `mm config set` | [auth.md](references/auth.md) |
  | Set BYOK mnemonic encryption password | `mm wallet password set` | [auth.md](references/auth.md) |
  | Change BYOK mnemonic encryption password | `mm wallet password change` | [auth.md](references/auth.md) |
  | Remove BYOK mnemonic encryption password | `mm wallet password remove` | [auth.md](references/auth.md) |
  | Interpret raw CLI error codes | `AuthError`, `ValidationError`, `WALLET_ERROR` | [errors.md](references/errors.md) |
  | Inspect CLI, skills, environment, and session health | `mm doctor` | [doctor.md](references/doctor.md) |
  | List installed CLI plugins | `mm plugins` | [plugins.md](references/plugins.md) |
  | Inspect an installed CLI plugin | `mm plugins inspect` | [plugins.md](references/plugins.md) |
  | Install a CLI plugin | `mm plugins install` | [plugins.md](references/plugins.md) |
  | Update a CLI plugin | `mm plugins update` | [plugins.md](references/plugins.md) |
  | Uninstall a CLI plugin | `mm plugins uninstall` | [plugins.md](references/plugins.md) |
  | Remove all user-installed CLI plugins | `mm plugins reset` | [plugins.md](references/plugins.md) |
  | Link a local plugin directory for development | `mm plugins link` | [plugins.md](references/plugins.md) |
  | Enable or disable the plugin beta | `mm config set experimentalPlugins` | [plugins.md](references/plugins.md) |
  | Decode EVM calldata into a human-readable intent | `mm decode` | [decode.md](references/decode.md) |
  | Create a wallet | `mm wallet create` | [wallet.md](references/wallet.md) |
  | List all wallets | `mm wallet list` | [wallet.md](references/wallet.md) |
  | Switch active wallet | `mm wallet select` | [wallet.md](references/wallet.md) |
  | Show active wallet details | `mm wallet show` | [wallet.md](references/wallet.md) |
  | Show active wallet address | `mm wallet address` | [wallet.md](references/wallet.md) |
  | Check the active wallet balance | `mm wallet balance` | [wallet.md](references/wallet.md) |
  | Show a QR code and address to fund the active wallet | `mm wallet add-fund` | [wallet.md](references/wallet.md) |
  | Show current trading mode | `mm wallet trading-mode get` | [wallet.md](references/wallet.md) |
  | Set trading mode to guard or beast | `mm wallet trading-mode set` | [wallet.md](references/wallet.md) |
  | View wallet policy | `mm wallet policy get` | [wallet.md](references/wallet.md) |
  | Set wallet policy | `mm wallet policy set` | [wallet.md](references/wallet.md) |
  | Show project policy template | `mm wallet policy template` | [wallet.md](references/wallet.md) |
  | Sign a plaintext message | `mm wallet sign-message` | [signing.md](references/signing.md) |
  | Sign EIP-712 typed data | `mm wallet sign-typed-data` | [signing.md](references/signing.md) |
  | Send a raw EVM transaction | `mm wallet send-transaction` | [transaction.md](references/transaction.md) |
  | Transfer native tokens or ERC-20 tokens | `mm transfer` | [transfer.md](references/transfer.md) |
  | List supported chains by the CLI | `mm chains list` | [chain.md](references/chain.md) |
  | List pending wallet requests | `mm wallet requests list` | [polling.md](references/polling.md) |
  | Watch a wallet polling id | `mm wallet requests watch` | [polling.md](references/polling.md) |
  | Query spot or historical prices | `mm price ...` | [market-data.md](references/market-data.md) |
  | Discover tokens, token networks, or token metadata | `mm token ...` | [market-data.md](references/market-data.md) |
  | List tokenized real-world assets such as stocks, ETFs, and CEFs | `mm token rwas` | [market-data.md](references/market-data.md) |
  | Get the featured AI market highlight | `mm pulse` | [market-data.md](references/market-data.md) |
  | Get an AI-generated summary for one asset | `mm pulse asset` | [market-data.md](references/market-data.md) |
  | Get the AI-generated market-wide overview | `mm pulse market` | [market-data.md](references/market-data.md) |
  | List perpetual markets | `mm perps markets` | [perps.md](references/perps.md) |
  | Check perps account balance | `mm perps balance` | [perps.md](references/perps.md) |
  | List open perpetual positions | `mm perps positions` | [perps.md](references/perps.md) |
  | List funding payments for the account | `mm perps funding` | [perps.md](references/perps.md) |
  | Show market funding rate history | `mm perps funding-rates` | [perps.md](references/perps.md) |
  | Get a quote for a perpetual order | `mm perps quote` | [perps.md](references/perps.md) |
  | List resting perpetual orders | `mm perps orders` | [perps.md](references/perps.md) |
  | Open a perpetual position | `mm perps open` | [perps.md](references/perps.md) |
  | Close a perpetual position | `mm perps close` | [perps.md](references/perps.md) |
  | Modify leverage, take-profit, or stop-loss | `mm perps modify` | [perps.md](references/perps.md) |
  | Cancel a resting perps order | `mm perps cancel` | [perps.md](references/perps.md) |
  | Deposit USDC into a perps venue | `mm perps deposit` | [perps.md](references/perps.md) |
  | Withdraw USDC from a perps venue | `mm perps withdraw` | [perps.md](references/perps.md) |
  | Transfer USDC between spot and perp accounts | `mm perps transfer` | [perps.md](references/perps.md) |
  | List perpetual futures venues | `mm perps list-venues` | [perps.md](references/perps.md) |
  | List available DEXs for a venue | `mm perps dexs` | [perps.md](references/perps.md) |
  | List vault equities for the wallet | `mm perps vault list` | [perps.md](references/perps.md) |
  | Show Hyperliquid vault details | `mm perps vault info` | [perps.md](references/perps.md) |
  | Deposit USDC into a Hyperliquid vault | `mm perps vault deposit` | [perps.md](references/perps.md) |
  | Withdraw USDC from a Hyperliquid vault | `mm perps vault withdraw` | [perps.md](references/perps.md) |
  | Show Hyperliquid account mode | `mm perps account mode get` | [perps.md](references/perps.md) |
  | Switch Hyperliquid account mode | `mm perps account mode set` | [perps.md](references/perps.md) |
  | Set Predict trading mode | `mm predict mode` | [predict.md](references/predict.md) |
  | One-time Predict setup | `mm predict setup` | [predict.md](references/predict.md) |
  | Create or refresh Predict credentials | `mm predict auth` | [predict.md](references/predict.md) |
  | Repair Predict approvals | `mm predict approve` | [predict.md](references/predict.md) |
  | Check Predict back-end status and account setup | `mm predict status` | [predict.md](references/predict.md) |
  | Check if Polymarket is geoblocked for your IP | `mm predict geoblock` | [predict.md](references/predict.md) |
  | List prediction markets | `mm predict markets list` | [predict.md](references/predict.md) |
  | Search prediction markets | `mm predict markets search` | [predict.md](references/predict.md) |
  | Inspect a prediction market | `mm predict markets get` | [predict.md](references/predict.md) |
  | List Polymarket events | `mm predict events list` | [predict.md](references/predict.md) |
  | Inspect a Polymarket event | `mm predict events get` | [predict.md](references/predict.md) |
  | List Polymarket event series | `mm predict series list` | [predict.md](references/predict.md) |
  | Inspect a Polymarket event series | `mm predict series get` | [predict.md](references/predict.md) |
  | List Polymarket tags | `mm predict tags list` | [predict.md](references/predict.md) |
  | Inspect a Polymarket tag | `mm predict tags get` | [predict.md](references/predict.md) |
  | Preview a prediction order cost | `mm predict quote` | [predict.md](references/predict.md) |
  | Place a prediction market order | `mm predict place` | [predict.md](references/predict.md) |
  | Cancel prediction orders | `mm predict cancel` | [predict.md](references/predict.md) |
  | View prediction market positions | `mm predict positions` | [predict.md](references/predict.md) |
  | View open prediction orders | `mm predict orders` | [predict.md](references/predict.md) |
  | Show full Predict portfolio snapshot | `mm predict portfolio` | [predict.md](references/predict.md) |
  | List redeemable winning positions | `mm predict redeem list` | [predict.md](references/predict.md) |
  | Redeem winning positions | `mm predict redeem` | [predict.md](references/predict.md) |
  | Check Predict deposit wallet balance | `mm predict balance` | [predict.md](references/predict.md) |
  | Fund Predict deposit wallet | `mm predict deposit` | [predict.md](references/predict.md) |
  | Withdraw pUSD from Predict deposit wallet | `mm predict withdraw` | [predict.md](references/predict.md) |
  | Fetch prediction order book | `mm predict book` | [predict.md](references/predict.md) |
  | Watch a Predict job | `mm predict watch` | [predict.md](references/predict.md) |
  | List Predict trade or redeem history | `mm predict history` | [predict.md](references/predict.md) |
  | Inspect Predict history for a specific market | `mm predict history get` | [predict.md](references/predict.md) |
  | Look up a transaction by hash | `mm tx` | [tx-history.md](references/tx-history.md) |
  | List recent transactions for the active wallet | `mm tx history` | [tx-history.md](references/tx-history.md) |
  | Get a swap or bridge quote | `mm swap quote` | [swap.md](references/swap.md) |
  | Execute a token swap or bridge | `mm swap execute` | [swap.md](references/swap.md) |
  | Check swap or bridge status | `mm swap status` | [swap.md](references/swap.md) |
  | Bridge tokens to another chain | `mm swap execute` | [swap.md](references/swap.md) |
  | Pay an HTTP `402` / x402 paywalled request | `python3 scripts/x402_pay.py` | [x402.md](references/x402.md) |
  | Pay an x402-gated MCP tool call | `python3 scripts/x402_pay.py` | [x402.md](references/x402.md) |
  | List earn vaults and APYs | `mm earn markets` | [earn.md](references/earn.md) |
  | View earn vault positions | `mm earn positions` | [earn.md](references/earn.md) |
  | Supply tokens to an earn vault | `mm earn supply` | [earn.md](references/earn.md) |
  | Withdraw tokens from an earn vault | `mm earn withdraw` | [earn.md](references/earn.md) |
  
  ## Workflows
  
  CLI behavior lives in `references/`. Repeatable patterns live in `workflows/`. Load a workflow file when the user's request is a pattern, not a single command.
  
  | Pattern | Workflow |
  | --- | --- |
  | First time setup and onboarding | [onboarding.md](workflows/onboarding.md) |
  | Login flow | [login.md](workflows/login.md) |
  | Troubleshooting decision tree | [troubleshooting.md](workflows/troubleshooting.md) |
  | Swap quote-review-execute flow | [swap.md](workflows/swap.md) |
  | Bridge quote-review-execute flow | [bridge.md](workflows/bridge.md) |
  | Open a perpetual position flow | [perps-open-position.md](workflows/perps-open-position.md) |
  | Close a perpetual position flow | [perps-close-position.md](workflows/perps-close-position.md) |
  | Modify a perpetual position flow | [perps-modify-position.md](workflows/perps-modify-position.md) |
  | Predict first-time setup and credentials | [predict-setup.md](workflows/predict-setup.md) |
  | Deposit or withdraw pUSD from Predict wallet | [predict-funding.md](workflows/predict-funding.md) |
  | Search and browse prediction markets | [predict-markets.md](workflows/predict-markets.md) |
  | Quote and place a prediction order | [predict-place-order.md](workflows/predict-place-order.md) |
  | View or cancel Predict orders and positions | [predict-manage-orders.md](workflows/predict-manage-orders.md) |
  | View Predict portfolio and redeem winnings | [predict-portfolio.md](workflows/predict-portfolio.md) |
  | View Predict trade and redeem history | [predict-history.md](workflows/predict-history.md) |
  | Token discovery, prices, and market data | [market-data.md](workflows/market-data.md) |
  | Supply tokens to earn yield | [earn-supply.md](workflows/earn-supply.md) |
  | Withdraw tokens from an earn vault | [earn-withdraw.md](workflows/earn-withdraw.md) |
  | Pay an HTTP `402` (x402) paywalled request | [x402-pay.md](workflows/x402-pay.md) |
  | Pay an x402-gated MCP tool call | [x402-mcp.md](workflows/x402-mcp.md) |
  
  ## Global Flags
  
  Every `mm` command accepts these flags:
  
  | Flag | Short | Description |
  | --- | --- | --- |
  | `--format` | `-f` | Output format: `text`, `json`, or `toon`. Defaults to `text` in TTY, `json` when piped |
  | `--json` | | Shorthand for `--format=json` |
  | `--toon` | | Shorthand for `--format=toon` |
  | `--verbose` | `-v` | Show debug logs on stderr. Use for troubleshooting |
  
  Always use `--toon` for command output unless the user explicitly requests a different format.
  
  The `mm plugins` commands are the exception. They come from oclif and accept none of these global flags, so `mm plugins --toon` fails with `Nonexistent flag: --toon`. Use `--json` or plain text there. See [plugins.md](references/plugins.md).
  
  ## Preflight
  
  Run these checks before the first CLI operation in a session, in order.
  
  ### 1. Version compatibility
  
  
  This skill is written for `@metamask/agent-wallet` v7.3.0, as specified by `cliVersion` in the frontmatter. The CLI requires Node.js 22.18 or later; on an older runtime every command exits 1 with `UNSUPPORTED_NODE` before the CLI loads. Check the installed version:
  
  ```bash
  mm --version
  ```
  
  The installed version is the value after `@metamask/agent-wallet/`, such as `@metamask/agent-wallet/7.3.0 darwin-arm64 node-v22.18.0`. Compare its `major.minor` against the pinned `cliVersion`. Optionally check the latest published version (best-effort, skip silently on network failure):
  
  ```bash
  npm view @metamask/agent-wallet version
  ```
  
  If the installed `major.minor` differs from the pinned `cliVersion`, or the installed version is behind the latest release, warn the user once and continue:
  
  > Version mismatch: installed CLI `<installed>`, this skill targets `<cliVersion>`, latest release is `<latest>`. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with `npm install -g @metamask/agent-wallet@latest`, then update the skills from `MetaMask/agent-skills` with the same tool that installed them, such as the plugin manager or the `skills` CLI.
  
  Run this check once per session. Do not block operations on it.
  
  ### 2. Readiness gate — authentication and initialization
  
  `mm doctor` is the single readiness check. Run it before the first CLI operation in a session:
  
  ```bash
  mm doctor
  ```
  
  It reports an `authenticated` boolean, an `initialized` boolean, and a list of `hints`. Do not run any other command until `mm doctor` reports both `authenticated: true` and `initialized: true`. Authentication and initialization are independent gates: a session can be authenticated while the project has no wallet mode selected, in which case any command that needs a wallet aborts before running with `NOT_INITIALIZED` — "Project not initialized." with hint: Run `mm init` to set up wallet and trading modes.
  
  A project counts as initialized only when a wallet mode is set — and, for `server-wallet`, a trading mode is set as well. `byok` needs only the wallet mode. Do not use `mm init show` as the check: it requires an initialized project and throws `NOT_INITIALIZED` on an uninitialized one rather than reporting state.
  
  Remediate, then re-run `mm doctor` and confirm a clean result before doing anything else:
  
  - `authenticated: false` → follow `workflows/login.md`, or `workflows/onboarding.md` for first-time setup, to run `mm login`.
  - `authenticated: true` and `initialized: false` → follow `workflows/onboarding.md` to run `mm init` and select a wallet mode. For server-wallet, also select a trading mode.
  
  ## Safety Rules
  
  These rules apply to every operation, regardless of which reference or workflow is active.
  
  ### Input Validation
  
  Before constructing any command, validate all user-provided values:
  
  | Flag | Validation rule |
  | --- | --- |
  | `--to`, `--address`, `--vault` | Must match `^0x[0-9a-fA-F]{40}$` |
  | `--amount` | Human-readable decimal such as 0.5 or 100. Must match `^\d+\.?\d*$`. Reject spaces, semicolons, pipes, backticks, or shell metacharacters |
  | `--chain-id` | Must be a positive integer (`^\d+$`) |
  | `--payload` for send-transaction | Must be valid JSON. No unescaped shell metacharacters outside the JSON structure |
  | `--payload` for decode | Must be 0x-prefixed hex calldata, matching `^0x[0-9a-fA-F]+$` |
  | `--token` | Must be a valid hex address or known symbol |
  | `--leverage` | Must be a positive integer (`^\d+$`) |
  | `--size` | Human-readable positive decimal such as 0.01 or 1. Scientific notation and host-locale grouping/decimals are accepted and canonicalized by the CLI. Reject shell metacharacters. Malformed values return `INVALID_AMOUNT` |
  | `--venue` | Must be `hyperliquid` |
  | `--side` for perps | Must be `long` or `short` |
  | `--tif` | Must be `gtc`, `ioc`, or `alo` |
  | `--mode` for perps account | Must be `standard` or `unified` |
  | `--order-id` | Must be a positive integer (`^\d+$`) |
  | `--token-id` | Must be a non-empty outcome token ID string |
  | `--price`, `--limit-price` | Must be a positive number in range `(0, 1]` |
  | `--order-type` | Must be one of `GTC`, `GTD`, `FOK`, `FAK` |
  | `--side` for predict | Must be `buy` or `sell` |
  | `--slippage` | Must be a number between 0 and 100 |
  | `--tick-size` | Must be one of `0.1`, `0.01`, `0.005`, `0.0025`, `0.001`, `0.0001` |
  | `--from-chain-id`, `--to-chain-id` | Must be a positive integer EVM chain ID |
  | `--to-address` | Must match `^0x[0-9a-fA-F]{40}$`. Only valid for cross-chain swaps (`--to-chain-id` differs from `--from-chain-id`); rejected for same-chain swaps |
  | `--refuel` | Boolean flag, no value. Only meaningful for cross-chain swaps where `--to-chain-id` differs from `--from-chain-id`. No effect on same-chain swaps |
  | `--strategy` | Comma-separated list from: `cost`, `speed`, `impact`, `output` |
  | `--wallet-timeout` | Must be a positive integer between 1 and 600 |
  | `--password` | Must be a non-empty string. Never log, display, or store the value. |
  | Plugin spec for `mm plugins install` | An npm package name, optionally `name@version` or `name@tag`. Reject spaces and shell metacharacters. `file:`, git, and bare `owner/repo` specs are unverified sources and are refused unless the user has enabled dev mode |
  | x402 `asset` | Must be a valid contract address on a network returned by `mm chains list`. The currency choice is the server's offer confirmed by the user; the script keeps no currency allowlist. |
  | x402 `payTo` / authorization `to` | Must match `^0x[0-9a-fA-F]{40}$` and equal the recipient in the `402` |
  | x402 `value` | Atomic-unit integer that exactly equals the offered amount. The `exact` scheme is not a maximum |
  | x402 resource URL | Must be `https://`. Reject a `402` reached via an unexpected cross-host redirect |
  | x402 MCP challenge | x402 v2 only. The signed `payment` object goes, as-is, in `_meta["x402/payment"]` of the retried tool call; a repeated `isError` result is a new challenge, never re-sign it without new user approval |
  
  Do not pass unvalidated user input into any command.
  
  ### Confirmation Requirements
  
  | Operation type | Confirmation rule |
  | --- | --- |
  | Transfers | Always confirm recipient, amount, token, and chain before executing |
  | Raw transactions | Always confirm transaction payload, chain, recipient, value, and calldata summary before executing |
  | Message signing | Always show exact message and chain before signing |
  | Typed-data signing | Always show domain, primary type, chain, verifying contract, and message summary before signing |
  | Swaps / bridges | Always confirm from/to tokens, amount, source/destination chain, slippage, quoted output, recipient address if `--to-address` is set, and the destination gas top-up if `--refuel` is set before executing |
  | x402 payments | Always confirm asset, decimals-correct amount, network, `payTo`, and resource URL or MCP tool before signing the authorization — over HTTP with `pay --confirm`, over MCP with `mcp-sign --confirm`. One payment attempt per resource, never auto-retry a payment. Autonomous auto-pay is not supported. |
  | Perps trading | Always confirm symbol, side, size, leverage, venue, order type, and limit price if present before executing. Also confirm time in force if `--tif` is set, that the order is reduce-only if `--reduce-only` is set, and the vault address if `--vault` is set |
  | Perps deposit/withdraw | Always confirm amount, asset, venue, network, and destination where applicable before executing |
  | Perps vault deposit/withdraw | Always confirm vault address and name from `mm perps vault info`, amount, venue, and network before executing. For deposits, say that the equity is locked for a period before it can be withdrawn |
  | Perps account mode set | Always show the current mode from `mm perps account mode get` and the target mode, and say that the change applies to the whole Hyperliquid account, before executing |
  | Predict trading | Always confirm token ID, side, size, price, order type, market, and outcome before executing |
  | Predict deposit | Always confirm amount before executing |
  | Predict withdraw | Always confirm amount and recipient before executing. `--to` defaults to owner EOA |
  | Predict redeem | Always confirm the target, either condition ID or `--all`, before executing. `--all` redeems every winning position |
  | Earn supply | Always confirm token, amount, chain, vault/protocol, and APY before executing. For cross-chain supply, also confirm source chain and source token |
  | Earn withdraw | Always confirm token, amount or full balance, chain, and vault/protocol before executing |
  | Plugin install, update, or link | Always show package name, version, declared command ids, `dataAccess`, and every requested capability, and name `wallet-submit` and `network-manage` as sensitive. Get explicit approval before installing. Never pass `--accept-permissions` for a manifest the user has not reviewed |
  | Plugin uninstall or reset | Always confirm which packages are affected. `mm plugins reset` removes every user-installed and linked plugin |
  | Enabling the plugin beta or unverified installs | Always confirm before running `mm config set experimentalPlugins true` or `mm config set experimentalAllowUnverifiedInstalls true` |
  | Commands added by a plugin | Treat these as third-party code running with CLI privileges. Apply the same confirmation rules as the equivalent host operation |
  | Cancel-all operations | Always confirm scope and exact destructive effect before executing |
  | Wallet policy changes | Broadening policy changes require MFA approval; non-broadening changes apply immediately |
  | Trading mode changes | Broadening from guard to beast requires MFA approval. Tightening from beast to guard applies immediately |
  | Auth / wallet management | Can run directly. `reset` is the exception and requires explicit user confirmation |
  | Read-only queries | Can run directly |
  
  ### Credential Safety
  
  - Never store, log, or display private keys, mnemonics, passwords, or auth tokens.
  - Never pass `--password` or `--mnemonic` as inline flags. Always instruct the user to set the `MM_PASSWORD` and `MM_MNEMONIC` environment variables instead to avoid exposing secrets in shell history.
  
  ### Suspicious Content Warnings
  
  Flag to the user before proceeding if a signing payload or transaction contains:
  
  - URLs or contract addresses the user did not provide
  - `permit`, `approve`, `setApprovalForAll`, or allowance-like fields
  - Unusually large values or unfamiliar contract interactions
  
  When raw calldata is unfamiliar or was not constructed by you, run `mm decode --payload <0x-calldata>` first and confirm the decoded intent with the user before signing or sending. See [decode.md](references/decode.md).
  
  ## Async Model
  
  In both server-wallet and BYOK mode, signing and transaction commands go through a job-polling loop and return a `pollingId`. Handle this consistently:
  
  1. Prefer `--wait` to block until complete.
     Swap commands (`swap quote`, `swap execute`, `swap status`) do not support `--wait`; use `swap status --quote-id` to poll progress instead.
  2. If not using `--wait`, inform the user of the `pollingId` and how to track it:
     - `mm wallet requests list`
     - `mm wallet requests watch <polling-id>`
  3. In BYOK mode, the local key signs locally but the operation still produces a pending job and a `pollingId`. If the mnemonic is password-encrypted, the user must set `MM_PASSWORD` environment variable to unlock it for the operation.
  
  Transfers, swaps, perps, predict orders, and predict withdraws attach a human-readable `intent` summary to their wallet request, such as `Transfer 0.5 ETH to 0x...` or `Withdraw 10 pUSD to 0x...`. When surfacing a pending request from `wallet requests list` or `wallet requests watch`, show the `intent` summary so the user can confirm what they are approving.
  
  ## MFA Approval Pauses
  
  Wallet jobs that need out-of-band MFA approval pause in `AWAITING_MFA`. **Detect this pause by scanning command stdout for the literal token `AWAITING_MFA`.** Do not infer MFA from free-text alone on older CLIs; from CLI v6.1.5 onward every output mode emits the token consistently.
  
  | Output mode | How to detect |
  | --- | --- |
  | `--json` / piped stdout | An NDJSON line containing `"_notice":{"kind":"AWAITING_MFA",...}` |
  | Plain TTY or Ink REPL | A stdout line containing `[AWAITING_MFA]`, e.g. `⚠ [AWAITING_MFA] Approve in MetaMask mobile.` |
  
  When `AWAITING_MFA` appears:
  
  1. Treat the command as **waiting for user approval**, not failed, hung, or complete.
  2. Surface the human instruction from the notice to the user.
  3. If a `pollingId` is present in the notice or command output, tell the user they can track completion with `mm wallet requests watch <polling-id>`.
  4. Do **not** retry the same wallet operation while the job is still pending.
  5. On `mm swap execute`, `mm earn supply`, or `mm earn withdraw`, an MFA pause with no hash yet may return `EXECUTE_FAILED` with a message naming the approval wait and `mm wallet requests watch <polling-id>` — that is still an MFA pause, not a missing hash.
  
  For approval surfaces and recovery steps, see [troubleshooting.md](workflows/troubleshooting.md).
  
  ## Response Style
  
  - Route silently. Do not announce which reference you are loading.
  - Surface errors from commands verbatim. Do not mask or reword them.
  - If a command fails, check `mm <command> --help` and guide from there.
  

• skills/metamask-agent-wallet/scripts/amount_to_hex.py631 Bfe18b7b977a3upstream ↗

  #!/usr/bin/env python3
  """Convert a human-readable token amount to 0x-prefixed hex for EVM calldata.
  
  Usage:
      python3 amount_to_hex.py <amount> <decimals>
  
  Examples:
      python3 amount_to_hex.py 1.5 18       # 1.5 ETH  -> 0x14d1120d7b160000
      python3 amount_to_hex.py 100 6        # 100 USDC -> 0x5f5e100
      python3 amount_to_hex.py 0.001 8      # 0.001 WBTC -> 0x186a0
  """
  
  import sys
  from decimal import Decimal
  
  if len(sys.argv) != 3:
      print(f"Usage: {sys.argv[0]} <amount> <decimals>", file=sys.stderr)
      sys.exit(1)
  
  decimals = int(sys.argv[2])
  value = int(Decimal(sys.argv[1]) * 10 ** decimals)
  
  print(hex(value))
  

• skills/metamask-agent-wallet/scripts/x402_pay.py34 KB586408b1fcd2upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/references/auth.md10 KB16c1d9d64d6eupstream ↗

  # Authentication Commands
  
  Use these commands to initialize wallet mode, sign in, inspect authentication status, and clear local session state.
  
  ## `init` Command
  
  Initialize the project by selecting wallet mode and trading mode. Requires an authenticated session. Run `mm login` first.
  
  ### Syntax
  
  ```bash
  mm init [--wallet <mode>] [--mode <mode>] [--mnemonic <phrase>] [--password <password>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--wallet` | No | Wallet mode: `server-wallet` or `byok` |
  | `--mode` | No | Trading mode: `guard` or `beast` |
  | `--mnemonic` | No | BIP-39 mnemonic phrase for BYOK wallet. Never pass inline. Set `MM_MNEMONIC` env var instead. |
  | `--password` | No | Password to encrypt the BYOK mnemonic at rest. Never pass inline. Set `MM_PASSWORD` env var instead. If omitted in interactive mode, the CLI prompts. If omitted in non-interactive mode, mnemonic is stored unencrypted. |
  
  ### Example
  
  ```bash
  mm init
  mm init --wallet server-wallet --mode beast
  export MM_MNEMONIC="word1 word2 ..."
  mm init --wallet byok --mode guard
  
  export MM_MNEMONIC="word1 word2 ..."
  export MM_PASSWORD="mypassword"
  mm init --wallet byok --mode guard
  ```
  
  ### Note
  
  - In server-wallet mode, if the account already has a remote EVM wallet, `mm init` syncs it and loads the existing trading mode instead of prompting for a new trading mode or creating a wallet. Use `mm wallet policy get` to view the wallet policy.
  - In BYOK mode, `mm init` registers the wallet server-side and prompts for trading mode (`guard` or `beast`). If a trading mode is already set server-side, it is loaded without prompting. The `--mode` flag skips the prompt in non-interactive/scripted use. Server-side registration must succeed — if it fails, the CLI throws `WALLET_NOT_REGISTERED` and rolls back the wallet mode so subsequent commands are blocked by the init gate.
  
  ## `init show` Command
  
  Display the current initialization settings (wallet mode, trading mode). Use `mm wallet policy get` to view the wallet policy separately.
  
  ### Syntax
  
  ```bash
  mm init show
  ```
  
  ### Supported Flags
  
  This command does not support additional flags beyond output format options.
  
  ### Example
  
  ```bash
  mm init show
  ```
  
  ## `login` Command
  
  Sign in to the CLI. On a TTY, bare `mm login` shows a method picker (MetaMask Mobile QR or browser). QR is recommended but not auto-selected. `mm login browser` covers both Google and Email — the user picks interactively in the browser.
  
  ### Syntax
  
  ```bash
  mm login [qr | browser] [--token <token>] [--timeout <seconds>] [--otp-pair] [--no-wait]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--token` | No | Pre-minted CLI token in `cliToken:cliRefreshToken` format. Can also be set via the `MM_CLI_TOKEN` env var |
  | `--timeout` | No | Seconds to wait for QR or browser callback |
  | `--otp-pair` | No | Use the legacy MWP 6-digit pairing-code flow for browser login instead of the default paste-token flow. Only valid with `browser`. Cannot be combined with `--no-wait` or `--token` |
  | `--no-wait` | No | Print the sign-in URL and exit without waiting, for non-interactive or CI use. Not supported with QR login or `--otp-pair`. Complete later with `mm login --token` |
  
  ### Example
  
  ```bash
  mm login browser
  mm login browser --no-wait
  mm login browser --otp-pair
  mm login --token "cliToken:cliRefreshToken"
  ```
  
  ### Note
  
  - `mm login browser`, the default, opens the dashboard URL and prompts the user to paste a CLI token in `cliToken:cliRefreshToken` format. This is the recommended flow for agents.
  - `mm login browser --otp-pair` restores the legacy MWP 6-digit pairing-code flow.
  - If already authenticated, the CLI returns `ALREADY_AUTHENTICATED`. Run `mm logout` first, then log in again.
  - `mm login qr`, scan with MetaMask Mobile, is available on all environments, including production.
  - Pairing codes tolerate `-` and whitespace separators, so `608-225` is equivalent to `608225`.
  - Use `mm login browser --no-wait` for non-interactive/CI flows. The command prints a sign-in URL; the user completes login in the browser via Google or Email. Bare `mm login --no-wait` fails without a TTY because no method is selected.
  - `--no-wait` is not supported with QR login or `--otp-pair`. Complete authentication later with `mm login --token`.
  - After a successful login in server-wallet mode, the CLI automatically syncs existing wallets from the server. Run `mm wallet list` immediately — no need to re-run `mm init`. In BYOK mode, no sync occurs; run `mm init` to configure the wallet.
  
  ## `auth status` Command
  
  Show the current authentication status.
  
  ### Syntax
  
  ```bash
  mm auth status [--toon]
  ```
  
  ### Supported Flags
  
  This command does not support additional flags beyond output format options.
  
  ### Example
  
  ```bash
  mm auth status
  mm auth status --toon
  ```
  
  ## `logout` Command
  
  Sign out and clear auth credentials plus local init state, wallet selection, and stored BYOK mnemonic. Prompts for confirmation before signing out. If no active session exists, returns `reason: ALREADY_LOGGED_OUT` with a hint to run `mm login`, exit 0, not an error.
  
  ### Syntax
  
  ```bash
  mm logout [--yes]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--yes` | No | Skip the confirmation prompt, for non-interactive or scripted use |
  
  ### Example
  
  ```bash
  mm logout
  mm logout --yes
  ```
  
  ## `config get` Command
  
  Show persisted CLI configuration. Does not require authentication.
  
  ### Syntax
  
  ```bash
  mm config get [env|verbose|format|walletTimeoutSeconds|experimentalPlugins|experimentalAllowUnverifiedInstalls]
  ```
  
  ### Supported Keys
  
  | Key | Description |
  | --- | --- |
  | `env` | Target API environment: `prod`, `dev`, or `uat`. Defaults to `prod` when unset |
  | `verbose` | Whether verbose logging is persisted, `true` or `false` |
  | `format` | Default output format: `json`, `text`, or `toon` |
  | `walletTimeoutSeconds` | Default wallet job timeout in seconds, 1-600 |
  | `experimentalPlugins` | Enable the beta `mm plugins` system, `true` or `false`. Defaults to `false`. When false, plugin commands fail with `PLUGIN_BETA_DISABLED` |
  | `experimentalAllowUnverifiedInstalls` | Allow `file:`, git, and `mm plugins link` sources, `true` or `false`. Required in addition to `experimentalPlugins` for those sources |
  
  Omit the key to return all values.
  
  ### Example
  
  ```bash
  mm config get
  mm config get env
  ```
  
  ## `config set` Command
  
  Persist a CLI configuration value in `~/.metamask/config.json`. Does not require authentication.
  
  ### Syntax
  
  ```bash
  mm config set <env|verbose|format|walletTimeoutSeconds|experimentalPlugins|experimentalAllowUnverifiedInstalls> <value>
  ```
  
  ### Supported Keys
  
  | Key | Values |
  | --- | --- |
  | `env` | `prod`, `dev`, or `uat` |
  | `verbose` | `true` or `false` |
  | `format` | `json`, `text`, or `toon` |
  | `walletTimeoutSeconds` | Positive integer, 1-600 |
  | `experimentalPlugins` | `true` or `false` |
  | `experimentalAllowUnverifiedInstalls` | `true` or `false` |
  
  ### Overrides
  
  Persisted values can be overridden per invocation without changing `~/.metamask/config.json`:
  
  | Key | Override |
  | --- | --- |
  | `env` | `MM_ENV` environment variable |
  | `verbose` | `--verbose` / `-v` flag |
  | `format` | `--format`, `--json`, `--toon`, etc. |
  
  ### Example
  
  ```bash
  mm config set env prod
  mm config set env dev
  mm config set env uat
  mm config set format toon
  mm config set experimentalPlugins true
  ```
  
  ### Note
  
  - Switch environments at any time with `mm config set env <prod|dev|uat>`.
  - Non-prod sessions are stored in env-scoped files under `~/.metamask/`, such as `session.dev.json` and `session.uat.json`; prod uses `session.json`.
  - The plugin system is off by default. For plugin install and run, set `experimentalPlugins` to `true`. For local `file:` / git / `plugins link`, also set `experimentalAllowUnverifiedInstalls`.
  
  ## `reset` Command
  
  Clear the local CLI session entirely, including auth credentials, wallet state, mnemonic, swap quotes, and persisted config. Prompts for confirmation before resetting.
  
  ### Syntax
  
  ```bash
  mm reset [--yes]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--yes` | No | Skip the confirmation prompt, for non-interactive or scripted use |
  
  ### Example
  
  ```bash
  mm reset
  mm reset --yes
  ```
  
  ## `wallet password set` Command
  
  Set a password to encrypt the BYOK mnemonic at rest. Only available in BYOK mode when the mnemonic is currently unencrypted.
  
  ### Syntax
  
  ```bash
  mm wallet password set [--new <password>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--new` | No | New password. If omitted, the CLI prompts interactively. |
  
  ### Example
  
  ```bash
  mm wallet password set
  mm wallet password set --new "mypassword"
  ```
  
  ## `wallet password change` Command
  
  Change the BYOK mnemonic encryption password. Only available when the mnemonic is currently encrypted.
  
  ### Syntax
  
  ```bash
  mm wallet password change [--current <password>] [--new <password>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--current` | No | Current password. If omitted, the CLI prompts interactively. |
  | `--new` | No | New password. If omitted, the CLI prompts interactively. |
  
  ### Example
  
  ```bash
  mm wallet password change
  mm wallet password change --current "oldpassword" --new "newpassword"
  ```
  
  ## `wallet password remove` Command
  
  Remove the BYOK mnemonic encryption password, storing the mnemonic as plaintext. Only available when the mnemonic is currently encrypted.
  
  ### Syntax
  
  ```bash
  mm wallet password remove [--current <password>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--current` | No | Current password. If omitted, the CLI prompts interactively. |
  
  ### Example
  
  ```bash
  mm wallet password remove
  mm wallet password remove --current "mypassword"
  ```
  
  ## Wallet Modes
  
  | Mode | Behavior |
  | --- | --- |
  | `server-wallet` | Keys hosted by MetaMask infrastructure. Signing and transaction operations return async job handles with a `pollingId`. |
  | `byok` | Bring your own local mnemonic. Keys are held locally and signing is done on-device, but operations still go through a job-polling loop and return a `pollingId`. If the mnemonic is encrypted with a password, the CLI requires `MM_PASSWORD` to unlock before any operation that needs the private key. |
  

• skills/metamask-agent-wallet/references/chain.md561 B2792df7bec63upstream ↗

  # Chain Commands
  
  Use `chains` commands to discover supported blockchain networks.
  
  ## `chains list` Command
  
  List all supported EVM blockchain networks (EIP-155).
  
  ### Syntax
  
  ```bash
  mm chains list [--toon]
  ```
  
  ### Supported Flags
  
  This command does not support additional flags beyond output format options.
  
  ### Example
  
  ```bash
  mm chains list
  mm chains list --toon
  ```
  
  ## Supported Namespaces
  
  | Namespace | Notes |
  | --- | --- |
  | `eip155` | Major EVM chains, such as Ethereum, Polygon, Arbitrum, Optimism, BSC, Monad, HyperEVM, Sei, MegaETH, and Arc |
  

• skills/metamask-agent-wallet/references/decode.md1.2 KBed859ceb2e82upstream ↗

  # Decode Commands
  
  Use `decode` to turn raw EVM calldata into a human-readable intent before signing or sending a transaction. Requires authentication and a completed `init`.
  
  ## `decode` Command
  
  Decode hex-encoded EVM calldata into its function name, parameters, and a plain-language summary.
  
  ### Syntax
  
  ```bash
  mm decode --payload <0x-calldata> [--toon]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--payload` | Yes | Hex-encoded EVM calldata to decode, such as `0x095ea7b3...` |
  
  ### Output
  
  | Field | Description |
  | --- | --- |
  | `functionName` | Decoded function name, when the selector is recognized |
  | `params` | Array of decoded parameters, each with `name` and `value` |
  | `intent` | Plain-language summary of the call, such as `Call approve(spender: 0x..., amount: ...)` |
  
  ### Example
  
  ```bash
  mm decode --payload 0x095ea7b3000000000000000000000000... --toon
  ```
  
  ## Notes
  
  - Use this before `mm wallet send-transaction` whenever the calldata is unfamiliar or was not constructed by you, to confirm what the transaction actually does.
  - If the selector is not recognized, `intent` falls back to `Call unknown function`. Treat unrecognized calldata as higher risk and warn the user before proceeding.
  

• skills/metamask-agent-wallet/references/doctor.md2.8 KB0814e74f94f7upstream ↗

  # Doctor command
  
  Use `mm doctor` to inspect CLI version, AI skills / plugin install, environment, and session health. This command does not require authentication or initialization.
  
  ## `doctor` command
  
  ### Syntax
  
  ```bash
  mm doctor
  mm doctor --json
  mm doctor --toon
  ```
  
  ### Supported flags
  
  This command does not support additional flags beyond output format options.
  
  ### Output
  
  | Field | Type | Description |
  | --- | --- | --- |
  | `cli` | string | Installed CLI version (`@metamask/agent-wallet`) |
  | `env` | string | Current environment (`prod`, `dev`, or `uat`) |
  | `authenticated` | boolean | Whether the CLI session is valid (Hydra token valid or refreshed) |
  | `initialized` | boolean | Whether you have run `mm init` (wallet mode and trading mode are set for server wallets) |
  | `recommendedSkills` | object | Installed MetaMask AI skill status for `metamask-agent-wallet` and `metamask-agent-workflows` |
  | `compatible` | boolean or null | Whether the installed CLI version is compatible with the installed skills. `null` if no skills are detected |
  | `skillSource` | string or null | `plugin` (marketplace plugin), `skills-cli` (installed with the `skills` CLI), or `null` |
  | `agentHost` | string or null | Detected calling agent host (`claude-code`, `cursor`, `codex`, `antigravity`, `grok`, …) or `null` |
  | `installSource` | string or null | First-touch channel from `~/.metamask/attribution.json`, or `null` |
  | `hints` | string[] | Actionable guidance, for example missing skills, auth issues, init needed, or version mismatch |
  
  ### Skill detection
  
  `mm doctor` resolves skills in this order:
  
  1. `MM_PLUGIN_ROOT/skills/<name>/SKILL.md` (set by the plugin session-start hook)
  2. Claude / Cursor plugin caches under `~/.claude/plugins` and `~/.cursor/plugins`
  3. Global skills lock file (`~/.agents/.skill-lock.json` or `$XDG_STATE_HOME/skills/.skill-lock.json`), then project/global `.agents/skills`
  
  When the lock file exists but contains no MetaMask entries, it falls back to scanning the current project for installed `metamask-agent-wallet` / `metamask-agent-workflows` skills. It parses `SKILL.md` frontmatter for the skill `version` and `cliVersion` metadata, then checks the CLI `major.minor` against the skill `cliVersion` requirement.
  
  When skills come from the plugin, upgrade hints point at the marketplace and pin `npm install -g @metamask/agent-wallet@<cliVersion>` instead of the `skills` CLI.
  
  ### Example
  
  ```bash
  mm doctor
  mm doctor --json
  mm doctor --toon
  ```
  
  ### Notes
  
  - Use as the first step in troubleshooting to check if CLI, auth, init, and skills are healthy.
  - Run after a CLI upgrade to verify skill compatibility.
  - Use in CI or scripting to confirm environment and session state.
  - Do not run wallet write commands until `authenticated: true` and `initialized: true`. Follow `workflows/onboarding.md` / `workflows/login.md` when hints say so.
  

• skills/metamask-agent-wallet/references/earn.md6.7 KBaef1ac0d706aupstream ↗

  # Earn Commands
  
  Use the `earn` commands to browse DeFi yield vaults, view positions, supply tokens, and withdraw. Powered by LiFi's earn API.
  
  ## `earn markets` Command
  
  List available earn vaults with APY and TVL data. Requires authentication and a completed `init`.
  
  ### Syntax
  
  ```bash
  mm earn markets [--chain-id <chain-id>] [--token <symbol|address>] [--protocol <name>] [--min-tvl <usd>] [--sort apy|tvl] [--limit <n>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--chain-id` | No | EVM chain ID to filter results, such as 1 for Ethereum or 8453 for Base |
  | `--token` | No | Filter by token symbol or address, such as USDC |
  | `--protocol` | No | Filter by protocol name, such as aave, compound, or morpho |
  | `--min-tvl` | No | Minimum TVL in USD. Must be a positive number |
  | `--sort` | No | Sort order: `apy` or `tvl`. Defaults to `apy` |
  | `--limit` | No | Maximum number of vaults to return |
  
  ### Example
  
  ```bash
  mm earn markets
  mm earn markets --chain-id 8453
  mm earn markets --chain-id 1 --protocol aave --min-tvl 100000
  ```
  
  ### Output
  
  Each vault includes: address, chainId, name, protocol, underlying tokens, APY with base/reward/total breakdown, 7-day and 30-day APY, TVL in USD, and whether it supports deposits via `isTransactional` and withdrawals via `isRedeemable`.
  
  ## `earn positions` Command
  
  List current earn positions and deposited balances for a wallet. Requires authentication and a completed `init`.
  
  ### Syntax
  
  ```bash
  mm earn positions [--chain-id <chain-id>] [--address <address>] [--token <symbol|address>] [--protocol <name>] [--vault <address>] [--min-usd <n>] [--sort usd] [--limit <n>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--chain-id` | No | EVM chain ID to filter positions |
  | `--address` | No | Account address. Defaults to the currently selected wallet |
  | `--token` | No | Filter by token symbol or address |
  | `--protocol` | No | Filter by protocol name |
  | `--vault` | No | Filter by vault contract address |
  | `--min-usd` | No | Hide positions below this USD balance |
  | `--sort` | No | Sort order: `usd` for descending balance |
  | `--limit` | No | Maximum number of positions to return |
  
  ### Example
  
  ```bash
  mm earn positions
  mm earn positions --chain-id 8453
  mm earn positions --address 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18
  ```
  
  ### Output
  
  Each position includes: chainId, vault address, protocol name, asset with address/symbol/decimals/name, balance in USD, and balance in native token units.
  
  ## `earn supply` Command
  
  Supply tokens to an earn vault to earn yield. Requires authentication. Handles ERC-20 approval automatically. Supports cross-chain deposits.
  
  ### Syntax
  
  ```bash
  mm earn supply --token <symbol|address> --amount <amount> --chain-id <chain-id> [--vault <address>] [--protocol <name>] [--min-tvl <usd>] [--from-chain-id <chain-id>] [--from-token <symbol|address>] [--wait] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--token` | Yes, unless `--vault` | Underlying token symbol or contract address, such as USDC |
  | `--amount` | Yes | Human-readable amount to supply, such as 100. Must be a positive number |
  | `--chain-id` | Yes | Destination EVM chain ID where the vault lives |
  | `--vault` | No | Vault contract address. If omitted, auto-selects the best vault for the token |
  | `--protocol` | No | Restrict vault auto-selection to a specific protocol, such as aave or compound |
  | `--min-tvl` | No | Minimum TVL in USD for vault auto-selection |
  | `--from-chain-id` | No | Source chain ID for cross-chain deposits |
  | `--from-token` | No | Source token symbol or address for cross-chain deposits. Required when `--from-chain-id` differs from `--chain-id` |
  | `--wait` | No | Poll after deposit to confirm the position is reflected, up to ~45s. Without `--wait`, the CLI shows a hint to check positions shortly |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Validation Rules
  
  - Either `--token` or `--vault` must be provided.
  - When `--from-chain-id` differs from `--chain-id`, `--from-token` is required.
  
  ### Example
  
  ```bash
  mm earn supply --token USDC --amount 100 --chain-id 8453
  mm earn supply --token USDC --amount 100 --chain-id 8453 --protocol aave
  mm earn supply --vault 0xabc...def --amount 50 --chain-id 1
  mm earn supply --token USDC --amount 100 --chain-id 8453 --from-chain-id 1 --from-token USDC
  ```
  
  ## `earn withdraw` Command
  
  Withdraw tokens from an earn vault. Requires authentication. Handles LP token approval automatically.
  
  ### Syntax
  
  ```bash
  mm earn withdraw --token <symbol|address> --amount <amount> --chain-id <chain-id> [--vault <address>] [--protocol <name>] [--all] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--token` | Yes, unless `--vault` | Underlying token symbol or contract address |
  | `--amount` | Yes, unless `--all` | Human-readable amount to withdraw. Must be a positive number |
  | `--chain-id` | Yes | EVM chain ID of the vault |
  | `--vault` | No | Vault contract address. If omitted, auto-selects by token |
  | `--protocol` | No | Restrict vault auto-selection to a specific protocol |
  | `--all` | No | Withdraw the full balance. Mutually exclusive with `--amount` |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Validation Rules
  
  - Either `--token` or `--vault` must be provided.
  - Either `--amount` or `--all` must be provided.
  - The vault must be redeemable with `isRedeemable: true`. If not, the CLI returns `NOT_REDEEMABLE`.
  
  ### Example
  
  ```bash
  mm earn withdraw --token USDC --amount 50 --chain-id 8453
  mm earn withdraw --token USDC --all --chain-id 8453
  mm earn withdraw --vault 0xabc...def --all --chain-id 1
  ```
  
  ## Notes
  
  - Use `mm earn markets` to discover available vaults before supplying.
  - Use `mm earn positions` to check current deposits before withdrawing.
  - If `--vault` is omitted, the CLI auto-selects the best vault for the token on the specified chain. Use `--protocol` to narrow the selection.
  - Cross-chain supply is supported: set `--from-chain-id` and `--from-token` to deposit from a different chain. The CLI routes through LiFi and polls until the cross-chain transaction completes, with a timeout of 10 minutes.
  - The CLI handles ERC-20 approvals automatically for both supply and withdraw operations.
  

• skills/metamask-agent-wallet/references/errors.md21 KB3be0c7659950upstream ↗

  # Error Codes
  
  This reference lists error codes the CLI actually emits. SDK-only or remapped codes are noted where relevant. Workflows for diagnosing failures live in `../workflows/troubleshooting.md`.
  
  ## Auth Errors
  
  | Code | Meaning |
  | --- | --- |
  | `ALREADY_AUTHENTICATED` | Valid session already exists; run `mm logout` before logging in again |
  | `AUTH_FAILED` | Authentication failed. Includes missing refresh token cases |
  | `AUTH_ERROR` | Generic authentication error. Includes missing auth token cases |
  | `TOKEN_INVALID` | Invalid CLI token, token pair, or project ID |
  | `TOKEN_REFRESH_FAILED` | Failed to refresh token |
  | `PAIRING_TIMEOUT` | Login pairing timed out |
  | `PAIRING_EXPIRED` | Pairing session expired |
  | `INVALID_OTP` | Invalid one-time password |
  | `MWP_TIMEOUT` | Mobile Wallet Protocol timeout |
  | `MWP_CANCELLED` | Mobile Wallet Protocol cancelled due to pairing abort |
  | `LOGOUT_FAILED` | Logout operation failed. Includes token revoke failures |
  | `ALREADY_LOGGED_OUT` | No active session to sign out of. Run `mm login` to authenticate |
  
  ## Validation Errors
  
  | Code | Meaning |
  | --- | --- |
  | `MISSING_FLAG` | Required flag is missing in headless mode |
  | `MISSING_INPUT` | Required input is missing |
  | `MISSING_CHAIN` | Chain value is missing |
  | `MISSING_CHAIN_ID` | Chain ID is missing |
  | `INVALID_CHAIN` | Chain value is invalid |
  | `MISSING_TO` | Recipient address is missing |
  | `INVALID_TO` | Recipient address is invalid |
  | `INVALID_DATA` | Transaction data is invalid. Also returned by `mm price history` when the Price API responds with an empty or malformed body — retry, or verify the asset is priced with `mm price spot` |
  | `INVALID_INPUT` | Invalid user input |
  | `UNKNOWN_FLAG` | Unrecognized CLI flag; the error lists valid flags for the command |
  | `MISSING_ARG` | Required positional argument is missing |
  | `UNEXPECTED_ARG` | Unexpected positional argument provided |
  | `INVALID_QUANTITY` | EVM quantity is invalid |
  | `INVALID_LIMIT` | Invalid limit value |
  | `INVALID_INTERVAL` | Invalid time interval |
  | `INVALID_TIMESTAMP` | Invalid timestamp |
  | `INVALID_ASSET_ID` | Invalid CAIP-19 asset id. On `mm price spot`, pass a full id such as `eip155:1/slip44:60` or a CAIP-2 chain id such as `eip155:1` for the native asset. On `mm price history`, `--asset-type` must be `<namespace>:<reference>`. `mm token assets` rejects bare chain ids |
  | `MISSING_ASSET_IDS` | Missing asset IDs |
  | `MISSING_ASSET_TYPE` | Missing asset type |
  | `MISSING_QUERY` | Missing search query |
  | `MISSING_WALLET_REF` | Missing wallet reference |
  | `MISSING_TRANSACTION_PAYLOAD` | Transaction payload is missing |
  | `INVALID_TRANSACTION_PAYLOAD` | Transaction payload is invalid |
  | `MISSING_TYPED_DATA` | EIP-712 typed data payload is missing |
  | `INVALID_TYPED_DATA` | EIP-712 typed data payload is invalid |
  | `CHAIN_ID_MISMATCH` | Typed-data domain chain ID differs from `--chain-id` |
  | `UNKNOWN_CHAIN` | Unrecognized chain ID |
  | `UNSUPPORTED_CHAIN` | The command is not supported on this chain. Run `mm chains list` to see supported chains and their features |
  | `INVALID_GAS_TOKEN` | Invalid gas token symbol or address |
  | `TOKEN_NO_ADDRESS` | Token symbol could not be resolved to a contract address |
  | `INVALID_EVM_ADDRESS` | Invalid EVM address, such as a malformed transfer recipient |
  | `INVALID_AMOUNT` | Non-positive or malformed amount value |
  | `INVALID_MNEMONIC` | BYOK mnemonic is invalid |
  | `INVALID_VENUE` | Invalid perpetual venue value |
  | `INVALID_NETWORK` | Invalid network value. Must be `mainnet` or `testnet` |
  | `INVALID_TIF` | Invalid `--tif` on `mm perps open` or `mm perps quote`. Must be `gtc`, `ioc`, or `alo`, and `gtc` or `alo` need `--type limit` with `--limit-px` |
  | `INVALID_WINDOW` | Invalid `--window` on `mm perps funding-rates`. Must be `1h`, `8h`, or `1d` |
  | `INVALID_ASSET` | Invalid asset value |
  | `INVALID_SIDE` | Invalid side value. Must be `long`/`short` or `buy`/`sell` |
  | `INVALID_ORDER_TYPE` | Invalid order type value |
  | `INVALID_PREDICT_MODE` | Invalid Predict mode value. Must be `mainnet` or `testnet` |
  | `INVALID_RECURRENCE` | Invalid recurrence value. Must be `annual`, `daily`, `weekly`, or `monthly` |
  | `INVALID_ENV` | Invalid environment value. Must be `prod`, `dev`, or `uat` |
  | `INVALID_SORT_BY` | Invalid sort-by field value |
  | `INVALID_SORT_DIRECTION` | Invalid sort direction value |
  | `INVALID_HISTORY_TYPE` | Invalid history type value. Must be `closed`, `trade`, or `redeem` |
  | `INVALID_POLICY_YAML` | Policy YAML passed to `mm wallet policy set` is not a full policy document. Start from `mm wallet policy get` or `mm wallet policy template`, edit that YAML, and pass the complete object with a top-level `schema_version` |
  
  ## Wallet Errors
  
  | Code | Meaning |
  | --- | --- |
  | `MISSING_MNEMONIC` | BYOK wallet mode is missing a mnemonic |
  | `MNEMONIC_LOCKED` | Mnemonic unlock failed after maximum attempts |
  | `WRONG_PASSWORD` | Current password is incorrect |
  | `ALREADY_ENCRYPTED` | Mnemonic is already password-encrypted. Use `wallet password change` instead |
  | `NOT_ENCRYPTED` | Mnemonic is not encrypted. Use `wallet password set` instead |
  | `PASSWORD_MISMATCH` | Password confirmation does not match |
  | `EMPTY_PASSWORD` | Empty password provided |
  | `WALLET_NOT_FOUND` | Wallet not found |
  | `WALLET_LIMIT_EXCEEDED` | The project already has the maximum of 100 wallets, so `mm wallet create` cannot add another. Run `mm wallet list` to review existing wallets, and select one with `mm wallet select` instead of creating a new one |
  | `WALLET_ERROR` | Wallet provider or wallet operation error. Includes on-chain reverts and network failures from wallet paths |
  | `WALLET_METADATA` | Wallet metadata error |
  | `WALLET_NOT_REGISTERED` | Server-side BYOK wallet registration failed. Re-run `mm init --wallet byok` |
  | `WRONG_NAMESPACE` | Wrong namespace for wallet |
  | `UNSUPPORTED_NAMESPACE` | Unsupported wallet namespace |
  | `NO_AUTH_TOKEN` | Missing authentication token for wallet operations |
  | `NO_PROJECT_ID` | Project ID not configured for wallet |
  | `MISSING_PROJECT_ID` | Project ID is not configured |
  | `INVALID_TRADING_MODE` | Invalid trading mode; use `guard` or `beast` |
  | `ALREADY_SET_TRADING_MODE` | Trading mode is already set to the requested value |
  | `WRONG_WALLET_MODE` | Operation not supported in the current wallet mode |
  | `WALLET_MODE_APPROVAL_IN_PROGRESS` | A wallet mode change approval is already in progress |
  | `TRADING_MODE_APPROVAL_REJECTED` | Trading mode change was rejected via MFA |
  | `TRADING_MODE_APPROVAL_EXPIRED` | Trading mode change MFA approval expired |
  | `WALLET_POLICY_APPROVAL_IN_PROGRESS` | A wallet policy change approval is already in progress |
  | `WALLET_POLICY_APPROVAL_REJECTED` | Wallet policy change was rejected via MFA |
  | `WALLET_POLICY_APPROVAL_EXPIRED` | Wallet policy change MFA approval expired |
  | `INSUFFICIENT_FUNDS` | Insufficient native balance or token balance for the operation |
  
  ## Command Errors
  
  | Code | Meaning |
  | --- | --- |
  | `ABORTED` | Operation aborted by user |
  | `JOB_TIMEOUT` | Wallet job poll timed out. Approve on your paired device if prompted, or check `mm wallet requests list` before retrying |
  | `REQUEST_NOT_FOUND` | Wallet job/request not found on remote |
  | `TX_DENIED` | Transaction was denied via MFA |
  | `TX_EXPIRED` | Transaction MFA approval expired |
  | `TX_FAILED` | Transaction failed after submission |
  | `TX_REVERTED` | Transaction reverted on-chain via RPC revert; check the `failure_reason` field for details |
  | `RELAY_TIMEOUT` | Gasless relay poll timed out. Check `mm wallet requests watch <polling-id>` before retrying; the job may still complete |
  | `RELAY_FAILED` | Gasless relay failed, typically because the wallet cannot cover the amount plus the relay fee. Retry with a lower `--amount` or check balances with `mm wallet balance` |
  | `RELAY_ABORTED` | Relay operation aborted |
  | `NOT_INITIALIZED` | Project not initialized. Run `mm init` |
  | `NO_MNEMONIC` | Mnemonic not stored |
  | `NO_TTY` | No TTY available for interactive prompts |
  | `MISSING_ID` | Missing ID parameter |
  | `MISSING_QUOTE_ID` | Missing quote ID |
  | `MISSING_SWAP_PARAMS` | Missing swap parameters |
  | `TX_NOT_FOUND` | Transaction not found for the given hash |
  | `INVALID_TX_HASH` | Invalid transaction hash format |
  | `COMMAND_NOT_FOUND` | Unknown command. Run `mm --help` to list valid commands |
  | `NON_INTERACTIVE` | Operation requires interactive mode but no TTY is available |
  | `COMING_SOON` | Feature not yet available in this environment |
  | `INVALID_CONFIG_KEY` | Unknown config key passed to `mm config get` or `mm config set` |
  | `INVALID_CONFIG_VALUE` | Invalid value for a config key, such as env not in `prod`, `dev`, or `uat` |
  
  ## Token & Pulse Errors
  
  | Code | Meaning |
  | --- | --- |
  | `TOKEN_UNSUPPORTED_CHAIN` | A chain passed to `mm token list ...`, `mm token assets`, or `mm token rwas` is not supported by the Token API. Testnets are never supported. Run `mm token networks` to see supported chains |
  | `TOKEN_API_ERROR` | The Token API returned an unexpected error. Retry, or re-run with `--verbose` for detail |
  | `PULSE_NOT_FOUND` | No Digest summary was found for the requested asset or highlight. Try another asset identifier |
  | `PULSE_AMBIGUOUS` | The `mm pulse asset` identifier matched multiple assets. Retry with `--caip-asset-type <caip19>` or `--hl-perps-market <market>` |
  
  ## Swap & Bridge Errors
  
  | Code | Meaning |
  | --- | --- |
  | `NO_QUOTES` | No swap or bridge quotes available. When returned as a soft unavailable outcome with exit 0, adjust amount, slippage, or token and retry |
  | `QUOTE_RETRY` | Transient bridge hiccup — re-run the exact same quote to get routes |
  | `BRIDGE_API_ERROR` | Bridge API error |
  | `TOKEN_NOT_FOUND` | Token not found |
  | `TOKEN_NOT_SUPPORTED` | Token not supported for this swap route |
  | `INVALID_SWAP_PARAMS` | Invalid swap parameters. Includes `--all-quotes` and `--yes` used together |
  | `NATIVE_ASSET_UNSUPPORTED` | Native asset not supported for this swap route |
  | `INSUFFICIENT_GAS` | Insufficient native gas to cover the swap; add native gas or use `--strategy output` / `--all-quotes` to pick a gasless quote |
  | `REFUEL_UNSUPPORTED_ROUTE` | Refuel is not supported on this route, either same-chain or native destination token. Drop `--refuel` and re-run |
  | `AMOUNT_TOO_HIGH` | Amount too high for available liquidity |
  | `AMOUNT_TOO_LOW` | Amount below provider minimum |
  | `SLIPPAGE_TOO_HIGH` | Slippage too high for this route |
  | `SLIPPAGE_TOO_LOW` | Slippage too low for this route |
  | `RWA_GEO_RESTRICTED` | RWA asset not available in your region |
  | `RWA_NATIVE_TOKEN_UNSUPPORTED` | RWA cannot be swapped against native asset |
  | `RWA_MARKET_UNAVAILABLE` | RWA market temporarily unavailable |
  | `QUOTE_PERSIST_FAILED` | Failed to persist the quote to `~/.metamask/swap-quotes/`. The CLI already retries a transient directory-creation failure once, so this means the path is genuinely unwritable. Create it manually with `mkdir -p "$HOME/.metamask/swap-quotes" && chmod u=rwx,go= "$HOME/.metamask/swap-quotes"`, then re-run `mm swap quote` |
  | `QUOTE_NOT_FOUND` | Quote not found |
  | `EXECUTE_FAILED` | Swap execution failed. When the job is paused on MFA and no hash is available yet, the message names the wait and `mm wallet requests watch` — treat as an MFA pause, not a missing hash |
  | `NO_TRADE_DATA` | No trade data available |
  | `STATUS_UNAVAILABLE` | Swap status unavailable |
  | `GASLESS_UNSUPPORTED` | Gasless relay is not supported on this chain |
  | `GASLESS_NOT_CONFIGURED` | Gasless relay is not configured for this operation |
  | `INSUFFICIENT_FUNDS` | Insufficient source token balance to execute swap. Check `mm wallet balance`, fund the wallet, or lower `--amount` and re-quote |
  | `SWAP_ERROR` | Generic swap error |
  | `FEES_LOOKUP_FAILED` | Unexpected wallet-fees lookup failure |
  
  ## Perps Errors
  
  | Code | Meaning |
  | --- | --- |
  | `UNSUPPORTED_VENUE` | Unsupported perpetual venue |
  | `UNSUPPORTED_NETWORK` | Unsupported network for perps |
  | `UNSUPPORTED_ROUTE` | Unsupported deposit or withdraw route. Also returned when vault equity is still locked on `mm perps vault withdraw`, and when `--vault` is combined with a deposit, withdrawal, or spot to perp transfer |
  | `UNSUPPORTED_ASSET` | Unsupported asset |
  | `UNSUPPORTED_SOURCE_CHAIN` | Unsupported source chain for perps deposit |
  | `INVALID_SYMBOL` | Unknown perpetual market symbol |
  | `INVALID_AMOUNT` | Invalid amount. Uses the shared amount parser — see the Validation Errors entry for accepted formats and the `reason`/hint fields |
  | `INVALID_SIZE` | Invalid position size |
  | `INVALID_LEVERAGE` | Invalid leverage value |
  | `INVALID_PRICE` | Invalid price |
  | `INVALID_SLIPPAGE` | Invalid slippage value |
  | `INVALID_ADDRESS` | Invalid address |
  | `INSUFFICIENT_BALANCE` | Insufficient balance |
  | `POSITION_NOT_FOUND` | Position not found |
  | `QUOTE_FAILED` | Quote generation failed |
  | `ORDER_REJECTED` | Order rejected |
  | `REDUCE_ONLY_REJECTED` | A `--reduce-only` order on `mm perps open` would increase or flip the position. Check `mm perps positions`, or drop `--reduce-only` if the user wants to add to the position |
  | `ALREADY_SET_ACCOUNT_MODE` | `mm perps account mode set` target matches the current mode. Nothing changed |
  | `CANCEL_FAILED` | Order cancellation failed |
  | `SIGNING_FAILED` | Signing operation failed |
  | `WITHDRAW_FAILED` | Withdrawal failed |
  | `DEPOSIT_FAILED` | Deposit failed |
  | `RATE_LIMITED` | Rate-limited by the venue, such as Hyperliquid HTTP 429. Wait and retry |
  | `HYPERLIQUID_ERROR` | Hyperliquid protocol error |
  | `PERPS_ERROR` | Generic perpetuals error |
  
  ## Predict Errors
  
  | Code | Meaning |
  | --- | --- |
  | `PREDICT_SETUP_REQUIRED` | Predict setup required before operation. Run `mm predict setup` for this owner, then retry |
  | `PREDICT_AUTH_REQUIRED` | Predict authentication required. Run `mm predict auth`, then retry |
  | `PREDICT_AUTH_INVALID` | Predict credentials invalid or incomplete. Run `mm predict auth --refresh`, then retry |
  | `PREDICT_RELAYER_CONFIG_REQUIRED` | Relayer configuration required. Configure the Predict relayer URL and retry |
  | `PREDICT_INVALID_DEPOSIT_AMOUNT` | Invalid deposit amount. Pass a positive pUSD amount with up to 6 decimal places |
  | `PREDICT_WITHDRAW_ZERO` | Withdraw amount must be greater than zero. Pass a `--amount` greater than zero |
  | `PREDICT_WITHDRAW_INSUFFICIENT_BALANCE` | Withdraw amount exceeds deposit wallet pUSD balance. Lower `--amount` or check `mm predict balance` |
  | `PREDICT_FUNDING_CHAIN_UNSUPPORTED` | Funding chain not supported. Deposit funding is only configured for Polygon, chain ID 137 |
  | `PREDICT_INSUFFICIENT_BALANCE` | Insufficient Predict balance. Lower `--size`, or deposit more collateral with `mm predict deposit`; check `mm predict balance` |
  | `PREDICT_INSUFFICIENT_ALLOWANCE` | Insufficient Predict allowance. Run `mm predict approve`, then retry the order |
  | `PREDICT_INSUFFICIENT_FUNDING_BALANCE` | Insufficient funding balance for Predict deposit. Fund the deposit wallet with USDC.e, or lower the deposit amount |
  | `PREDICT_CANCEL_TARGET_REQUIRED` | Cancel target not specified. Pass `orderId`, `orderIds`, market/assetId, or `--all` |
  | `PREDICT_ORDER_SIZE_TOO_SMALL` | Order size is below the exchange minimum. Raise `--size` to at least the minimum stated in the error; inspect liquidity with `mm predict book` |
  | `PREDICT_ORDER_NOT_FILLED` | Order could not be fully filled. Adjust `--size`/`--price`, check liquidity with `mm predict book`, or use GTC instead of FOK |
  | `PREDICT_REDEEM_NONE` | No redeemable positions. Check `mm predict redeem list` |
  | `PREDICT_REDEEM_NOT_FOUND` | Redeem target not found. Check the condition/token ID against `mm predict redeem list` |
  | `PREDICT_REDEEM_MISSING_TARGET` | Missing redeem target. Pass a condition or token ID |
  | `PREDICT_METHOD_UNAVAILABLE` | Predict method not available |
  | `PREDICT_DEPOSIT_FAILED` | Predict deposit failed |
  | `PREDICT_ERROR` | Generic Predict error. Re-check inputs and mode via `mm predict mode`; run `mm predict status` to verify back-end reachability |
  | `PREDICT_UNAVAILABLE_FOR_LEGAL_REASONS` | Polymarket returned HTTP 451 (unavailable for legal reasons). Distinct from `PREDICT_GEOBLOCKED`, which comes from the dedicated geoblock API. Check `mm predict geoblock` |
  | `PREDICT_INSUFFICIENT_GAS` | Insufficient native POL for gas on Polygon. Top up wallet with POL, check balances with `mm wallet balance`, then retry |
  | `PREDICT_GEOBLOCKED` | Polymarket is not available in your region; Predict features cannot be used from this location. Emitted by `mm predict setup` as a region guard and surfaced by `mm predict geoblock` |
  | `UNSUPPORTED_PREDICT_CHAIN` | Predict chain not supported |
  | `PREDICT_HISTORY_CONDITION_REQUIRED` | Condition ID is required for `predict history get` |
  | `PREDICT_HISTORY_INVALID_SORT_BY` | Invalid sort-by key for the history mode. Closed: `realizedpnl`, `title`, `price`, `avgprice`, `timestamp`. Trade/redeem: `timestamp`, `tokens`, `cash` |
  | `POLYMARKET_FUNDING_CHAIN_UNSUPPORTED` | Deposit funding is only configured for Polygon, chain ID 137. Use the supported chain or fund Amoy manually for testnet |
  
  ## Earn Errors
  
  | Code | Meaning |
  | --- | --- |
  | `VAULT_NOT_FOUND` | No matching vault found for the token/chain/protocol |
  | `NOT_REDEEMABLE` | Vault does not support withdrawals |
  | `EARN_API_ERROR` | LiFi API error or rate limit |
  | `QUOTE_FAILED` | LiFi returned no executable transaction |
  | `EXECUTE_FAILED` | Transaction reverted, no hash returned, or cross-chain timeout. When the job is paused on MFA, the message names the wait and `mm wallet requests watch` — treat as an MFA pause, not a missing hash |
  | `NO_POSITION` | No matching earn position found for the wallet |
  | `POSITION_NOT_FOUND` | No matching earn position found for the specified vault/token |
  | `AMBIGUOUS_VAULT` | Multiple vaults match the token/chain/protocol. Narrow with `--vault` or `--protocol` |
  | `INSUFFICIENT_LP_BALANCE` | Insufficient LP token balance for the requested withdrawal amount |
  | `EARN_ERROR` | Generic earn error |
  
  ## Transaction History Errors
  
  | Code | Meaning |
  | --- | --- |
  | `NO_HISTORY_WALLETS` | No EVM wallets found in roster for transaction history |
  
  ## Startup Errors
  
  | Code | Meaning |
  | --- | --- |
  | `UNSUPPORTED_NODE` | The active Node.js runtime is below the minimum supported version, 22.18. Emitted before the CLI loads, on stderr as plain text or as a JSON envelope when `--json` is passed, and exits 1. Upgrade Node.js from https://nodejs.org/ or with a version manager such as nvm, fnm, or volta |
  
  ## Plugin Errors
  
  See [plugins.md](plugins.md) for the install flow and the gates behind these codes.
  
  | Code | Meaning |
  | --- | --- |
  | `PLUGIN_BETA_DISABLED` | The plugin system is beta and off. Ask the user before running `mm config set experimentalPlugins true`. Emitted both when running a plugin command and when installing |
  | `PLUGIN_UNVERIFIED_SOURCE` | The CLI refused a `file:` spec, a git source, or a bare path. Install from npm. For a plugin the user is building, set `experimentalAllowUnverifiedInstalls` to `true` |
  | `PLUGIN_METADATA_UNAVAILABLE` | `npm view <pkg> --json` could not be resolved. Installs fail closed, so nothing was installed. Check the package name and connectivity, then retry |
  | `PLUGIN_NOT_FOUND` | The package spec did not resolve to a name and version |
  | `PLUGIN_MANIFEST_INVALID` | `package.json#mm` is missing or does not match the manifest schema |
  | `PLUGIN_CLI_VERSION` | The plugin's `minCliVersion` is not satisfied by the installed CLI. Upgrade the CLI or install a compatible plugin version |
  | `PLUGIN_ID_COLLISION` | A plugin command id collides with a built-in `mm` command |
  | `PLUGIN_HOOKS_FORBIDDEN` | The package declares `oclif.hooks` or `oclif.plugins`, which run outside the plugin sandbox. Plugins may only contribute commands |
  | `PLUGIN_MANIFEST_FILE_MISSING` | The package shipped no prebuilt `oclif.manifest.json`. It was not approved and has been removed again |
  | `PLUGIN_INVALID_BASE` | A plugin command class does not extend `PluginCommand` |
  | `PLUGIN_SEALED_OVERRIDE` | A plugin command overrides a sealed lifecycle member. Plugin commands may implement only `execute` plus the documented hooks |
  | `PERMISSION_DENIED` on install | The user declined consent, or a non-TTY install was attempted without `--accept-permissions`. A run that passes `--json` needs that flag as well |
  | `PERMISSION_DENIED` on a plugin command | The capability was not approved, the command id is missing from `approvedCommandIds`, or the approval no longer matches the installed version and manifest hash. Run `mm plugins install <pkg>` so the user can approve the current manifest. This code is also raised when a plugin reaches for the host only session or mnemonic store |
  
  ## Network & Filesystem Errors
  
  | Code | Meaning |
  | --- | --- |
  | `NETWORK_UNREACHABLE` | Network unreachable |
  | `NETWORK_TIMEOUT` | Network request timed out |
  | `RESET_FAILED` | Failed to reset CLI session |
  | `MNEMONIC_STORE_FAILED` | Failed to store mnemonic to disk |
  | `FILESYSTEM_ERROR` | Generic filesystem error |
  

• skills/metamask-agent-wallet/references/market-data.md11 KBdd799c04542cupstream ↗

  # Market Data Commands
  
  Use `price`, `token`, and `pulse` commands for read-only token metadata, token discovery, tokenized real-world assets, price data, and AI-generated market summaries.
  
  The token discovery commands `token list popular|trending|top-gainer|search`, `token assets`, and `token rwas` check each requested chain against `mm token networks` before querying. A chain outside that list, including every testnet, returns `TOKEN_UNSUPPORTED_CHAIN`.
  
  ## `price spot` Command
  
  Fetch spot prices for one or more CAIP-19 assets.
  
  ### Syntax
  
  ```bash
  mm price spot --asset-ids <asset-ids> [--vs <currency>] [--market-data]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--asset-ids` | Yes | Comma-separated CAIP-19 asset IDs. A bare CAIP-2 chain id such as `eip155:1` auto-completes to that chain's native asset (`eip155:1/slip44:60`). Malformed ids return `INVALID_ASSET_ID` |
  | `--vs` | No | Quote currency. Defaults to `usd` |
  | `--market-data` | No | Include market cap, supply, and change percent |
  
  ### Example
  
  ```bash
  mm price spot --asset-ids "eip155:1/slip44:60,eip155:137/slip44:966"
  mm price spot --asset-ids eip155:1
  mm price spot --asset-ids "eip155:1/slip44:60" --vs eur
  mm price spot --asset-ids "eip155:1/slip44:60" --market-data
  ```
  
  ## `price history` Command
  
  Fetch historical prices for an asset.
  
  ### Syntax
  
  ```bash
  mm price history --chain-id <caip2-chain-id> [--asset-type <asset-type>] [--time-period <period>] [--interval <interval>] [--from <unix>] [--to <unix>] [--vs <currency>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--chain-id` | Yes | CAIP-2 chain ID, such as `eip155:1`. Run `mm price networks` to see supported chains |
  | `--asset-type` | No | CAIP-19 asset type, such as `slip44:60` for ETH or `erc20:0x...` for ERC-20 tokens. Defaults to the chain's native asset. Invalid types return `INVALID_ASSET_ID` |
  | `--time-period` | No | Time period, such as `1d`, `7d`, `30d`, `2M`, `1y`, or `3y` |
  | `--interval` | No | Sampling interval: `5m`, `15m`, `30m`, `hourly`, or `daily` |
  | `--from` | No | Start time as a Unix timestamp in seconds. Use with `--to` instead of `--time-period` for custom ranges |
  | `--to` | No | End time as a Unix timestamp in seconds. Use with `--from` instead of `--time-period` for custom ranges |
  | `--vs` | No | Quote currency code. Defaults to `usd`. Run `mm price currencies` to see options |
  
  ### Example
  
  ```bash
  mm price history --chain-id eip155:1 --time-period 7d --interval daily
  mm price history --chain-id eip155:1 --asset-type slip44:60 --time-period 7d --interval daily
  ```
  
  ## `price currencies` Command
  
  List supported quote currencies.
  
  ### Syntax
  
  ```bash
  mm price currencies
  ```
  
  ### Example
  
  ```bash
  mm price currencies
  ```
  
  ## `price networks` Command
  
  List CAIP-2 networks supported by the price API.
  
  ### Syntax
  
  ```bash
  mm price networks
  ```
  
  ### Example
  
  ```bash
  mm price networks
  ```
  
  ## `token list` Commands
  
  List popular, trending, or top-gainer tokens.
  
  ### Syntax
  
  ```bash
  mm token list popular [--chain-id <chain>]
  mm token list trending [--chain-id <chain>]
  mm token list top-gainer [--chain-id <chain>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--chain-id` | No | Chain id, CAIP-2 id, or configured chain key. Defaults to the active wallet chain, or `eip155:1` if none is selected |
  
  ### Example
  
  ```bash
  mm token list popular --chain-id 1
  mm token list trending --chain-id 1
  mm token list top-gainer --chain-id 1
  ```
  
  ## `token list search` Command
  
  Search tokens by query.
  
  ### Syntax
  
  ```bash
  mm token list search <query> [--chain-ids <chains>] [--limit <n>] [--after <cursor>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `<query>` | Yes | Search query by symbol or name, such as USDC or Wrapped Ether. Positional argument; `--query` is also accepted |
  | `--chain-ids` | No | Comma-separated chain IDs, CAIP-2 IDs, or configured chain keys. Defaults to the active wallet chain, or `eip155:1` if none is selected |
  | `--limit` | No | Maximum results. Defaults to 10, range 1-500 |
  | `--after` | No | Pagination cursor |
  
  ### Example
  
  ```bash
  mm token list search USDC --chain-ids 1,137 --limit 25
  mm token list search "Wrapped Ether" --chain-ids eip155:8453
  ```
  
  ### Notes
  
  - Quote multi-word queries so they arrive as a single positional argument.
  - With no query, the command returns `MISSING_QUERY`; it never prompts for one.
  
  ## `token networks` Command
  
  List networks supported by token APIs.
  
  ### Syntax
  
  ```bash
  mm token networks
  ```
  
  ### Example
  
  ```bash
  mm token networks
  ```
  
  ## `token assets` Command
  
  Fetch asset metadata for one or more CAIP-19 assets.
  
  ### Syntax
  
  ```bash
  mm token assets --asset-ids <asset-ids> [--include-market-data] [--include-token-security-data] [--include-labels] [--include-aggregators] [--include-coingecko-id] [--include-occurrences] [--include-rwa-data]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--asset-ids` | Yes | Comma-separated CAIP-19 asset IDs, such as `eip155:1/erc20:0xa0b8...`. Run `mm token networks` to see supported chains. Bare CAIP-2 chain ids are rejected with `INVALID_ASSET_ID`; pass a full asset id |
  | `--include-market-data` | No | Include market cap, volume, and price data |
  | `--include-token-security-data` | No | Include token security signals such as scam risk and honeypot detection |
  | `--include-labels` | No | Include token labels and categories |
  | `--include-aggregators` | No | Include aggregator sources that list this token |
  | `--include-coingecko-id` | No | Include the CoinGecko identifier for cross-referencing |
  | `--include-occurrences` | No | Include occurrence count across chains |
  | `--include-rwa-data` | No | Include real-world asset data |
  
  ### Example
  
  ```bash
  mm token assets --asset-ids "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48,eip155:137/slip44:966"
  mm token assets --asset-ids "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" --include-market-data --include-token-security-data --include-labels
  mm token assets --asset-ids "eip155:1/slip44:60" --include-aggregators --include-coingecko-id --include-rwa-data
  ```
  
  ## `token rwas` Command
  
  List tokenized real-world assets, or RWAs, such as stocks, ETFs, and closed-end funds.
  
  ### Syntax
  
  ```bash
  mm token rwas [--chain-ids <chains>] [--active <true|false>] [--custodian <custodian>] [--type <type>] [--industry <industry>] [--sort-by <sort>] [--limit <n>] [--after <cursor>] [--include-token-security-data]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--chain-ids` | No | Comma-separated chain IDs, CAIP-2 IDs, or configured chain keys, such as `1,137`. Omit to list every chain. Run `mm token networks` to see supported chains |
  | `--active` | No | Filter by active status: `true` or `false` |
  | `--custodian` | No | Filter by custodian: `ondo` or `robinhood` |
  | `--type` | No | Filter by underlying asset type: `stock`, `etf`, `cef`, or `unspecified` |
  | `--industry` | No | Filter by industry: `industrials`, `technology`, `healthcare`, `consumer discretionary`, `financials`, `materials`, `utilities`, `energy`, `real estate`, `infrastructure`, `unspecified`, or `unknown`. Quote multi-word values |
  | `--sort-by` | No | Sort order: `price_change_asc`, `price_change_desc`, `volume_asc`, `volume_desc`, `market_cap_asc`, or `market_cap_desc` |
  | `--limit` | No | Maximum results. Must be a positive integer |
  | `--after` | No | Pagination cursor from the `nextCursor` of a previous response |
  | `--include-token-security-data` | No | Include token security signals |
  
  `--custodian`, `--type`, `--industry`, and `--sort-by` are case-insensitive.
  
  ### Example
  
  ```bash
  mm token rwas --chain-ids 1 --type stock --sort-by market_cap_desc --limit 20
  mm token rwas --custodian ondo --type etf
  mm token rwas --industry technology --active true
  ```
  
  ### Notes
  
  - Each item includes `symbol`, and when available a CAIP-19 `assetId`, `address`, `chainId`, `name`, `decimals`, `active`, `custodian`, `type`, `industry`, `price`, `marketCap`, and `volume24hUsd`.
  - When `hasNextPage` is `true`, pass `nextCursor` as `--after` to fetch the next page.
  - Use the returned `assetId` with `mm price spot` or `mm token assets`.
  
  ## `pulse` Command
  
  Show the featured AI-generated market highlight from the Digest API.
  
  ### Syntax
  
  ```bash
  mm pulse [--full]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--full` | No | Include full trend details, sources, articles, and related assets. Without it, the output is a brief `headline`, `summary`, and `trends` list |
  
  ### Example
  
  ```bash
  mm pulse
  mm pulse --full
  ```
  
  ## `pulse asset` Command
  
  Show an AI-generated summary for a single asset.
  
  ### Syntax
  
  ```bash
  mm pulse asset <asset> [--full]
  mm pulse asset --caip-asset-type <caip19> [--full]
  mm pulse asset --hl-perps-market <market> [--full]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `<asset>` | One of three | Asset symbol, name, or CAIP-19 id, matched exactly, such as `ETH`. Positional argument; `--asset` is also accepted |
  | `--caip-asset-type` | One of three | CAIP-19 asset type, such as `eip155:1/slip44:60` |
  | `--hl-perps-market` | One of three | Hyperliquid perpetuals market name, such as `BTC` |
  | `--full` | No | Include full trend details, sources, articles, and related assets. Without it, the output is a brief `assetId`, `assetSymbol`, `headline`, `summary`, and `trends` list |
  
  ### Example
  
  ```bash
  mm pulse asset ETH
  mm pulse asset --caip-asset-type eip155:1/slip44:60
  mm pulse asset --hl-perps-market BTC --full
  ```
  
  ### Notes
  
  - If a symbol matches several assets, the command returns `PULSE_AMBIGUOUS`. Retry with `--caip-asset-type` or `--hl-perps-market`.
  - If no summary exists for the asset, the command returns `PULSE_NOT_FOUND`. Retry with another identifier type before reporting that no summary exists.
  - For RWAs, prefer `--hl-perps-market` over a bare symbol. The two can return different summaries for the same asset; for example, `NVDA` and `xyz:NVDA` differ.
  - Social posts and their URLs are unverified. Flag lookalike handles and airdrop or "checker" links as possible phishing.
  
  ## `pulse market` Command
  
  Show the latest AI-generated market-wide overview.
  
  ### Syntax
  
  ```bash
  mm pulse market [--full]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--full` | No | Include full trend details, sources, articles, and related assets. Without it, the output is a brief `generatedAt` timestamp and `trends` list |
  
  ### Example
  
  ```bash
  mm pulse market
  mm pulse market --full
  ```
  
  ### Notes
  
  - Pulse summaries are AI-generated. Present them as summaries, not as trading advice, and cite `generatedAt` when the user asks how recent they are.
  

• skills/metamask-agent-wallet/references/perps.md29 KBd5ead3904e38upstream ↗

  # Perpetual Trading Commands
  
  Use `perps` commands to trade perpetual futures on supported venues. Currently supported venue: `hyperliquid`.
  
  ## Common Flags
  
  Most `perps` commands accept these flags (`list-venues` does not):
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  
  The `--yes` flag skips interactive confirmation on `open`, `close`, `modify`, and `cancel` only. On `deposit`, `transfer`, and `withdraw`, `--yes` is accepted but has no effect because those commands do not prompt. Perps commands do not use `--wait`.
  
  `open`, `close`, `modify`, `cancel`, `positions`, `orders`, and `balance` accept `--vault <address>` to trade or read on behalf of a Hyperliquid vault instead of the connected wallet. `deposit`, `withdraw`, `transfer`, and vault deposits or withdrawals are not available on behalf of a vault and return `UNSUPPORTED_ROUTE`. In BYOK mode with an encrypted mnemonic, state-changing commands also accept `--password` to unlock the mnemonic. Set `MM_PASSWORD` env var instead of passing inline.
  
  ## `perps markets` Command
  
  List perpetual markets for a venue.
  
  ### Syntax
  
  ```bash
  mm perps markets [--venue <venue>] [--network <network>] [--symbol <symbol>] [--symbols <list>] [--dex <name>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid`. Run `mm perps list-venues` to see options |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--symbol` | No | Filter to a single market symbol such as BTC |
  | `--symbols` | No | Comma-separated market symbols to filter such as BTC,ETH,SOL |
  | `--dex` | No | HIP-3 DEX name; omit for the main Hyperliquid DEX. Run `mm perps dexs` to see options |
  
  ### Example
  
  ```bash
  mm perps markets --venue hyperliquid
  mm perps markets --venue hyperliquid --symbol BTC
  mm perps markets --venue hyperliquid --symbols BTC,ETH,SOL --network testnet
  mm perps markets --venue hyperliquid --dex <name from mm perps dexs>
  ```
  
  ## `perps balance` Command
  
  Show the connected wallet's perpetual account balances for a venue.
  
  ### Syntax
  
  ```bash
  mm perps balance [--venue <venue>] [--network <network>] [--dex <dex>] [--all-dexes] [--vault <address>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--dex` | No | HIP-3 DEX name. Omit to query only the main Hyperliquid DEX. Run `mm perps dexs` to see options |
  | `--all-dexes` | No | Aggregate balances across all DEXs. Mutually exclusive with `--dex` |
  | `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to read the vault's account instead of the connected wallet's. Malformed values return `INVALID_ADDRESS` |
  
  ### Example
  
  ```bash
  mm perps balance --venue hyperliquid
  mm perps balance --venue hyperliquid --network testnet
  mm perps balance --venue hyperliquid --all-dexes
  ```
  
  ## `perps positions` Command
  
  List open positions for the connected wallet on a venue.
  
  With `--funding`, each position also carries `fundingRate`, the current hourly market rate in the same units as `mm perps markets`. The field is omitted when the markets request fails; the positions still return.
  
  
  ### Syntax
  
  ```bash
  mm perps positions [--venue <venue>] [--network <network>] [--dex <dex>] [--all-dexes] [--funding] [--vault <address>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--dex` | No | HIP-3 DEX name. Omit to query only the main Hyperliquid DEX. Run `mm perps dexs` to see options |
  | `--all-dexes` | No | Aggregate positions across all DEXs. Mutually exclusive with `--dex` |
  | `--funding` | No | Also fetch the current market funding rate for each open position. Without it, the extra markets request is skipped |
  | `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to read the vault's account instead of the connected wallet's. Malformed values return `INVALID_ADDRESS` |
  
  ### Example
  
  ```bash
  mm perps positions --venue hyperliquid
  mm perps positions --venue hyperliquid --network testnet
  mm perps positions --venue hyperliquid --all-dexes
  mm perps positions --venue hyperliquid --funding
  ```
  
  ## `perps funding` Command
  
  List funding payments for the connected wallet on a venue. Each row is one funding credit or debit from the account ledger. For market funding rates, use `mm perps funding-rates`.
  
  ### Syntax
  
  ```bash
  mm perps funding [--venue <venue>] [--network <network>] [--symbol <symbol>] [--start-time <ms>] [--end-time <ms>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--symbol` | No | Filter to one market symbol such as BTC. Omit to list every funding payment in the window |
  | `--start-time` | No | Window start as a whole Unix timestamp in milliseconds, not seconds or an ISO date. Any other format, or a start later than `--end-time`, returns `INVALID_INPUT`. Defaults to 30 days before the end of the window. The window cannot exceed 365 days; a longer one returns `HYPERLIQUID_ERROR` |
  | `--end-time` | No | Window end as a whole Unix timestamp in milliseconds, not seconds or an ISO date. Any other format returns `INVALID_INPUT`. Defaults to now |
  
  ### Example
  
  ```bash
  mm perps funding --venue hyperliquid
  mm perps funding --venue hyperliquid --symbol BTC
  mm perps funding --venue hyperliquid --start-time 1760000000000 --end-time 1760600000000
  ```
  
  ## `perps funding-rates` Command
  
  Show hourly market funding rates for one symbol over a lookback window. This is public market history, not the connected account's funding payments.
  
  ### Syntax
  
  ```bash
  mm perps funding-rates [--venue <venue>] --symbol <symbol> --window <window> [--network <network>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--symbol` | Yes | Market symbol such as BTC. HIP-3 markets use the prefixed symbol such as `xyz:XYZ100` |
  | `--window` | Yes | Lookback window: `1h`, `8h`, or `1d`. Any other value returns `INVALID_WINDOW` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  
  ### Example
  
  ```bash
  mm perps funding-rates --venue hyperliquid --symbol BTC --window 8h
  mm perps funding-rates --venue hyperliquid --symbol ETH --window 1d
  ```
  
  ## `perps quote` Command
  
  Estimate entry price, notional, fees, and liquidation price without placing an order.
  
  ### Syntax
  
  ```bash
  mm perps quote [--venue <venue>] --symbol <symbol> --side <side> --size <size> --leverage <leverage> [--type <type>] [--limit-px <price>] [--tif <tif>] [--network <network>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--symbol` | Yes | Market symbol such as BTC, ETH, or SOL |
  | `--side` | Yes | Position direction: `long` or `short` |
  | `--size` | Yes | Size in base asset, human-readable such as 0.01 or 1 |
  | `--leverage` | Yes | Leverage multiplier as a positive integer such as 5 or 10 |
  | `--type` | No | Order type: `market` or `limit`. Defaults to `market` |
  | `--limit-px` | If `--type limit` | Limit price, human-readable such as 60000 for BTC |
  | `--tif` | No | Time in force: `gtc`, `ioc`, or `alo`. `alo` is post-only. `gtc` and `alo` require `--type limit` and `--limit-px`; `ioc` works with any order type. Omit to keep the defaults: `ioc` for market and `gtc` for limit. Invalid values or combinations return `INVALID_TIF` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  
  ### Example
  
  ```bash
  mm perps quote --venue hyperliquid --symbol BTC --side long --size 0.01 --leverage 5
  mm perps quote --venue hyperliquid --symbol ETH --side short --size 1 --leverage 10 --type limit --limit-px 2500
  mm perps quote --venue hyperliquid --symbol ETH --side short --size 1 --leverage 10 --type limit --limit-px 2500 --tif alo
  ```
  
  ## `perps open` Command
  
  Open a new perpetual position by placing an order.
  
  ### Syntax
  
  ```bash
  mm perps open [--venue <venue>] --symbol <symbol> --side <side> --size <size> --leverage <leverage> [--type <type>] [--limit-px <price>] [--tif <tif>] [--max-slippage-bps <bps>] [--reduce-only] [--network <network>] [--vault <address>] [--dry-run] [--yes] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--symbol` | Yes | Market symbol such as BTC, ETH, or SOL |
  | `--side` | Yes | Position direction: `long` or `short` |
  | `--size` | Yes | Size in base asset, human-readable such as 0.01 or 1 |
  | `--leverage` | Yes | Leverage multiplier as a positive integer such as 5 or 10 |
  | `--type` | No | Order type: `market` or `limit`. Defaults to `market` |
  | `--limit-px` | If `--type limit` | Limit price; required when `--type` is `limit` such as 60000 for BTC |
  | `--tif` | No | Time in force: `gtc`, `ioc`, or `alo`. `alo` is post-only. `gtc` and `alo` require `--type limit` and `--limit-px`; `ioc` works with any order type. Omit to keep the defaults: `ioc` for market and `gtc` for limit. Invalid values or combinations return `INVALID_TIF` |
  | `--max-slippage-bps` | No | Slippage cap in basis points for IOC market pricing such as 50 |
  | `--reduce-only` | No | Submit an order that can only reduce or close the existing position. If it would increase or flip the position, the venue rejects it with `REDUCE_ONLY_REJECTED` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to trade on behalf of a vault you lead. Malformed values return `INVALID_ADDRESS` |
  | `--dry-run` | No | Validate and preview the order without signing or submitting |
  | `--yes` | No | Skip interactive confirmation |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Example
  
  ```bash
  mm perps open --venue hyperliquid --symbol BTC --side long --size 0.01 --leverage 5
  mm perps open --venue hyperliquid --symbol ETH --side short --size 1 --leverage 10 --type limit --limit-px 2500
  mm perps open --venue hyperliquid --symbol BTC --side long --size 0.05 --leverage 3 --dry-run
  mm perps open --venue hyperliquid --symbol BTC --side short --size 0.01 --leverage 5 --reduce-only
  mm perps open --venue hyperliquid --symbol ETH --side long --size 1 --leverage 5 --type limit --limit-px 2400 --tif alo
  ```
  
  ## `perps orders` Command
  
  List resting orders for the connected wallet on a venue.
  
  ### Syntax
  
  ```bash
  mm perps orders [--venue <venue>] [--network <network>] [--dex <dex>] [--vault <address>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--dex` | No | HIP-3 DEX name. Omit to query only the main Hyperliquid DEX. Run `mm perps dexs` to see options |
  | `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to read the vault's account instead of the connected wallet's. Malformed values return `INVALID_ADDRESS` |
  
  ### Example
  
  ```bash
  mm perps orders --venue hyperliquid
  mm perps orders --venue hyperliquid --network testnet
  mm perps orders --venue hyperliquid --dex <name from mm perps dexs>
  ```
  
  ## `perps close` Command
  
  Close one position, part of a position, or all open positions.
  
  ### Syntax
  
  ```bash
  mm perps close [--venue <venue>] [--symbol <symbol>] [--size <size>] [--all] [--max-slippage-bps <bps>] [--network <network>] [--vault <address>] [--dry-run] [--yes] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--symbol` | Yes, unless `--all` | Market symbol to close such as BTC or ETH |
  | `--size` | No | Partial close size in base asset such as 0.5; omit for full close. Not allowed with `--all` |
  | `--all` | No | Close all open positions; mutually exclusive with `--symbol` |
  | `--max-slippage-bps` | No | Slippage cap in basis points for IOC pricing such as 50 |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to trade on behalf of a vault you lead. Malformed values return `INVALID_ADDRESS` |
  | `--dry-run` | No | Preview the close action without signing or submitting |
  | `--yes` | No | Skip interactive confirmation |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Validation Rules
  
  - `--size` is not allowed with `--all`.
  
  ### Example
  
  ```bash
  mm perps close --venue hyperliquid --symbol BTC
  mm perps close --venue hyperliquid --symbol ETH --size 0.5
  mm perps close --venue hyperliquid --all
  mm perps close --venue hyperliquid --symbol BTC --dry-run
  ```
  
  ## `perps modify` Command
  
  Modify leverage, take-profit, or stop-loss for an existing position.
  
  ### Syntax
  
  ```bash
  mm perps modify [--venue <venue>] --symbol <symbol> [--leverage <leverage>] [--tp <price>] [--sl <price>] [--network <network>] [--vault <address>] [--dry-run] [--yes] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--symbol` | Yes | Market symbol such as BTC, ETH, or SOL |
  | `--leverage` | No | New leverage multiplier as a positive integer such as 5 or 10 |
  | `--tp` | No | Take-profit trigger price, human-readable such as 3000 or 2500.50 |
  | `--sl` | No | Stop-loss trigger price, human-readable such as 2000 or 1800.75 |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to trade on behalf of a vault you lead. Malformed values return `INVALID_ADDRESS` |
  | `--dry-run` | No | Preview the modify action without signing or submitting |
  | `--yes` | No | Skip interactive confirmation |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Validation Rules
  
  - At least one of `--leverage`, `--tp`, or `--sl` must be provided.
  
  ### Example
  
  ```bash
  mm perps modify --venue hyperliquid --symbol BTC --leverage 10
  mm perps modify --venue hyperliquid --symbol ETH --tp 3000 --sl 2000
  mm perps modify --venue hyperliquid --symbol BTC --leverage 3 --dry-run
  ```
  
  ## `perps cancel` Command
  
  Cancel a resting perps order.
  
  ### Syntax
  
  ```bash
  mm perps cancel [--venue <venue>] --order-id <id> [--symbol <symbol>] [--network <network>] [--vault <address>] [--dry-run] [--yes] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid`. Run `mm perps list-venues` to see options |
  | `--order-id` | Yes | Venue order ID to cancel. Must be a positive integer |
  | `--symbol` | No | Market symbol, speeds up cancel by avoiding an open-order lookup. For example BTC or ETH |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to trade on behalf of a vault you lead. Malformed values return `INVALID_ADDRESS` |
  | `--dry-run` | No | Preview the cancel action without signing or submitting |
  | `--yes` | No | Skip interactive confirmation |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Example
  
  ```bash
  mm perps cancel --venue hyperliquid --order-id 12345
  mm perps cancel --venue hyperliquid --order-id 12345 --symbol BTC
  mm perps cancel --venue hyperliquid --order-id 12345 --dry-run
  mm perps cancel --venue hyperliquid --order-id 12345 --yes
  ```
  
  ## `perps deposit` Command
  
  Deposit USDC into a perpetual venue.
  
  ### Syntax
  
  ```bash
  mm perps deposit [--venue <venue>] --amount <amount> [--asset <asset>] [--source-chain-id <chain>] [--network <network>] [--dry-run] [--yes] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid`. Run `mm perps list-venues` to see options |
  | `--amount` | Yes | Human-readable USDC amount to deposit such as 100 or 50.5 |
  | `--asset` | No | Deposit asset. Defaults to `USDC` |
  | `--source-chain-id` | No | Source chain as a CAIP-2 ID or decimal chain ID. Defaults to Arbitrum for the selected network: `eip155:42161` on mainnet, `eip155:421614` on testnet |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--dry-run` | No | Preview the transaction without signing or submitting |
  | `--yes` | No | Skip interactive confirmation |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Example
  
  ```bash
  mm perps deposit --venue hyperliquid --amount 100 --asset USDC
  mm perps deposit --venue hyperliquid --amount 100 --asset USDC --dry-run
  ```
  
  ## `perps withdraw` Command
  
  Withdraw USDC from a perpetual venue.
  
  ### Syntax
  
  ```bash
  mm perps withdraw [--venue <venue>] --amount <amount> [--asset <asset>] [--destination <address>] [--network <network>] [--dry-run] [--include-spot] [--yes] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid`. Run `mm perps list-venues` to see options |
  | `--amount` | Yes | Human-readable USDC amount to withdraw such as 50 or 25.5 |
  | `--asset` | No | Withdrawal asset. Defaults to `USDC` |
  | `--destination` | No | EVM destination address. Defaults to your connected wallet |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--dry-run` | No | Preview the withdrawal without signing or submitting |
  | `--include-spot` | No | Move free spot USDC to perp before withdrawing if needed |
  | `--yes` | No | Skip interactive confirmation |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Example
  
  ```bash
  mm perps withdraw --venue hyperliquid --amount 50 --asset USDC
  mm perps withdraw --venue hyperliquid --amount 50 --asset USDC --include-spot
  mm perps withdraw --venue hyperliquid --amount 50 --asset USDC --destination 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18
  ```
  
  ## `perps transfer` Command
  
  Transfer USDC between spot and perp accounts on a perpetual venue.
  
  ### Syntax
  
  ```bash
  mm perps transfer [--venue <venue>] --amount <amount> --direction <direction> [--asset <asset>] [--network <network>] [--dry-run] [--yes] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--amount` | Yes | Human-readable USDC amount to transfer such as 100 or 50.5 |
  | `--direction` | Yes | Transfer direction: `spot-to-perp` or `perp-to-spot` |
  | `--asset` | No | Transfer asset. Defaults to `USDC` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--dry-run` | No | Preview the transfer without signing or submitting |
  | `--yes` | No | Skip interactive confirmation |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Example
  
  ```bash
  mm perps transfer --venue hyperliquid --amount 100 --direction spot-to-perp --asset USDC
  mm perps transfer --venue hyperliquid --amount 50 --direction perp-to-spot --asset USDC
  ```
  
  ## `perps list-venues` Command
  
  List available perpetual futures venues.
  
  ### Syntax
  
  ```bash
  mm perps list-venues
  ```
  
  ### Supported Flags
  
  This command does not support additional flags beyond output format options.
  
  ### Example
  
  ```bash
  mm perps list-venues
  ```
  
  ## `perps dexs` Command
  
  List available DEX identifiers a venue exposes. For Hyperliquid, this includes the main DEX and any HIP-3 builder-deployed DEXs.
  
  ### Syntax
  
  ```bash
  mm perps dexs [--venue <venue>] [--network <network>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  
  ### Example
  
  ```bash
  mm perps dexs --venue hyperliquid
  ```
  
  ## `perps vault list` Command
  
  List the connected wallet's equity in Hyperliquid vaults.
  
  ### Syntax
  
  ```bash
  mm perps vault list [--venue <venue>] [--network <network>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  
  ### Example
  
  ```bash
  mm perps vault list --venue hyperliquid
  ```
  
  ## `perps vault info` Command
  
  Show metadata for a Hyperliquid vault.
  
  ### Syntax
  
  ```bash
  mm perps vault info [--venue <venue>] --vault <address> [--network <network>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--vault` | Yes | Hyperliquid vault address, 0x-prefixed hex. Malformed values return `INVALID_ADDRESS`, and an address with no vault returns `INVALID_INPUT` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  
  ### Example
  
  ```bash
  mm perps vault info --venue hyperliquid --vault 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303
  ```
  
  ## `perps vault deposit` Command
  
  Deposit USDC from the connected wallet's perp balance into a Hyperliquid vault. Creating a vault is not supported.
  
  ### Syntax
  
  ```bash
  mm perps vault deposit [--venue <venue>] --vault <address> --amount <amount> [--network <network>] [--dry-run] [--yes] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--vault` | Yes | Hyperliquid vault address, 0x-prefixed hex. Malformed values return `INVALID_ADDRESS` |
  | `--amount` | Yes | Human-readable USDC amount such as 100. The minimum is 1 USDC. The amount must fit in the perp spendable balance, otherwise `INSUFFICIENT_BALANCE`. In standard account mode, move spot USDC to perp first with `mm perps transfer`; unified accounts already include free spot USDC |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--dry-run` | No | Validate the flags and return a `prepared` status without signing. Balance, minimum, and vault checks only run on a live deposit |
  | `--yes` | No | Skip interactive confirmation |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Example
  
  ```bash
  mm perps vault deposit --venue hyperliquid --vault 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303 --amount 100 --dry-run
  mm perps vault deposit --venue hyperliquid --vault 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303 --amount 100
  ```
  
  ## `perps vault withdraw` Command
  
  Withdraw USDC from a Hyperliquid vault back to the connected wallet's perp balance.
  
  ### Syntax
  
  ```bash
  mm perps vault withdraw [--venue <venue>] --vault <address> --amount <amount> [--network <network>] [--dry-run] [--yes] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--vault` | Yes | Hyperliquid vault address, 0x-prefixed hex. Malformed values return `INVALID_ADDRESS` |
  | `--amount` | Yes | Human-readable USDC amount such as 50. The minimum is 1 USDC, and the amount cannot exceed your equity in the vault, otherwise `INSUFFICIENT_BALANCE`. Equity still inside its lock period returns `UNSUPPORTED_ROUTE` with the unlock time |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--dry-run` | No | Validate the flags and return a `prepared` status without signing. Equity, minimum, and lock checks only run on a live withdrawal |
  | `--yes` | No | Skip interactive confirmation |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Example
  
  ```bash
  mm perps vault withdraw --venue hyperliquid --vault 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303 --amount 50
  ```
  
  ## `perps account mode get` Command
  
  Show the Hyperliquid account abstraction mode for the connected wallet. In `standard` mode spot and perp balances are separate; in `unified` mode they are pooled.
  
  ### Syntax
  
  ```bash
  mm perps account mode get [--venue <venue>] [--network <network>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  
  ### Example
  
  ```bash
  mm perps account mode get --venue hyperliquid
  ```
  
  ## `perps account mode set` Command
  
  Switch the Hyperliquid account abstraction mode for the connected wallet. This changes how spot and perp balances are pooled for the whole Hyperliquid account, not only for one command.
  
  ### Syntax
  
  ```bash
  mm perps account mode set [--venue <venue>] --mode <mode> [--network <network>] [--yes] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` |
  | `--mode` | Yes | Target mode: `standard` for separate spot and perp balances, or `unified` for pooled balances. If the account is already in that mode, the command returns `ALREADY_SET_ACCOUNT_MODE` |
  | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` |
  | `--yes` | No | Skip interactive confirmation |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  There is no `--dry-run`. Run `mm perps account mode get` first to show the user the current mode.
  
  ### Output
  
  `venue`, `network`, `previousRawState`, `rawState`, `mode`, and `changed`. The CLI reads the mode back after switching and returns `HYPERLIQUID_ERROR` if the change did not take effect.
  
  ### Example
  
  ```bash
  mm perps account mode set --venue hyperliquid --mode unified
  ```
  
  ## Notes
  
  - If the user does not mention a token symbol, use `mm perps markets` to list available markets and confirm the symbol with the user before proceeding.
  - To answer "how much funding have I paid or earned", use `mm perps funding` for the payment ledger or the `funding` object from `mm perps positions` for running totals. To answer "what is the funding rate", use `mm perps funding-rates` for history or `mm perps positions --funding` and `mm perps markets` for the current rate.
  

• skills/metamask-agent-wallet/references/plugins.md11 KBe35a99890de0upstream ↗

  # Plugins commands
  
  Third-party npm packages can add first-class `mm` commands that appear in `mm help` and in the REPL. The `mm plugins` commands manage them. This system is beta and off by default.
  
  This reference covers CLI plugins only. It is unrelated to the agent skills install that `mm doctor` reports as `skillSource`. See [doctor.md](doctor.md) for that.
  
  ## Trust model
  
  Read this before installing anything. Plugins run in-process and unsandboxed, with the same privileges as the CLI. Install-time consent is the real trust boundary. Capability gates and the hidden session and mnemonic store are defense in depth, and a malicious package can import the SDK directly.
  
  | Rule | Detail |
  | --- | --- |
  | Never install without explicit user approval | Show the package name, version, declared commands, data access, and requested capabilities, then ask. Approval for one package never carries over to another |
  | Never bypass the consent prompt | Pass `--accept-permissions` only when the user has already reviewed the manifest and the environment cannot show a prompt |
  | Treat sensitive capabilities as high risk | The consent screen marks `wallet-submit` and `network-manage` with a warning sign. Call them out explicitly |
  | Keep unverified installs off | Enable `experimentalAllowUnverifiedInstalls` only for a plugin the user is building |
  | Apply host confirmation rules to plugin commands | A plugin command that signs or submits is still a write operation. Confirm it the way you confirm `mm transfer`, and run `mm decode` on unfamiliar calldata |
  
  Signing from a plugin still routes through MetaMask policy and stays MFA gated.
  
  ## Enabling the beta
  
  Installing a plugin and running a plugin command are both blocked until the user enables the feature.
  
  ```bash
  mm config set experimentalPlugins true
  ```
  
  A local source needs a second key as well. Local sources are `file:` specs, relative paths, absolute paths, git sources, and `mm plugins link`.
  
  ```bash
  mm config set experimentalAllowUnverifiedInstalls true
  ```
  
  Both keys live in `~/.metamask/config.json` and are documented in [auth.md](auth.md). Run `mm config get` to read the current state before assuming either key is on.
  
  Setting `experimentalPlugins` back to `false` leaves plugins installed and makes their commands fail with `PLUGIN_BETA_DISABLED`.
  
  ```bash
  mm config set experimentalPlugins false
  ```
  
  ## Commands
  
  | Intent | Command | Beta gate |
  | --- | --- | --- |
  | List installed plugins | `mm plugins` | No |
  | Show a plugin's version, location, and commands | `mm plugins inspect <plugin>` | No |
  | Install from npm | `mm plugins install <pkg>` | Yes |
  | Update installed plugins | `mm plugins update [<pkg>]` | Yes |
  | Link a local directory for development | `mm plugins link <path>` | Yes, and unverified installs as well |
  | Remove one plugin | `mm plugins uninstall <plugin>` | No |
  | Remove every user-installed and linked plugin | `mm plugins reset` | Yes |
  
  Listing, inspecting, and uninstalling are never beta gated, so the user can always see what is installed and remove it.
  
  `mm plugins add` is an alias of install. `mm plugins remove` and `mm plugins unlink` are aliases of uninstall.
  
  ### Output format
  
  These commands come from oclif rather than the host command layer, so the global `--format` and `--toon` flags do not apply. `mm plugins --toon` fails with `Nonexistent flag: --toon`. Use `--json` or plain text instead.
  
  | Command | Flags |
  | --- | --- |
  | `mm plugins` | `--json`, `--core` to include core plugins |
  | `mm plugins inspect` | `--json`, `--verbose` |
  | `mm plugins install` | `--json`, `--force`, `--silent`, `--verbose`, `--accept-permissions` |
  | `mm plugins update` | `--verbose` |
  | `mm plugins link` | `--install`, `--verbose` |
  | `mm plugins uninstall` | `--verbose` |
  | `mm plugins reset` | `--hard`, `--reinstall` |
  
  The host help cannot resolve `mm plugins install --help`. Use the colon form instead, such as `mm plugins:install --help`.
  
  ## Install flow
  
  1. Check the gate with `mm config get`. If `experimentalPlugins` is `false`, ask the user before setting it to `true`.
  
  2. Preview the package before installing it. The consent screen is built from the `mm` block in the package's `package.json`, and the CLI reads that block with this call.
  
     ```bash
     npm view <pkg> --json
     ```
  
     Surface every command id, every `dataAccess` entry, and every capability to the user. Capabilities come from both `mm.capabilities` and `mm.commands[].capabilities`.
  
  3. Install one package at a time so each consent screen is reviewed on its own.
  
     ```bash
     mm plugins install @acme/mm-report
     ```
  
     The permission screen prints on stderr and the confirm prompt defaults to No. Declining exits with `PERMISSION_DENIED` and changes nothing.
  
  4. A non-TTY session cannot show that prompt, and neither can a run that passes `--json`. Both fail with `PERMISSION_DENIED` unless `--accept-permissions` is passed. Add that flag only after the user has approved the reviewed manifest.
  
     ```bash
     mm plugins install @acme/a @acme/b --accept-permissions
     ```
  
     One `--accept-permissions` consents to every package named in the command, so prefer separate commands.
  
  5. Verify with `mm plugins` and `mm plugins inspect <plugin>`, then run the new command.
  
  Installs fail closed. If the npm registry is unreachable or the package cannot be resolved, nothing is installed and the CLI reports `PLUGIN_METADATA_UNAVAILABLE`. Plugin lifecycle scripts such as `postinstall` never run, because the CLI forces `npm_config_ignore_scripts` to `true` on every plugin install, update, link, reset, and uninstall.
  
  ### What must hold for an install to succeed
  
  | Requirement | Error when violated |
  | --- | --- |
  | Package name and version resolve | `PLUGIN_NOT_FOUND` |
  | The `mm` block in `package.json` is a valid manifest, with `schemaVersion` 1, a `minCliVersion`, and at least one command | `PLUGIN_MANIFEST_INVALID` |
  | The running CLI satisfies `minCliVersion` | `PLUGIN_CLI_VERSION` |
  | No command id collides with a built-in `mm` command | `PLUGIN_ID_COLLISION` |
  | The package declares neither `oclif.hooks` nor `oclif.plugins` | `PLUGIN_HOOKS_FORBIDDEN` |
  | The package ships a prebuilt `oclif.manifest.json` | `PLUGIN_MANIFEST_FILE_MISSING`, and the CLI removes the plugin again |
  | Each command class extends `PluginCommand` | `PLUGIN_INVALID_BASE` |
  | No sealed lifecycle member is overridden | `PLUGIN_SEALED_OVERRIDE` |
  | The source is npm, unless dev mode is on | `PLUGIN_UNVERIFIED_SOURCE` |
  
  ## Capabilities
  
  Capabilities are declared per command in the manifest and approved at install time.
  
  | Capability | Grants | Sensitive |
  | --- | --- | --- |
  | `wallet-read` | Read services for accounts, balances, prices, tokens, fees, and swap quotes, plus an authenticated public client for raw EVM RPC reads | No |
  | `wallet-submit` | The wallet executor for signing and submitting. Every use is audited, and policy and MFA gates still apply | Yes |
  | `network-manage` | The network registry | Yes |
  
  `mnemonic-read` and `config-write` are reserved and are not part of the beta schema. A manifest that declares either one fails validation. The CLI session and the mnemonic store are host only, so a plugin that reaches for them gets `PERMISSION_DENIED`.
  
  The consent screen also lists the `dataAccess` entries for each command. The full set is `accounts`, `balances`, `prices`, `tokens`, `network`, `fees`, `swap-quotes`, `session`, and `mnemonic`. That list is disclosure only. Enforcement happens through capabilities.
  
  ## Approvals and repeat consent
  
  An approved install writes a record under `plugins` in `~/.metamask/config.json`. The record holds `version`, `integrity`, `manifestHash`, `approvedCapabilities`, `approvedCommandIds`, and `approvedAt`.
  
  A fresh consent prompt appears whenever the version or the manifest hash changes, including on `mm plugins update`. Until the new manifest is approved, the plugin's commands run with zero capabilities, and any call that needs one fails with `PERMISSION_DENIED`. The same downgrade applies when the approval record is missing, and when the command id is missing from `approvedCommandIds`.
  
  When a plugin command returns `PERMISSION_DENIED`, do not retry it. Run `mm plugins install <pkg>` or `mm plugins update <pkg>` so the user can approve the current manifest, then run the command again.
  
  ## Uninstall
  
  ```bash
  mm plugins uninstall @acme/mm-report
  ```
  
  This removes the plugin code and deletes its approval record from `~/.metamask/config.json`. It is not beta gated and does not prompt for consent, so it still works after `experimentalPlugins` is set back to `false`. The argument is the installed package name, with or without a version or dist tag suffix.
  
  Reset removes everything the user installed or linked.
  
  ```bash
  mm plugins reset
  ```
  
  `mm plugins reset` is beta gated and destructive across all plugins. Show the `mm plugins` output and confirm the scope with the user first.
  
  If the user wants the commands gone but the packages kept, set `experimentalPlugins` to `false` instead of uninstalling.
  
  ## Where things live
  
  | What | Where |
  | --- | --- |
  | Plugin code | The oclif data directory. On macOS that is `~/Library/Application Support/mm/node_modules/<pkg>` and on Linux it is `~/.local/share/mm/node_modules/<pkg>` |
  | Approvals and beta flags | `~/.metamask/config.json`, under the `plugins`, `experimentalPlugins`, and `experimentalAllowUnverifiedInstalls` keys |
  | Host peer symlink | A link inside the data directory points `@metamask/agent-wallet` at the running CLI. The CLI creates it so a plugin import of `@metamask/agent-wallet/plugin` resolves to the same in-process instance |
  
  Manage all of this through the commands above. Never hand-edit `~/.metamask/config.json`, and never delete files under `~/.metamask/`, because that directory also holds wallets, the session, and the BYOK mnemonic.
  
  ## Local development
  
  Use these steps only for a plugin the user is building.
  
  ```bash
  mm config set experimentalPlugins true
  mm config set experimentalAllowUnverifiedInstalls true
  mm plugins install file:/path/to/mm-plugin-hello.tgz --accept-permissions
  mm plugins link /path/to/mm-plugin-hello
  ```
  
  These sources show an unverified source banner ahead of the capability screen. A local install and a link both still write an approval record, built from the `package.json` on disk. A bare path such as `acme/mm-hello` reads as a GitHub slug rather than a directory, and the CLI refuses it unless dev mode is on.
  
  ## Notes
  
  - Plugin commands respect `requiresAuth` and `requiresInit`, and both default to `true`. Most plugin commands therefore need `mm login` and `mm init` first, exactly like host commands. Run the `mm doctor` readiness gate before invoking one.
  - A user-installed plugin overrides a core plugin of the same name.
  - `mm plugins` lists user plugins only. Add `--core` to include the bundled oclif plugins.
  - `MM_NPM_LOG_LEVEL` sets the npm log level for these installs, and `MM_NPM_REGISTRY` sets the npm registry.
  

• skills/metamask-agent-wallet/references/polling.md1.7 KBd320ec9aa552upstream ↗

  # Polling Commands
  
  In server wallet mode, signing and transaction commands return a `pollingId` instead of an immediate result. Use these commands to track and wait for results. Both commands are server-wallet mode only.
  
  Transfers, swaps, perps, predict orders, and predict withdraws attach a human-readable `intent` summary to their request, such as `Transfer 0.5 ETH to 0x...` or `Withdraw 10 pUSD to 0x...`. When listing or watching requests, surface the `intent` so the user can confirm what they are approving.
  
  ## `wallet requests list` Command
  
  List all pending wallet requests.
  
  ### Syntax
  
  ```bash
  mm wallet requests list [--sync] [--toon]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--sync` | No | Refresh pending requests before listing. Defaults to true. Use `--no-sync` to skip |
  
  ### Example
  
  ```bash
  mm wallet requests list
  mm wallet requests list --no-sync --toon
  ```
  
  ## `wallet requests watch` Command
  
  Wait for a specific wallet request to complete by its polling ID. MFA prompts are surfaced once when a job enters the `AWAITING_MFA` state. Detect MFA pauses by scanning stdout for the literal `AWAITING_MFA` token — see the **MFA Approval Pauses** section in `SKILL.md`.
  
  ### Syntax
  
  ```bash
  mm wallet requests watch <polling-id> [--wallet-timeout <seconds>] [--toon]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `<polling-id>` | Yes | Polling ID returned by a previous command. Positional argument. Run `mm wallet requests list` to see pending IDs |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Example
  
  ```bash
  mm wallet requests watch abc-123
  mm wallet requests watch abc-123 --toon
  ```
  

• skills/metamask-agent-wallet/references/predict.md25 KBa1844b70742bupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/references/signing.md2.8 KB34f2e5a87ff7upstream ↗

  # Signing Commands
  
  Use `wallet sign-message` and `wallet sign-typed-data` to produce
  cryptographic signatures with the active wallet.
  
  ## `wallet sign-message` Command
  
  Sign a plaintext message with the active wallet.
  
  ### Syntax
  
  ```bash
  mm wallet sign-message --message <text> --chain-id <id> [--wait] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--chain-id` | Yes | EVM chain ID as a positive integer, such as 1 or 137. If not mentioned, ask the user. |
  | `--message` | Yes | Plain-text message to sign |
  | `--wait` | No | Block until the signature request completes. In server-wallet mode only, BYOK returns immediately |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Example
  
  ```bash
  mm wallet sign-message --message "Hello, world!" --chain-id 1
  mm wallet sign-message --message "Hello" --chain-id 1 --wait
  ```
  
  ## `wallet sign-typed-data` Command
  
  Sign EIP-712 typed data with the active wallet.
  
  ### Syntax
  
  ```bash
  mm wallet sign-typed-data --chain-id <id> --payload '<JSON>' [--wait] [--password <password>] [--wallet-timeout <seconds>]
  ```
  
  ### Supported Flags
  
  | Name | Required | Description |
  | --- | --- | --- |
  | `--chain-id` | Yes | EVM chain ID as a positive integer, such as 1 or 137 |
  | `--payload` | Yes | EIP-712 typed data as a JSON string with `domain`, `types`, `primaryType`, and `message` |
  | `--wait` | No | Block until the signature request completes. In server-wallet mode only, BYOK returns immediately |
  | `--intent` | No | Human-readable summary of what is being signed, forwarded with the request |
  | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline |
  | `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` |
  
  ### Example
  
  ```bash
  mm wallet sign-typed-data --chain-id 1 --payload '{"types":...,"primaryType":...,"domain":...,"message":...}'
  mm wallet sign-typed-data --chain-id 137 --payload '{"types":...}' --wait --intent "Approve 10 USDC"
  ```
  
  ## EIP-712 Typed Data
  
  The `--payload` must be valid JSON with these required fields:
  - `types` -- type definitions
  - `primaryType` -- the main type being signed
  - `domain` -- domain separator containing name, version, chainId, and verifyingContract
  - `message` -- the actual data to sign
  
  ## Notes
  
  - If the Chain is not mentioned by the user, ask for the chain.
  - In server-wallet mode, signing returns a `pollingId` when `--wait` is omitted. See `references/polling.md` to track requests.
  

• skills/metamask-agent-wallet/references/swap.md14 KB04a9f04ecdd4upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/references/transaction.md2.6 KBbd2d68da51c3upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/references/transfer.md2.4 KB85f16830a5d9upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/references/tx-history.md3.4 KB13d220cc8c02upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/references/wallet.md9.2 KBc0a78f384e40upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/references/x402.md11 KB3c373e71bd8bupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/bridge.md4.7 KB295f24299ea8upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/earn-supply.md2.2 KBd29d2baba1adupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/earn-withdraw.md1.4 KB2deae441c151upstream ↗

  # Earn Withdraw Workflow
  
  Use this workflow when the user wants to withdraw tokens from a DeFi earn vault.
  
  Reference command syntax in `references/earn.md`.
  
  ## Flow
  
  1. Check positions.
  2. Confirm with the user.
  3. Withdraw.
  
  ## Check Positions
  
  List current earn positions to see what the user has deposited:
  
  ```bash
  mm earn positions
  mm earn positions --chain-id 8453
  ```
  
  Show the user their positions with balance and protocol info.
  
  ## Withdraw
  
  Partial withdrawal:
  
  ```bash
  mm earn withdraw --token USDC --amount 50 --chain-id 8453
  ```
  
  Full withdrawal:
  
  ```bash
  mm earn withdraw --token USDC --all --chain-id 8453
  ```
  
  With a specific vault:
  
  ```bash
  mm earn withdraw --vault 0xabc...def --all --chain-id 1
  ```
  
  ## Confirm
  
  Before executing, confirm with the user: token, amount (or full balance), chain, and vault/protocol.
  
  ## Edge cases
  
  - `NOT_REDEEMABLE`: the vault does not support withdrawals. Inform the user and suggest checking other vaults.
  - `VAULT_NOT_FOUND`: no matching vault. Run `mm earn positions` to check current positions.
  - `INSUFFICIENT_FUNDS`: trying to withdraw more than the deposited balance. Use `--all` to withdraw the full amount.
  - `EXECUTE_FAILED`: if the message names MFA approval and `mm wallet requests watch`, follow MFA Approval Pauses in `SKILL.md`. Otherwise the transaction reverted — retry or check the transaction on the block explorer.
  - `QUOTE_FAILED`: LiFi returned no executable transaction. Try a different amount or vault.
  

• skills/metamask-agent-wallet/workflows/login.md978 B9d7622089b01upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/market-data.md3.6 KBcabef2982e30upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/onboarding.md3.6 KB816f70eacf03upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/perps-close-position.md1020 B8aa26ec13055upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/perps-modify-position.md1.0 KB3f28f06c1262upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/perps-open-position.md2.8 KBef2ea6743c3bupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/predict-funding.md2.7 KB58e8d6e999caupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/predict-history.md2.2 KBbde2c008ab4fupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/predict-manage-orders.md935 B5fd10d749f04upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/predict-markets.md1.3 KBc220aa128a7bupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/predict-place-order.md2.3 KB4305eb573c23upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/predict-portfolio.md900 Bb64ede075ee8upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/predict-setup.md1.3 KBd442ae33d42fupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/swap.md4.1 KB36bdb07f2171upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/troubleshooting.md8.6 KBa19ee9a60bebupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/x402-mcp.md2.9 KB45e2f06b4e59upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• skills/metamask-agent-wallet/workflows/x402-pay.md2.9 KBeedda9a3b8e2upstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• README.mdupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/metamask-agent-skills-skills-metamask-agent-wallet.md