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, 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 |
| Login in MetaMask Agentic CLI |
mm login |
auth.md |
| Choose a wallet mode and set up policies |
mm init |
auth.md |
| Show current init settings |
mm init show |
auth.md |
| Sign in via QR code with MetaMask Mobile |
mm login qr |
auth.md |
| Sign in via browser (Google or Email) |
mm login browser |
auth.md |
| Sign out |
mm logout |
auth.md |
| Reset CLI session |
mm reset |
auth.md |
| Show CLI configuration |
mm config get |
auth.md |
| Set CLI configuration |
mm config set |
auth.md |
| Set BYOK mnemonic encryption password |
mm wallet password set |
auth.md |
| Change BYOK mnemonic encryption password |
mm wallet password change |
auth.md |
| Remove BYOK mnemonic encryption password |
mm wallet password remove |
auth.md |
| Interpret raw CLI error codes |
AuthError, ValidationError, WALLET_ERROR |
errors.md |
| Inspect CLI, skills, environment, and session health |
mm doctor |
doctor.md |
| Decode EVM calldata into a human-readable intent |
mm decode |
decode.md |
| Create a wallet |
mm wallet create |
wallet.md |
| List all wallets |
mm wallet list |
wallet.md |
| Switch active wallet |
mm wallet select |
wallet.md |
| Show active wallet details |
mm wallet show |
wallet.md |
| Show active wallet address |
mm wallet address |
wallet.md |
| Check the active wallet balance |
mm wallet balance |
wallet.md |
| Show a QR code and address to fund the active wallet |
mm wallet add-fund |
wallet.md |
| Show current trading mode |
mm wallet trading-mode get |
wallet.md |
| Set trading mode to guard or beast |
mm wallet trading-mode set |
wallet.md |
| View wallet policy |
mm wallet policy get |
wallet.md |
| Set wallet policy |
mm wallet policy set |
wallet.md |
| Show project policy template |
mm wallet policy template |
wallet.md |
| Sign a plaintext message |
mm wallet sign-message |
signing.md |
| Sign EIP-712 typed data |
mm wallet sign-typed-data |
signing.md |
| Send a raw EVM transaction |
mm wallet send-transaction |
transaction.md |
| Transfer native tokens or ERC-20 tokens |
mm transfer |
transfer.md |
| List supported chains by the CLI |
mm chains list |
chain.md |
| List pending wallet requests |
mm wallet requests list |
polling.md |
| Watch a wallet polling id |
mm wallet requests watch |
polling.md |
| Query spot or historical prices |
mm price ... |
market-data.md |
| Discover tokens, token networks, or token metadata |
mm token ... |
market-data.md |
| List perpetual markets |
mm perps markets |
perps.md |
| Check perps account balance |
mm perps balance |
perps.md |
| List open perpetual positions |
mm perps positions |
perps.md |
| Get a quote for a perpetual order |
mm perps quote |
perps.md |
| List resting perpetual orders |
mm perps orders |
perps.md |
| Open a perpetual position |
mm perps open |
perps.md |
| Close a perpetual position |
mm perps close |
perps.md |
| Modify leverage, take-profit, or stop-loss |
mm perps modify |
perps.md |
| Cancel a resting perps order |
mm perps cancel |
perps.md |
| Deposit USDC into a perps venue |
mm perps deposit |
perps.md |
| Withdraw USDC from a perps venue |
mm perps withdraw |
perps.md |
| Transfer USDC between spot and perp accounts |
mm perps transfer |
perps.md |
| List perpetual futures venues |
mm perps list-venues |
perps.md |
| List available DEXs for a venue |
mm perps dexs |
perps.md |
| Set Predict trading mode |
mm predict mode |
predict.md |
| One-time Predict setup |
mm predict setup |
predict.md |
| Create or refresh Predict credentials |
mm predict auth |
predict.md |
| Repair Predict approvals |
mm predict approve |
predict.md |
| Check Predict back-end status and account setup |
mm predict status |
predict.md |
| Check if Polymarket is geoblocked for your IP |
mm predict geoblock |
predict.md |
| List prediction markets |
mm predict markets list |
predict.md |
| Search prediction markets |
mm predict markets search |
predict.md |
| Inspect a prediction market |
mm predict markets get |
predict.md |
| List Polymarket events |
mm predict events list |
predict.md |
| Inspect a Polymarket event |
mm predict events get |
predict.md |
| List Polymarket event series |
mm predict series list |
predict.md |
| Inspect a Polymarket event series |
mm predict series get |
predict.md |
| List Polymarket tags |
mm predict tags list |
predict.md |
| Inspect a Polymarket tag |
mm predict tags get |
predict.md |
| Preview a prediction order cost |
mm predict quote |
predict.md |
| Place a prediction market order |
mm predict place |
predict.md |
| Cancel prediction orders |
mm predict cancel |
predict.md |
| View prediction market positions |
mm predict positions |
predict.md |
| View open prediction orders |
mm predict orders |
predict.md |
| Show full Predict portfolio snapshot |
mm predict portfolio |
predict.md |
| List redeemable winning positions |
mm predict redeem list |
predict.md |
| Redeem winning positions |
mm predict redeem |
predict.md |
| Check Predict deposit wallet balance |
mm predict balance |
predict.md |
| Fund Predict deposit wallet |
mm predict deposit |
predict.md |
| Withdraw pUSD from Predict deposit wallet |
mm predict withdraw |
predict.md |
| Fetch prediction order book |
mm predict book |
predict.md |
| Watch a Predict job |
mm predict watch |
predict.md |
| List Predict trade or redeem history |
mm predict history |
predict.md |
| Inspect Predict history for a specific market |
mm predict history get |
predict.md |
| Look up a transaction by hash |
mm tx |
tx-history.md |
| List recent transactions for the active wallet |
mm tx history |
tx-history.md |
| Get a swap or bridge quote |
mm swap quote |
swap.md |
| Execute a token swap or bridge |
mm swap execute |
swap.md |
| Check swap or bridge status |
mm swap status |
swap.md |
| Bridge tokens to another chain |
mm swap execute |
swap.md |
Pay an HTTP 402 / x402 paywalled request |
python3 scripts/x402_pay.py |
x402.md |
| Pay an x402-gated MCP tool call |
python3 scripts/x402_pay.py |
x402.md |
| List earn vaults and APYs |
mm earn markets |
earn.md |
| View earn vault positions |
mm earn positions |
earn.md |
| Supply tokens to an earn vault |
mm earn supply |
earn.md |
| Withdraw tokens from an earn vault |
mm earn withdraw |
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 |
| Login flow |
login.md |
| Troubleshooting decision tree |
troubleshooting.md |
| Swap quote-review-execute flow |
swap.md |
| Bridge quote-review-execute flow |
bridge.md |
| Open a perpetual position flow |
perps-open-position.md |
| Close a perpetual position flow |
perps-close-position.md |
| Modify a perpetual position flow |
perps-modify-position.md |
| Predict first-time setup and credentials |
predict-setup.md |
| Deposit or withdraw pUSD from Predict wallet |
predict-funding.md |
| Search and browse prediction markets |
predict-markets.md |
| Quote and place a prediction order |
predict-place-order.md |
| View or cancel Predict orders and positions |
predict-manage-orders.md |
| View Predict portfolio and redeem winnings |
predict-portfolio.md |
| View Predict trade and redeem history |
predict-history.md |
| Token discovery, prices, and market data |
market-data.md |
| Supply tokens to earn yield |
earn-supply.md |
| Withdraw tokens from an earn vault |
earn-withdraw.md |
Pay an HTTP 402 (x402) paywalled request |
x402-pay.md |
| Pay an x402-gated MCP tool call |
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.
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 v6.1.5, 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:
mm --version
The installed version is the value after @metamask/agent-wallet/, such as @metamask/agent-wallet/6.1.4 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):
npm view @metamask/agent-wallet version
If the installed major.minor differs from the pinned cliVersion, or the installed version is behind the latest release, warn the user once and continue:
Version mismatch: installed CLI <installed>, this skill targets <cliVersion>, latest release is <latest>. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with npm install -g @metamask/agent-wallet@latest, then re-install the skills with npx skills add metaMask/agent-skills.
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:
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 |
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 decimal such as 0.01 or 1. Must match ^\d+\.?\d*$ and be positive |
--venue |
Must be hyperliquid |
--side for perps |
Must be long or short |
--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. |
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 |
| Perps deposit/withdraw |
Always confirm amount, asset, venue, network, and destination where applicable 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 |
| 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 |
May execute without confirmation, except reset which requires explicit user confirmation |
| Read-only queries |
May execute without confirmation |
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.
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:
- Prefer
--wait to block until complete.
- If not using
--wait, inform the user of the pollingId and how to track it:
mm wallet requests listmm wallet requests watch <polling-id>
- 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:
- Treat the command as waiting for user approval, not failed, hung, or complete.
- Surface the human instruction from the notice to the user.
- If a
pollingId is present in the notice or command output, tell the user they can track completion with mm wallet requests watch <polling-id>.
- Do not retry the same wallet operation while the job is still pending.
- On
mm swap execute with --no-wait, an MFA pause may return EXECUTE_FAILED with a message naming the approval wait and the watch command — that is still an MFA pause, not a missing hash.
For approval surfaces and recovery steps, see troubleshooting.md.
Output Rules
- Route silently. Do not announce which reference you are loading.
- Surface errors from commands verbatim. Do not mask or reword them.
- If a command fails, check
mm <command> --help and guide from there.
1---2name: metamask-agent-wallet3description: Use when the user asks anything about blockchain wallets, transactions, signing, token transfers, supported chains, wallet balances, perpetual futures trading, prediction markets, token swaps, cross-chain bridges, market data, token discovery, decoding EVM calldata, DeFi earn/yield vaults, 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.4license: MIT5---6
7# MetaMask Agentic CLI Skill
8
9This 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, perpetual futures trading, prediction market trading, prediction trade/redeem history, token swaps, cross-chain bridges, DeFi earn/yield vaults, and EVM calldata decoding.
10
11Use the routing table to select the relevant reference file. CLI behavior lives in `references/`. Repeatable operational patterns live in `workflows/`.
12
13## Command Routing
14
15Match 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.
16
17| User Intent | Command | Reference |
18| --- | --- | --- |
19| Check authentication status | `mm auth status` | [auth.md](references/auth.md) |
20| Login in MetaMask Agentic CLI | `mm login` | [auth.md](references/auth.md) |
21| Choose a wallet mode and set up policies | `mm init` | [auth.md](references/auth.md) |
22| Show current init settings | `mm init show` | [auth.md](references/auth.md) |
23| Sign in via QR code with MetaMask Mobile | `mm login qr` | [auth.md](references/auth.md) |
24| Sign in via browser (Google or Email) | `mm login browser` | [auth.md](references/auth.md) |
25| Sign out | `mm logout` | [auth.md](references/auth.md) |
26| Reset CLI session | `mm reset` | [auth.md](references/auth.md) |
27| Show CLI configuration | `mm config get` | [auth.md](references/auth.md) |
28| Set CLI configuration | `mm config set` | [auth.md](references/auth.md) |
29| Set BYOK mnemonic encryption password | `mm wallet password set` | [auth.md](references/auth.md) |
30| Change BYOK mnemonic encryption password | `mm wallet password change` | [auth.md](references/auth.md) |
31| Remove BYOK mnemonic encryption password | `mm wallet password remove` | [auth.md](references/auth.md) |
32| Interpret raw CLI error codes | `AuthError`, `ValidationError`, `WALLET_ERROR` | [errors.md](references/errors.md) |
33| Inspect CLI, skills, environment, and session health | `mm doctor` | [doctor.md](references/doctor.md) |
34| Decode EVM calldata into a human-readable intent | `mm decode` | [decode.md](references/decode.md) |
35| Create a wallet | `mm wallet create` | [wallet.md](references/wallet.md) |
36| List all wallets | `mm wallet list` | [wallet.md](references/wallet.md) |
37| Switch active wallet | `mm wallet select` | [wallet.md](references/wallet.md) |
38| Show active wallet details | `mm wallet show` | [wallet.md](references/wallet.md) |
39| Show active wallet address | `mm wallet address` | [wallet.md](references/wallet.md) |
40| Check the active wallet balance | `mm wallet balance` | [wallet.md](references/wallet.md) |
41| Show a QR code and address to fund the active wallet | `mm wallet add-fund` | [wallet.md](references/wallet.md) |
42| Show current trading mode | `mm wallet trading-mode get` | [wallet.md](references/wallet.md) |
43| Set trading mode to guard or beast | `mm wallet trading-mode set` | [wallet.md](references/wallet.md) |
44| View wallet policy | `mm wallet policy get` | [wallet.md](references/wallet.md) |
45| Set wallet policy | `mm wallet policy set` | [wallet.md](references/wallet.md) |
46| Show project policy template | `mm wallet policy template` | [wallet.md](references/wallet.md) |
47| Sign a plaintext message | `mm wallet sign-message` | [signing.md](references/signing.md) |
48| Sign EIP-712 typed data | `mm wallet sign-typed-data` | [signing.md](references/signing.md) |
49| Send a raw EVM transaction | `mm wallet send-transaction` | [transaction.md](references/transaction.md) |
50| Transfer native tokens or ERC-20 tokens | `mm transfer` | [transfer.md](references/transfer.md) |
51| List supported chains by the CLI | `mm chains list` | [chain.md](references/chain.md) |
52| List pending wallet requests | `mm wallet requests list` | [polling.md](references/polling.md) |
53| Watch a wallet polling id | `mm wallet requests watch` | [polling.md](references/polling.md) |
54| Query spot or historical prices | `mm price ...` | [market-data.md](references/market-data.md) |
55| Discover tokens, token networks, or token metadata | `mm token ...` | [market-data.md](references/market-data.md) |
56| List perpetual markets | `mm perps markets` | [perps.md](references/perps.md) |
57| Check perps account balance | `mm perps balance` | [perps.md](references/perps.md) |
58| List open perpetual positions | `mm perps positions` | [perps.md](references/perps.md) |
59| Get a quote for a perpetual order | `mm perps quote` | [perps.md](references/perps.md) |
60| List resting perpetual orders | `mm perps orders` | [perps.md](references/perps.md) |
61| Open a perpetual position | `mm perps open` | [perps.md](references/perps.md) |
62| Close a perpetual position | `mm perps close` | [perps.md](references/perps.md) |
63| Modify leverage, take-profit, or stop-loss | `mm perps modify` | [perps.md](references/perps.md) |
64| Cancel a resting perps order | `mm perps cancel` | [perps.md](references/perps.md) |
65| Deposit USDC into a perps venue | `mm perps deposit` | [perps.md](references/perps.md) |
66| Withdraw USDC from a perps venue | `mm perps withdraw` | [perps.md](references/perps.md) |
67| Transfer USDC between spot and perp accounts | `mm perps transfer` | [perps.md](references/perps.md) |
68| List perpetual futures venues | `mm perps list-venues` | [perps.md](references/perps.md) |
69| List available DEXs for a venue | `mm perps dexs` | [perps.md](references/perps.md) |
70| Set Predict trading mode | `mm predict mode` | [predict.md](references/predict.md) |
71| One-time Predict setup | `mm predict setup` | [predict.md](references/predict.md) |
72| Create or refresh Predict credentials | `mm predict auth` | [predict.md](references/predict.md) |
73| Repair Predict approvals | `mm predict approve` | [predict.md](references/predict.md) |
74| Check Predict back-end status and account setup | `mm predict status` | [predict.md](references/predict.md) |
75| Check if Polymarket is geoblocked for your IP | `mm predict geoblock` | [predict.md](references/predict.md) |
76| List prediction markets | `mm predict markets list` | [predict.md](references/predict.md) |
77| Search prediction markets | `mm predict markets search` | [predict.md](references/predict.md) |
78| Inspect a prediction market | `mm predict markets get` | [predict.md](references/predict.md) |
79| List Polymarket events | `mm predict events list` | [predict.md](references/predict.md) |
80| Inspect a Polymarket event | `mm predict events get` | [predict.md](references/predict.md) |
81| List Polymarket event series | `mm predict series list` | [predict.md](references/predict.md) |
82| Inspect a Polymarket event series | `mm predict series get` | [predict.md](references/predict.md) |
83| List Polymarket tags | `mm predict tags list` | [predict.md](references/predict.md) |
84| Inspect a Polymarket tag | `mm predict tags get` | [predict.md](references/predict.md) |
85| Preview a prediction order cost | `mm predict quote` | [predict.md](references/predict.md) |
86| Place a prediction market order | `mm predict place` | [predict.md](references/predict.md) |
87| Cancel prediction orders | `mm predict cancel` | [predict.md](references/predict.md) |
88| View prediction market positions | `mm predict positions` | [predict.md](references/predict.md) |
89| View open prediction orders | `mm predict orders` | [predict.md](references/predict.md) |
90| Show full Predict portfolio snapshot | `mm predict portfolio` | [predict.md](references/predict.md) |
91| List redeemable winning positions | `mm predict redeem list` | [predict.md](references/predict.md) |
92| Redeem winning positions | `mm predict redeem` | [predict.md](references/predict.md) |
93| Check Predict deposit wallet balance | `mm predict balance` | [predict.md](references/predict.md) |
94| Fund Predict deposit wallet | `mm predict deposit` | [predict.md](references/predict.md) |
95| Withdraw pUSD from Predict deposit wallet | `mm predict withdraw` | [predict.md](references/predict.md) |
96| Fetch prediction order book | `mm predict book` | [predict.md](references/predict.md) |
97| Watch a Predict job | `mm predict watch` | [predict.md](references/predict.md) |
98| List Predict trade or redeem history | `mm predict history` | [predict.md](references/predict.md) |
99| Inspect Predict history for a specific market | `mm predict history get` | [predict.md](references/predict.md) |
100| Look up a transaction by hash | `mm tx` | [tx-history.md](references/tx-history.md) |
101| List recent transactions for the active wallet | `mm tx history` | [tx-history.md](references/tx-history.md) |
102| Get a swap or bridge quote | `mm swap quote` | [swap.md](references/swap.md) |
103| Execute a token swap or bridge | `mm swap execute` | [swap.md](references/swap.md) |
104| Check swap or bridge status | `mm swap status` | [swap.md](references/swap.md) |
105| Bridge tokens to another chain | `mm swap execute` | [swap.md](references/swap.md) |
106| Pay an HTTP `402` / x402 paywalled request | `python3 scripts/x402_pay.py` | [x402.md](references/x402.md) |
107| Pay an x402-gated MCP tool call | `python3 scripts/x402_pay.py` | [x402.md](references/x402.md) |
108| List earn vaults and APYs | `mm earn markets` | [earn.md](references/earn.md) |
109| View earn vault positions | `mm earn positions` | [earn.md](references/earn.md) |
110| Supply tokens to an earn vault | `mm earn supply` | [earn.md](references/earn.md) |
111| Withdraw tokens from an earn vault | `mm earn withdraw` | [earn.md](references/earn.md) |
112
113## Workflows
114
115CLI 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.
116
117| Pattern | Workflow |
118| --- | --- |
119| First time setup and onboarding | [onboarding.md](workflows/onboarding.md) |
120| Login flow | [login.md](workflows/login.md) |
121| Troubleshooting decision tree | [troubleshooting.md](workflows/troubleshooting.md) |
122| Swap quote-review-execute flow | [swap.md](workflows/swap.md) |
123| Bridge quote-review-execute flow | [bridge.md](workflows/bridge.md) |
124| Open a perpetual position flow | [perps-open-position.md](workflows/perps-open-position.md) |
125| Close a perpetual position flow | [perps-close-position.md](workflows/perps-close-position.md) |
126| Modify a perpetual position flow | [perps-modify-position.md](workflows/perps-modify-position.md) |
127| Predict first-time setup and credentials | [predict-setup.md](workflows/predict-setup.md) |
128| Deposit or withdraw pUSD from Predict wallet | [predict-funding.md](workflows/predict-funding.md) |
129| Search and browse prediction markets | [predict-markets.md](workflows/predict-markets.md) |
130| Quote and place a prediction order | [predict-place-order.md](workflows/predict-place-order.md) |
131| View or cancel Predict orders and positions | [predict-manage-orders.md](workflows/predict-manage-orders.md) |
132| View Predict portfolio and redeem winnings | [predict-portfolio.md](workflows/predict-portfolio.md) |
133| View Predict trade and redeem history | [predict-history.md](workflows/predict-history.md) |
134| Token discovery, prices, and market data | [market-data.md](workflows/market-data.md) |
135| Supply tokens to earn yield | [earn-supply.md](workflows/earn-supply.md) |
136| Withdraw tokens from an earn vault | [earn-withdraw.md](workflows/earn-withdraw.md) |
137| Pay an HTTP `402` (x402) paywalled request | [x402-pay.md](workflows/x402-pay.md) |
138| Pay an x402-gated MCP tool call | [x402-mcp.md](workflows/x402-mcp.md) |
139
140## Global Flags
141
142Every `mm` command accepts these flags:
143
144| Flag | Short | Description |
145| --- | --- | --- |
146| `--format` | `-f` | Output format: `text`, `json`, or `toon`. Defaults to `text` in TTY, `json` when piped |
147| `--json` | | Shorthand for `--format=json` |
148| `--toon` | | Shorthand for `--format=toon` |
149| `--verbose` | `-v` | Show debug logs on stderr. Use for troubleshooting |
150
151Always use `--toon` for command output unless the user explicitly requests a different format.
152
153## Preflight
154
155Run these checks before the first CLI operation in a session, in order.
156
157### 1. Version compatibility
158
159
160This skill is written for `@metamask/agent-wallet` v6.1.5, 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:
161
162```bash
163mm --version
164```
165
166The installed version is the value after `@metamask/agent-wallet/`, such as `@metamask/agent-wallet/6.1.4 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):
167
168```bash
169npm view @metamask/agent-wallet version
170```
171
172If the installed `major.minor` differs from the pinned `cliVersion`, or the installed version is behind the latest release, warn the user once and continue:
173
174> Version mismatch: installed CLI `<installed>`, this skill targets `<cliVersion>`, latest release is `<latest>`. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with `npm install -g @metamask/agent-wallet@latest`, then re-install the skills with `npx skills add metaMask/agent-skills`.
175
176Run this check once per session. Do not block operations on it.
177
178### 2. Readiness gate — authentication and initialization
179
180`mm doctor` is the single readiness check. Run it before the first CLI operation in a session:
181
182```bash
183mm doctor
184```
185
186It 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.
187
188A 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.
189
190Remediate, then re-run `mm doctor` and confirm a clean result before doing anything else:
191
192- `authenticated: false` → follow `workflows/login.md`, or `workflows/onboarding.md` for first-time setup, to run `mm login`.
193- `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.
194
195## Safety Rules
196
197These rules apply to every operation, regardless of which reference or workflow is active.
198
199### Input Validation
200
201Before constructing any command, validate all user-provided values:
202
203| Flag | Validation rule |
204| --- | --- |
205| `--to`, `--address` | Must match `^0x[0-9a-fA-F]{40}$` |
206| `--amount` | Human-readable decimal such as 0.5 or 100. Must match `^\d+\.?\d*$`. Reject spaces, semicolons, pipes, backticks, or shell metacharacters |
207| `--chain-id` | Must be a positive integer (`^\d+$`) |
208| `--payload` for send-transaction | Must be valid JSON. No unescaped shell metacharacters outside the JSON structure |
209| `--payload` for decode | Must be 0x-prefixed hex calldata, matching `^0x[0-9a-fA-F]+$` |
210| `--token` | Must be a valid hex address or known symbol |
211| `--leverage` | Must be a positive integer (`^\d+$`) |
212| `--size` | Human-readable decimal such as 0.01 or 1. Must match `^\d+\.?\d*$` and be positive |
213| `--venue` | Must be `hyperliquid` |
214| `--side` for perps | Must be `long` or `short` |
215| `--order-id` | Must be a positive integer (`^\d+$`) |
216| `--token-id` | Must be a non-empty outcome token ID string |
217| `--price`, `--limit-price` | Must be a positive number in range `(0, 1]` |
218| `--order-type` | Must be one of `GTC`, `GTD`, `FOK`, `FAK` |
219| `--side` for predict | Must be `buy` or `sell` |
220| `--slippage` | Must be a number between 0 and 100 |
221| `--tick-size` | Must be one of `0.1`, `0.01`, `0.005`, `0.0025`, `0.001`, `0.0001` |
222| `--from-chain-id`, `--to-chain-id` | Must be a positive integer EVM chain ID |
223| `--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 |
224| `--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 |
225| `--strategy` | Comma-separated list from: `cost`, `speed`, `impact`, `output` |
226| `--wallet-timeout` | Must be a positive integer between 1 and 600 |
227| `--password` | Must be a non-empty string. Never log, display, or store the value. |
228| 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. |
229| x402 `payTo` / authorization `to` | Must match `^0x[0-9a-fA-F]{40}$` and equal the recipient in the `402` |
230| x402 `value` | Atomic-unit integer that exactly equals the offered amount. The `exact` scheme is not a maximum |
231| x402 resource URL | Must be `https://`. Reject a `402` reached via an unexpected cross-host redirect |
232| 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 |
233
234Do not pass unvalidated user input into any command.
235
236### Confirmation Requirements
237
238| Operation type | Confirmation rule |
239| --- | --- |
240| Transfers | Always confirm recipient, amount, token, and chain before executing |
241| Raw transactions | Always confirm transaction payload, chain, recipient, value, and calldata summary before executing |
242| Message signing | Always show exact message and chain before signing |
243| Typed-data signing | Always show domain, primary type, chain, verifying contract, and message summary before signing |
244| 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 |
245| 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. |
246| Perps trading | Always confirm symbol, side, size, leverage, venue, order type, and limit price if present before executing |
247| Perps deposit/withdraw | Always confirm amount, asset, venue, network, and destination where applicable before executing |
248| Predict trading | Always confirm token ID, side, size, price, order type, market, and outcome before executing |
249| Predict deposit | Always confirm amount before executing |
250| Predict withdraw | Always confirm amount and recipient before executing. `--to` defaults to owner EOA |
251| Predict redeem | Always confirm the target, either condition ID or `--all`, before executing. `--all` redeems every winning position |
252| Earn supply | Always confirm token, amount, chain, vault/protocol, and APY before executing. For cross-chain supply, also confirm source chain and source token |
253| Earn withdraw | Always confirm token, amount or full balance, chain, and vault/protocol before executing |
254| Cancel-all operations | Always confirm scope and exact destructive effect before executing |
255| Wallet policy changes | Broadening policy changes require MFA approval; non-broadening changes apply immediately |
256| Trading mode changes | Broadening from guard to beast requires MFA approval. Tightening from beast to guard applies immediately |
257| Auth / wallet management | May execute without confirmation, except `reset` which requires explicit user confirmation |
258| Read-only queries | May execute without confirmation |
259
260### Credential Safety
261
262- Never store, log, or display private keys, mnemonics, passwords, or auth tokens.
263- 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.
264
265### Suspicious Content Warnings
266
267Flag to the user before proceeding if a signing payload or transaction contains:
268
269- URLs or contract addresses the user did not provide
270- `permit`, `approve`, `setApprovalForAll`, or allowance-like fields
271- Unusually large values or unfamiliar contract interactions
272
273When 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).
274
275## Async Model
276
277In both server-wallet and BYOK mode, signing and transaction commands go through a job-polling loop and return a `pollingId`. Handle this consistently:
278
2791. Prefer `--wait` to block until complete.
2802. If not using `--wait`, inform the user of the `pollingId` and how to track it:
281 - `mm wallet requests list`
282 - `mm wallet requests watch <polling-id>`
2833. 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.
284
285Transfers, 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.
286
287## MFA Approval Pauses
288
289Wallet 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.
290
291| Output mode | How to detect |
292| --- | --- |
293| `--json` / piped stdout | An NDJSON line containing `"_notice":{"kind":"AWAITING_MFA",...}` |
294| Plain TTY or Ink REPL | A stdout line containing `[AWAITING_MFA]`, e.g. `⚠ [AWAITING_MFA] Approve in MetaMask mobile.` |
295
296When `AWAITING_MFA` appears:
297
2981. Treat the command as **waiting for user approval**, not failed, hung, or complete.
2992. Surface the human instruction from the notice to the user.
3003. If a `pollingId` is present in the notice or command output, tell the user they can track completion with `mm wallet requests watch <polling-id>`.
3014. Do **not** retry the same wallet operation while the job is still pending.
3025. On `mm swap execute` with `--no-wait`, an MFA pause may return `EXECUTE_FAILED` with a message naming the approval wait and the watch command — that is still an MFA pause, not a missing hash.
303
304For approval surfaces and recovery steps, see [troubleshooting.md](workflows/troubleshooting.md).
305
306## Output Rules
307
308- Route silently. Do not announce which reference you are loading.
309- Surface errors from commands verbatim. Do not mask or reword them.
310- If a command fails, check `mm <command> --help` and guide from there.
metamask