# metamask-agent-wallet Adopt this skill: https://proskills.md/skills/other/metamask-agent-skills-skills-metamask-agent-wallet Page: https://proskills.md/skills/other/metamask-agent-skills-skills-metamask-agent-wallet This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required. ## File: skills/metamask-agent-wallet/SKILL.md size: 29047 sha: 5ad19a9693f3152e826d66a44e56a02f5ef23a25 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/SKILL.md ````text --- 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 ``, this skill targets ``, latest release is ``. 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 ` 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 `. 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 ` — 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 --help` and guide from there. ```` ## File: skills/metamask-agent-wallet/scripts/amount_to_hex.py size: 631 sha: fe18b7b977a3a18b54597f6ace54769ceefd8129 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/scripts/amount_to_hex.py ```text #!/usr/bin/env python3 """Convert a human-readable token amount to 0x-prefixed hex for EVM calldata. Usage: python3 amount_to_hex.py 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]} ", file=sys.stderr) sys.exit(1) decimals = int(sys.argv[2]) value = int(Decimal(sys.argv[1]) * 10 ** decimals) print(hex(value)) ``` ## File: skills/metamask-agent-wallet/scripts/x402_pay.py size: 35006 sha: 586408b1fcd27567d78e5fb3b9843f6a0c4cb304 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/scripts/x402_pay.py Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/scripts/x402_pay.py ## File: skills/metamask-agent-wallet/references/auth.md size: 10420 sha: 16c1d9d64d6ed1c097fec79f2ffe1add30c057c2 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/auth.md ````text # 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 ] [--mnemonic ] [--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 ] [--timeout ] [--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 ``` ### 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 `. - 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 ] ``` ### 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 ] [--new ] ``` ### 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 ] ``` ### 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. | ```` ## File: skills/metamask-agent-wallet/references/chain.md size: 561 sha: 2792df7bec63b09dfaf115c443030face947833b upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/chain.md ````text # 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 | ```` ## File: skills/metamask-agent-wallet/references/decode.md size: 1254 sha: ed859ceb2e821dd34c95313305c62f9c0b58d95e upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/decode.md ````text # 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. ```` ## File: skills/metamask-agent-wallet/references/doctor.md size: 2897 sha: 0814e74f94f752b5a0b7e8ad23c1f079fbb71e2f upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/doctor.md ````text # 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//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@` 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. ```` ## File: skills/metamask-agent-wallet/references/earn.md size: 6903 sha: aef1ac0d706a216e0655fddf554406d70f000de6 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/earn.md ````text # 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 ] [--token ] [--protocol ] [--min-tvl ] [--sort apy|tvl] [--limit ] ``` ### 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 ] [--address
] [--token ] [--protocol ] [--vault
] [--min-usd ] [--sort usd] [--limit ] ``` ### 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 --amount --chain-id [--vault
] [--protocol ] [--min-tvl ] [--from-chain-id ] [--from-token ] [--wait] [--password ] [--wallet-timeout ] ``` ### 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 --amount --chain-id [--vault
] [--protocol ] [--all] [--password ] [--wallet-timeout ] ``` ### 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. ```` ## File: skills/metamask-agent-wallet/references/errors.md size: 21265 sha: 3be0c76599509e19be029ad7a895335237918d60 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/errors.md ```text # 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 `:`. `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 ` 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 ` or `--hl-perps-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 --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 ` 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 | ``` ## File: skills/metamask-agent-wallet/references/market-data.md size: 10896 sha: dd799c04542c77957bc1ea0925edbcf5abeadd7a upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/market-data.md ````text # 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 [--vs ] [--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 [--asset-type ] [--time-period ] [--interval ] [--from ] [--to ] [--vs ] ``` ### 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 ] mm token list trending [--chain-id ] mm token list top-gainer [--chain-id ] ``` ### 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 [--chain-ids ] [--limit ] [--after ] ``` ### Supported Flags | Name | Required | Description | | --- | --- | --- | | `` | 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 [--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 ] [--active ] [--custodian ] [--type ] [--industry ] [--sort-by ] [--limit ] [--after ] [--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 [--full] mm pulse asset --caip-asset-type [--full] mm pulse asset --hl-perps-market [--full] ``` ### Supported Flags | Name | Required | Description | | --- | --- | --- | | `` | 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. ```` ## File: skills/metamask-agent-wallet/references/perps.md size: 29306 sha: d5ead3904e3826ba6a1490cb25b5a43c25d8fff2 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/perps.md ````text # 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
` 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 ] [--network ] [--symbol ] [--symbols ] [--dex ] ``` ### 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 ``` ## `perps balance` Command Show the connected wallet's perpetual account balances for a venue. ### Syntax ```bash mm perps balance [--venue ] [--network ] [--dex ] [--all-dexes] [--vault
] ``` ### 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 ] [--network ] [--dex ] [--all-dexes] [--funding] [--vault
] ``` ### 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 ] [--network ] [--symbol ] [--start-time ] [--end-time ] ``` ### 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 ] --symbol --window [--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 ] --symbol --side --size --leverage [--type ] [--limit-px ] [--tif ] [--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 ] --symbol --side --size --leverage [--type ] [--limit-px ] [--tif ] [--max-slippage-bps ] [--reduce-only] [--network ] [--vault
] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### 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 ] [--network ] [--dex ] [--vault
] ``` ### 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 ``` ## `perps close` Command Close one position, part of a position, or all open positions. ### Syntax ```bash mm perps close [--venue ] [--symbol ] [--size ] [--all] [--max-slippage-bps ] [--network ] [--vault
] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### 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 ] --symbol [--leverage ] [--tp ] [--sl ] [--network ] [--vault
] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### 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 ] --order-id [--symbol ] [--network ] [--vault
] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### 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 ] --amount [--asset ] [--source-chain-id ] [--network ] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### 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 ] --amount [--asset ] [--destination
] [--network ] [--dry-run] [--include-spot] [--yes] [--password ] [--wallet-timeout ] ``` ### 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 ] --amount --direction [--asset ] [--network ] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### 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 ] [--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 ] [--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 ] --vault
[--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 ] --vault
--amount [--network ] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### 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 ] --vault
--amount [--network ] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### 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 ] [--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 ] --mode [--network ] [--yes] [--password ] [--wallet-timeout ] ``` ### 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. ```` ## File: skills/metamask-agent-wallet/references/plugins.md size: 11060 sha: e35a99890de02a4a5b1f25c73992cf62caed17bc upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/plugins.md ````text # 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 ` | No | | Install from npm | `mm plugins install ` | Yes | | Update installed plugins | `mm plugins update []` | Yes | | Link a local directory for development | `mm plugins link ` | Yes, and unverified installs as well | | Remove one plugin | `mm plugins uninstall ` | 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 --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 `, 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 ` or `mm plugins update ` 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/` and on Linux it is `~/.local/share/mm/node_modules/` | | 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. ```` ## File: skills/metamask-agent-wallet/references/polling.md size: 1788 sha: d320ec9aa5528189dcc7cb59132d964da5206028 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/polling.md ````text # 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 [--wallet-timeout ] [--toon] ``` ### Supported Flags | Name | Required | Description | | --- | --- | --- | | `` | 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 ``` ```` ## File: skills/metamask-agent-wallet/references/predict.md size: 25283 sha: a1844b70742bdac429ff5131d08b36cc7dd17d87 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/predict.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/predict.md ## File: skills/metamask-agent-wallet/references/signing.md size: 2869 sha: 34f2e5a87ff74e175e8177dd00d475f6f338b9cd upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/signing.md ````text # 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 --chain-id [--wait] [--password ] [--wallet-timeout ] ``` ### 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 --payload '' [--wait] [--password ] [--wallet-timeout ] ``` ### 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. ```` ## File: skills/metamask-agent-wallet/references/swap.md size: 14050 sha: 04a9f04ecdd45238bade428f63050bb8e71f3e0b upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/swap.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/swap.md ## File: skills/metamask-agent-wallet/references/transaction.md size: 2615 sha: bd2d68da51c35b5dd89f12426d3cf9532f54cbce upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/transaction.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/transaction.md ## File: skills/metamask-agent-wallet/references/transfer.md size: 2413 sha: 85f16830a5d9b11ceb722c3d17aa997d03eb46b1 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/transfer.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/transfer.md ## File: skills/metamask-agent-wallet/references/tx-history.md size: 3532 sha: 13d220cc8c02773faff792169d7b5e8f91bca709 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/tx-history.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/tx-history.md ## File: skills/metamask-agent-wallet/references/wallet.md size: 9390 sha: c0a78f384e4098f2fa7f747546fa0a9253fbc6d4 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/wallet.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/wallet.md ## File: skills/metamask-agent-wallet/references/x402.md size: 10829 sha: 3c373e71bd8b45cd67c4ac5bfa501c8a2d11b71a upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/x402.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/references/x402.md ## File: skills/metamask-agent-wallet/workflows/bridge.md size: 4819 sha: 295f24299ea82255a76da2c2b859438041312de2 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/bridge.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/bridge.md ## File: skills/metamask-agent-wallet/workflows/earn-supply.md size: 2269 sha: d29d2baba1ad9dd4119d8c7c9beb8a38f3312eef upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/earn-supply.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/earn-supply.md ## File: skills/metamask-agent-wallet/workflows/earn-withdraw.md size: 1484 sha: 2deae441c151f9ccd1f32fb876695a681c839d87 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/earn-withdraw.md ````text # 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. ```` ## File: skills/metamask-agent-wallet/workflows/login.md size: 978 sha: 9d7622089b01a78df7452b849f9368f8935c788f upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/login.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/login.md ## File: skills/metamask-agent-wallet/workflows/market-data.md size: 3720 sha: cabef2982e301f1aec72997744c0fce10b1c8534 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/market-data.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/market-data.md ## File: skills/metamask-agent-wallet/workflows/onboarding.md size: 3636 sha: 816f70eacf03df4aedc96d463a1c084843d7d1a1 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/onboarding.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/onboarding.md ## File: skills/metamask-agent-wallet/workflows/perps-close-position.md size: 1020 sha: 8aa26ec13055aaa5f723f17c45cf5e34f6a38d9f upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/perps-close-position.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/perps-close-position.md ## File: skills/metamask-agent-wallet/workflows/perps-modify-position.md size: 1051 sha: 3f28f06c1262ebca1f02a6adb41813569fb71b85 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/perps-modify-position.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/perps-modify-position.md ## File: skills/metamask-agent-wallet/workflows/perps-open-position.md size: 2870 sha: ef2ea6743c3b786d0dedfa61ddc2f782266bcd31 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/perps-open-position.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/perps-open-position.md ## File: skills/metamask-agent-wallet/workflows/predict-funding.md size: 2771 sha: 58e8d6e999cacc62efbf254916e861344eecdfdb upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-funding.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-funding.md ## File: skills/metamask-agent-wallet/workflows/predict-history.md size: 2245 sha: bde2c008ab4f16e258d9323b9368c7e41ada4a86 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-history.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-history.md ## File: skills/metamask-agent-wallet/workflows/predict-manage-orders.md size: 935 sha: 5fd10d749f04b45eb8ec6469f8161bfbe202b360 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-manage-orders.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-manage-orders.md ## File: skills/metamask-agent-wallet/workflows/predict-markets.md size: 1313 sha: c220aa128a7bfafdae9922f2603c73177ed4cd04 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-markets.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-markets.md ## File: skills/metamask-agent-wallet/workflows/predict-place-order.md size: 2312 sha: 4305eb573c236c70cc63b5c7809071fe6300b9b6 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-place-order.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-place-order.md ## File: skills/metamask-agent-wallet/workflows/predict-portfolio.md size: 900 sha: b64ede075ee83b1268b40b11cb864103d98bb6d7 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-portfolio.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-portfolio.md ## File: skills/metamask-agent-wallet/workflows/predict-setup.md size: 1330 sha: d442ae33d42f45eb963a9ca4fbefaa6c046d0a85 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-setup.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/predict-setup.md ## File: skills/metamask-agent-wallet/workflows/swap.md size: 4211 sha: 36bdb07f21719ad9be568d3696c346ce40ea4afe upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/swap.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/swap.md ## File: skills/metamask-agent-wallet/workflows/troubleshooting.md size: 8801 sha: a19ee9a60beb9c520464443577ac665724ddd39a upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/troubleshooting.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/troubleshooting.md ## File: skills/metamask-agent-wallet/workflows/x402-mcp.md size: 2989 sha: 45e2f06b4e5935825e48c03efb3c63c37fc8ebd5 upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/x402-mcp.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/x402-mcp.md ## File: skills/metamask-agent-wallet/workflows/x402-pay.md size: 2919 sha: eedda9a3b8e265731c23b0515d2273f26deec74c upstream: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/x402-pay.md Content is not inlined in the catalog. Read the upstream file: https://github.com/metamask/agent-skills/blob/main/skills/metamask-agent-wallet/workflows/x402-pay.md ## File: README.md upstream: https://github.com/metamask/agent-skills/blob/main/README.md ````text # MetaMask Agent CLI Skills SKILLs for the MetaMask Agent CLI (`@metamask/agent-wallet` v7.3.0). These skills enable AI agents to authenticate, manage wallets, swap tokens, bridge across chains, trade perpetual futures, earn yield on DeFi vaults, and more using the MetaMask Agent Wallet CLI (`mm`). This repository is also packaged as a **plugin** for Claude Code, Cursor, Codex, Antigravity CLI (`agy`), and Grok Build. The plugin ships the same skills plus a session-start hook that checks CLI readiness via `mm doctor` and records local install attribution. ## Skills | Skill | Description | | --- | --- | | [`metamask-agent-wallet`](./skills/metamask-agent-wallet/SKILL.md) | Full CLI skill that routes the agent to topic-specific reference docs (`references/`) for all MetaMask Agent CLI commands — auth, wallets, transfers, signing, swaps, bridges, perps, prediction markets, DeFi earn/yield vaults, market data, x402 payments, and calldata decoding — plus multistep workflow templates (`workflows/`) for onboarding, swaps, bridges, perps, prediction markets, and earn. | ## Install as a plugin (recommended) ### Claude Code ```bash claude plugin marketplace add MetaMask/agent-skills claude plugin install metamask-agent-wallet@metamask ``` Or use `/plugin` → Discover / Install inside Claude Code. Local development: ```bash claude --plugin-dir /path/to/agent-skills ``` ### Cursor 1. Open **Customize → Plugins**. 2. Add from Git: `https://github.com/MetaMask/agent-skills`. 3. Enable **metamask-agent-wallet**. Or submit/browse via the [Cursor Marketplace](https://cursor.com/marketplace) once listed. ### Codex ```bash codex plugin marketplace add MetaMask/agent-skills codex plugin add metamask-agent-wallet@metamask ``` Or use `/plugins` inside Codex. Local development: ```bash codex plugin marketplace add /path/to/agent-skills codex plugin add metamask-agent-wallet@metamask ``` Codex skips plugin-bundled hooks until you review and trust them. After that, a new session injects MetaMask readiness context the same way as Claude Code and Cursor. ### Antigravity CLI (`agy`) Install the repo root so skills and session-start hooks resolve: ```bash agy plugin install /path/to/agent-skills agy plugin install https://github.com/MetaMask/agent-skills ``` The slim `.antigravity-plugin/` directory (rules only) is for validation; prefer the repo root so `skills/` and `hooks/session-start.sh` are on the plugin path. Restart `agy` after install, then `agy plugin list`. The extension rule routes wallet work to `skills/metamask-agent-wallet/SKILL.md`. ### Grok Build Install the repo directly (recommended): ```bash grok plugin install MetaMask/agent-skills --trust ``` Local development: ```bash grok plugin install /path/to/agent-skills --trust ``` Optional marketplace (for browsing; install by repo path if name lookup fails): ```bash grok plugin marketplace add MetaMask/agent-skills grok plugin marketplace add /path/to/agent-skills ``` Grok skips plugin-bundled hooks, MCP servers, and skills until you trust the plugin (`--trust`). After that, a new session injects MetaMask readiness context the same way as Claude Code and Cursor. To pick up a newly installed plugin, press `r` in the Plugins tab or start a new session. ### Skills CLI (legacy / non-plugin hosts) ```bash npx skills add MetaMask/agent-skills ``` Select any one of the SKILLs upon prompt. ## What the session-start hook does On every new (or resumed) agent session the hook: 1. Reads the pinned CLI version from `skills/metamask-agent-wallet/SKILL.md`. 2. Writes or updates `~/.metamask/attribution.json` with `{ installSource, pluginVersion, firstSeenAt, lastSeenAt }` so analytics can attribute acquisition to this plugin. **No email or personal identity is stored.** 3. If `mm` is on `PATH`, runs `mm doctor --json` (≈15s timeout) and injects a short readiness summary into the session context (install / upgrade / login / init hints). 4. If `mm` is missing, injects guidance to **ask the user** before running `npm install -g @metamask/agent-wallet@`. The hook **never** installs or upgrades the CLI itself. It always exits `0` and never blocks the session. ## CLI install and updates The plugin does not bundle `mm`. After the agent asks and the user consents: ```bash npm install -g @metamask/agent-wallet@latest # or pin to the skill's cliVersion, e.g.: npm install -g @metamask/agent-wallet@7.3.0 ``` Requires a supported Node.js version. Then complete onboarding with `mm login` and `mm init` (see the skill workflows). When the skill's `cliVersion` advances, the next session-start context (or `mm doctor`) will prompt an upgrade the same way. ## Privacy | Data | Where | Purpose | | --- | --- | --- | | `installSource`, `pluginVersion`, timestamps | `~/.metamask/attribution.json` (mode `0600`) | First-touch acquisition channel for MetaMask product analytics after the user runs `mm` | | Host env (`CLAUDECODE`, `CURSOR_AGENT`, `CODEX_THREAD_ID`, `ANTIGRAVITY_AGENT`, `GROK_PLUGIN_ROOT`, …) | Read by `mm` at command time | Tag Segment events with the calling agent host | | Cursor `user_email` / other PII from hooks | **Not written** | — | Product analytics from the CLI respect `MM_TELEMETRY_DISABLED=1`, `DO_NOT_TRACK=1`, and dashboard Osano consent. ## Release coupling When `@metamask/agent-wallet` ships a new `major.minor`: 1. Bump `metadata.cliVersion` (and `metadata.version`) in `skills/metamask-agent-wallet/SKILL.md`. 2. Bump `version` in `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.cursor-plugin/plugin.json`, `.codex-plugin/plugin.json`, `.grok-plugin/plugin.json`, `.grok-plugin/marketplace.json`, and root `plugin.json`. 3. Ship one PR; Claude Code, Cursor, Codex, Antigravity CLI, and Grok Build auto-pull plugin updates from Git. Do **not** rename the plugin `name` (`metamask-agent-wallet`) after marketplace listing — it is an immutable slug. ## Repository layout ```text . ├── plugin.json # Agent Plugins 1.0 (skills only) ├── hooks.json # Cursor sessionStart ├── .claude-plugin/ │ ├── plugin.json │ └── marketplace.json ├── .cursor-plugin/ │ └── plugin.json ├── .codex-plugin/ │ └── plugin.json ├── .antigravity-plugin/ # Antigravity CLI (`agy`) │ ├── plugin.json │ ├── hooks.json │ └── rules/ ├── .grok-plugin/ # Grok Build │ ├── plugin.json │ └── marketplace.json ├── .agents/plugins/ │ └── marketplace.json # Codex / ChatGPT repo marketplace ├── hooks/ │ ├── hooks.json # Claude SessionStart │ ├── codex-hooks.json # Codex SessionStart │ ├── antigravity-hooks.json # Antigravity repo-root SessionStart │ ├── grok-hooks.json # Grok Build SessionStart │ └── session-start.sh └── skills/ ├── metamask-agent-wallet/ └── metamask-agent-workflows/ ``` ## License [MIT](./LICENSE) ## Marketplace listing See [docs/MARKETPLACE_SUBMISSION.md](./docs/MARKETPLACE_SUBMISSION.md) for Claude Code, Cursor, Codex, Antigravity CLI, and Grok Build submission steps (human review required after this repo is pushed). ````