> For the complete documentation index, see [llms.txt](/llms.txt).

# 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](https://support.metamask.io/manage-crypto/transactions/transaction-shield/)for eligibility, coverage limits, and terms.

## CLI and session[​](#cli-and-session "Direct link to 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[​](#wallet-modes "Direct link to Wallet modes")

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

### Server-wallet[​](#server-wallet "Direct link to 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[​](#bring-your-own-wallet "Direct link to 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[​](#transaction-simulation "Direct link to Transaction simulation")

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

## Threat scanning[​](#threat-scanning "Direct link to 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[​](#transaction-protection "Direct link to Transaction Protection")

Eligible transactions deemed safe are backed by Transaction Protection coverage up to $10,000/month. [Transaction Shield](https://support.metamask.io/manage-crypto/transactions/transaction-shield/) is MetaMask's subscription that pairs Transaction Protection with priority support. See [Transaction Shield](https://support.metamask.io/manage-crypto/transactions/transaction-shield/)for subscription details, eligibility, coverage limits, and terms.

## Smart Transactions[​](#smart-transactions "Direct link to Smart Transactions")

[Smart Transactions](https://support.metamask.io/manage-crypto/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 "Direct link to Trading modes")

Trading modes apply to server-wallet only. During `mm init`, you set allowlists and choose Guard Mode or Beast Mode to define how those policies are enforced. See [Trading modes](/agent-wallet/reference/trading-modes/) for the full guardrail and approval comparison.

## Server-wallet async model[​](#server-wallet-async-model "Direct link to 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-vs-headless "Direct link to 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[​](#next-steps "Direct link to Next steps")

- [Quickstart](/agent-wallet/quickstart/)
- [CLI commands](/agent-wallet/reference/commands/)