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/agent-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/month.* See Transaction Shield for eligibility, coverage limits, and terms.

CLI and session​

  • Install @metamask/agent-wallet to get the mm binary.
  • Run mm doctor to verify CLI version, skill compatibility, authentication, and initialization before wallet operations.
  • 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. Requests are signed locally and then submitted as jobs, so operations can also return a pollingId unless you pass --wait.

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.

Gasless execution​

For ERC-20 transfers and swaps where the wallet's native balance cannot cover gas, the CLI automatically routes through a gasless relay using EIP-7702. The relay submits the transaction on your behalf and deducts fees from the transferred ERC-20 token automatically.

ERC-7821 batch execution​

On eligible chains and accounts, the CLI combines ERC-20 approval and trade into a single atomic execute() call using ERC-7821. This reduces the number of transactions and avoids approval front-running. The CLI falls back to sequential submission when batching is not available.

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.

Policy enforcement​

During mm init, you choose Guard Mode or Beast Mode to define how policies are enforced. See Trading modes for the guardrail and approval comparison, Outflow policy for rolling 24-hour limit details, and Switch modes and wallets to change 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 simulates the transaction, runs threat scanning, and evaluates your policies.
  3. If policy requires 2-factor authentication or threat scanning flags the transaction, the job enters an AWAITING_MFA state until you approve in the MetaMask Mobile notifications menu (QR sign-in) or through the approval email (browser sign-in). See Approve requests.
  4. The CLI returns a pollingId unless you pass --wait.

Track pending work:

mm wallet requests list
mm wallet requests watch <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