MetaMask Agent Wallet

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, 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.

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
List installed CLI plugins	mm plugins	plugins.md
Inspect an installed CLI plugin	mm plugins inspect	plugins.md
Install a CLI plugin	mm plugins install	plugins.md
Update a CLI plugin	mm plugins update	plugins.md
Uninstall a CLI plugin	mm plugins uninstall	plugins.md
Remove all user-installed CLI plugins	mm plugins reset	plugins.md
Link a local plugin directory for development	mm plugins link	plugins.md
Enable or disable the plugin beta	mm config set experimentalPlugins	plugins.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.

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.

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.0.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.0.0 darwin-arm64 node-v22.18.0. Compare its major.minor against the pinned cliVersion. Optionally check the latest published version (best-effort, skip silently on network failure):

bash

npm view @metamask/agent-wallet version

If the installed major.minor differs from the pinned cliVersion, or the installed version is behind the latest release, warn the user once and continue:

Version mismatch: installed CLI <installed>, this skill targets <cliVersion>, latest release is <latest>. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with npm install -g @metamask/agent-wallet@latest, then 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:

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	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
--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
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
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	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:

1. Prefer --wait to block until complete.
2. If not using --wait, inform the user of the pollingId and how to track it:
   • mm wallet requests list
   • mm wallet requests watch <polling-id>
3. In BYOK mode, the local key signs locally but the operation still produces a pending job and a pollingId. If the mnemonic is password-encrypted, the user must set MM_PASSWORD environment variable to unlock it for the operation.

Transfers, swaps, perps, predict orders, and predict withdraws attach a human-readable intent summary to their wallet request, such as Transfer 0.5 ETH to 0x... or Withdraw 10 pUSD to 0x.... When surfacing a pending request from wallet requests list or wallet requests watch, show the intent summary so the user can confirm what they are approving.

MFA Approval Pauses

Wallet jobs that need out-of-band MFA approval pause in AWAITING_MFA. Detect this pause by scanning command stdout for the literal token AWAITING_MFA. Do not infer MFA from free-text alone on older CLIs; from CLI v6.1.5 onward every output mode emits the token consistently.

Output mode	How to detect
--json / piped stdout	An NDJSON line containing "_notice":{"kind":"AWAITING_MFA",...}
Plain TTY or Ink REPL	A stdout line containing [AWAITING_MFA], e.g. ⚠ [AWAITING_MFA] Approve in MetaMask mobile.

When AWAITING_MFA appears:

1. Treat the command as waiting for user approval, not failed, hung, or complete.
2. Surface the human instruction from the notice to the user.
3. If a pollingId is present in the notice or command output, tell the user they can track completion with mm wallet requests watch <polling-id>.
4. Do not retry the same wallet operation while the job is still pending.
5. On mm swap execute, mm earn supply, or mm earn withdraw, an MFA pause with no hash yet may return EXECUTE_FAILED with a message naming the approval wait and mm wallet requests watch <polling-id> — that is still an MFA pause, not a missing hash.

For approval surfaces and recovery steps, see troubleshooting.md.

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.