metamask-agent-wallet

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, prediction markets, token swaps, cross-chain bridges, market data, token discovery, decoding EVM calldata, Aave V3 lending and borrowing, or authentication via the MetaMask Agentic CLI. Single entry point for all mm CLI operations. license: MIT metadata: author: metamask version: "4.0.0" cliVersion: "3.0.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, perpetual futures trading, prediction market trading, token swaps, and cross-chain bridges.

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.

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.

Global Flags

Every mm command accepts these flags:

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/agentic-cli v3.0.0 (see cliVersion in the frontmatter). Check the installed version:

mm --version

The installed version is the value after @metamask/agentic-cli/ (e.g. @metamask/agentic-cli/2.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):

npm view @metamask/agentic-cli 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 is pinned to 3.0.0, latest release is <latest>. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with npm install -g @metamask/agentic-cli@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 + 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." (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 (and a trading mode for server-wallet).

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:

Do not pass unvalidated user input into any command.

Confirmation Requirements

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.

Server Wallet Async Model

In server-wallet mode, signing and transaction commands return a pollingId instead of an immediate result. 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 <id>
3. In BYOK mode, results are returned immediately. 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 (e.g. Transfer 0.5 ETH to 0x..., 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.

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.