For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

Architecture

MetaMask Agent Wallet exposes wallet operations through the mm CLI, backed by the @metamask/agentic-sdk package. Security is applied by default on every signing and transaction path, backed by Transaction Protection.

Transactions through Agent Wallet deemed safe are guaranteed against loss up to $10,000.* See Transaction Shield for eligibility, coverage limits, and terms.

CLI and session​

  • Install @metamask/agentic-cli to get the mm binary.
  • Session data is stored at ~/.metamask/session.json with restricted file permissions.
  • Wallet metadata is stored at ~/.metamask/wallets.json. Predict state is stored at ~/.metamask/predict.json.
  • Run mm reset to clear local session state.

Wallet modes​

Choose a wallet mode during mm init. The CLI prompts interactively when you omit --wallet.

Server-wallet​

Keys are managed and secured server-side in a trusted execution environment (TEE), so agents can't access your main wallet. You retain self-custody.

Signing and transaction operations use an asynchronous model. Long-running operations return a pollingId unless you pass --wait.

Bring your own wallet​

You supply a BIP-39 mnemonic. Useful when you need local key control or an existing seed phrase. Operation results return immediately.

Never pass --mnemonic on the command line. Set the MM_MNEMONIC environment variable instead. Optionally encrypt the mnemonic at rest with MM_PASSWORD or mm wallet password set.

Transaction simulation​

Before a transaction executes, the CLI simulates it to surface reverts, unexpected state changes, and other failures early.

Threat scanning​

Threat scanning is powered by Blockaid and production-tested across millions of MetaMask transactions. Malicious transactions get auto-bounced. When a transaction is flagged, it requires your approval before it executes. You receive details in the CLI output and through the approval flow.

Transaction Protection​

Eligible transactions deemed safe are backed by Transaction Protection coverage up to $10,000/month. Transaction Shield is MetaMask's subscription that pairs Transaction Protection with priority support. See Transaction Shield for subscription details, eligibility, coverage limits, and terms.

Smart Transactions​

Smart Transactions optimize how your trades land onchain with fewer fails, better gas, and built-in MEV protection where supported on the target chain.

Trading modes​

Trading modes apply to server-wallet only. During mm init, you set outflow limits and allowlists, then choose a trading mode that defines how those policies are enforced. Choose during mm init with --mode or at the interactive prompt.

ModeCLI flagSummary
Guard Mode (Recommended)--mode guardDesigned for everyday traders. Transactions outside your policy limits require 2-factor authentication approval.
Beast Mode--mode beastDesigned for power users. Malicious transactions are still blocked and surfaced for 2-factor authentication approval.

Designed for everyday traders. Transactions outside your policy limits require 2-factor authentication approval.

Guardrails

  • Threat scanning
  • Network allowlist
  • Token recipient allowlist
  • Address allowlist
  • Outflow limit (rolling 24h)

Approval required for

  • Malicious transactions
  • Addresses or contracts not in allowlist
  • Networks not in allowlist
  • Recipients not in allowlist
  • Raising outflow limit

Beast Mode​

Designed for power users. Malicious transactions are still blocked and surfaced for 2-factor authentication approval.

Guardrails

  • Threat scanning

Approval required for

  • Malicious transactions
  • Risky contracts

When 2-factor authentication is required, the CLI pauses the job until you approve or reject it. Your sign-in method during mm login determines which channel the CLI uses:

Sign-in methodApproval channel
QR codeMetaMask Mobile push notification
Google or emailEmail link with transaction details

The agent cannot proceed without your approval on flagged or policy-violating transactions.

Switch modes by re-running mm init with a different --mode value. Confirm the active configuration with mm init show. See Trading modes.

Server-wallet async model​

When you submit a signing or transaction request in server-wallet mode:

  1. The CLI submits the request to the wallet service.
  2. The service may simulate the transaction, run threat scanning, and evaluate policies.
  3. If policy requires 2-factor authentication or threat scanning flags the transaction, the job enters an AWAITING_MFA state until you approve via MetaMask Mobile or email.
  4. The CLI returns a pollingId unless you pass --wait.

Track pending work:

mm wallet requests list
mm wallet requests watch --polling-id <POLLING_ID>

REPL vs headless​

  • REPL: Run mm with no arguments on a TTY for an interactive shell.
  • Headless: Pass flags explicitly or use --format json for machine-readable output in scripts and agents.

Next steps​

On this page