MetaMask · yashovardhan · Jun 8, 2026 · May 28, 2026 · Jun 8, 2026 · Jun 8, 2026
@@ -17,6 +17,7 @@ Every new documentation page must be added to the appropriate sidebar file:
 | MetaMask Connect     | `mm-connect-sidebar.js`  |
 | Embedded Wallets     | `ew-sidebar.js`          |
 | Smart Accounts Kit   | `gator-sidebar.js`       |
+| Agent Wallet         | `agent-wallet-sidebar.js` |
 | Services             | `services-sidebar.js`    |
 | Developer dashboard  | `dashboard-sidebar.js`   |
 | Snaps                | `snaps-sidebar.js`       |

@@ -0,0 +1,73 @@
+---
+description: Product-specific guidance for MetaMask Agent Wallet documentation, including terminology, CLI conventions, and content organization.
+globs: agent-wallet/**/*.md,agent-wallet/**/*.mdx
+alwaysApply: false
+---
+
+# Agent Wallet
+
+## Product naming
+
+- The product name is **MetaMask Agent Wallet**. Use **Agent Wallet** as short form in prose.
+- The CLI binary is `mm` (lowercase, monospace). Do not document `mm-dev` or `mm-uat` in user-facing docs.
+- The npm package is `@metamask/agentic-cli`.
+
+## Wallet and trading modes
+
+- **server-wallet** — private keys are held securely in a TEE-backed environment.
+- **Bring your own wallet** — user supplies a BIP-39 mnemonic. CLI flag: `byok`.
+- **Guard Mode (Recommended)** — trading mode (`--mode guard`). Designed for everyday traders. Enforces security check, network allowlist, token recipient allowlist, address allowlist, and rolling 24h outflow limit. 2-factor authentication on policy violations, malicious transactions, and raising outflow limit.
+- **Beast Mode** — trading mode (`--mode beast`). Designed for power users. Security check guardrail only. 2-factor authentication on malicious transactions and risky contracts.
+
+Users choose wallet and trading modes during interactive `mm init` or by prompting their agent.
+Mark Guard Mode as **Recommended**; do not describe modes as opt-in, default, or preferred in other ways.
+Sign-in method (QR, Google, or email) determines the 2FA approval channel (Mobile push vs email link).
+
+CLI flags use `server-wallet`, `byok`, `guard`, and `beast`.
+
+## Security terms
+
+Use these terms consistently when describing the security stack:
+
+- **Transaction Protection** — guarantee for transactions deemed safe (up to $10,000 loss coverage).
+  Frame as backing for "security by default," not as a standalone scanning feature. Link eligibility
+  and terms to
+  [Transaction Shield support](https://support.metamask.io/manage-crypto/transactions/transaction-shield/).
+- **Transaction Shield** — automated security checks for malicious contracts and scams. Link to
+  [Transaction Shield support](https://support.metamask.io/manage-crypto/transactions/transaction-shield/).
+  Do not lead with vendor names.
+- **Smart Transactions** — optimizes how trades land onchain (fewer fails, better gas, built-in MEV
+  protection). Link to
+  [Smart Transactions support](https://support.metamask.io/manage-crypto/transactions/smart-transactions/).
+  Do not use "Servo" in user-facing docs.
+- **Server wallet** / **TEE** — keys managed and secured server-side; agents can't access the user's
+  main wallet. Do not lead with vendor names.
+- **2FA** or **2-factor authentication** — human approval for flagged or policy-violating transactions. Do not use "MFA" in prose (CLI state `AWAITING_MFA` is acceptable in code references).
+
+Do not add comparative security claims beyond approved product copy.
+
+## Content organization
+
+| Folder           | Content type                                      |
+| ---------------- | ------------------------------------------------- |
+| Root (`README.mdx`, `quickstart.md`, `use-the-cli-directly.md`) | Overview, quickstart, headless CLI |
+| `guides/`        | Task-oriented how-to guides                       |
+| `reference/`     | Architecture, CLI commands, error codes, supported chains |
+| `troubleshooting/` | Symptom-based fixes (single page in v1)         |
+
+Do not paste content from `.agents/skills/metamask-agent-wallet/` into documentation pages.
+
+## Reference conventions
+
+- Command headings use backtick-wrapped names (for example, `## \`mm transfer\``).
+- Parameters use tables with columns: Flag, Required, Description.
+- Use `bash` fences for CLI examples.
+- Global flags: `--format`, `--json`, `--toon`, `--verbose`.
+
+## Sidebar
+
+The sidebar configuration is in [agent-wallet-sidebar.js](agent-wallet-sidebar.js).
+
+## Images
+
+Place product images in `static/img/agent-wallet/`.
@@ -22,6 +22,13 @@ listed on the right unless they appear in code, URLs, or direct quotations from
 | sign-in / sign-out (noun or adjective) | log-in, log-out, login, logout (as nouns/adj)                                   |
 | onchain / offchain                     | on-chain, off-chain                                                             |
 | Wallet Standard, Wallet Adapter        | wallet-standard, wallet-adapter (except in URLs)                                |
+| MetaMask Agent Wallet                  | Agentic CLI, Agentic Wallet (except in code/URLs where `agentic` appears)       |
+| Agent Wallet (short form)              | agent wallet (lowercase product name)                                           |
+| Guard Mode                             | guard mode (capitalize Mode)                                                    |
+| Beast Mode                             | beast mode (capitalize Mode)                                                    |
+| server-wallet                          | server wallet, Server Wallet (except as product phrase "server-wallet mode")    |
+| Bring your own wallet                  | BYOK, bring your own key, byok (except CLI flag `--wallet byok`)                |
+| `mm` (CLI binary)                      | MM, Mm (except at sentence start)                                               |
 
 ## Standards and specifications
 

@@ -1,19 +1,24 @@
 # MetaMask developer documentation
 
+<!-- vale off -->
+
 This repository contains the source for [docs.metamask.io](https://docs.metamask.io), the MetaMask
 developer documentation site. It is built with Docusaurus and covers multiple products aimed at
 dapp developers and wallet extension builders.
 
+<!-- vale on -->
+
 ## Products
 
-| Product             | Path                        | Sidebar file            | Description                                                                         |
-| ------------------- | --------------------------- | ----------------------- | ----------------------------------------------------------------------------------- |
-| MetaMask Connect    | `metamask-connect/`         | `mm-connect-sidebar.js` | Connect dapps to MetaMask extension and mobile, across EVM, Solana, and multichain. |
-| Embedded Wallets    | `embedded-wallets/`         | `ew-sidebar.js`         | Embed wallet functionality directly into applications.                              |
-| Smart Accounts Kit  | `smart-accounts-kit/`       | `gator-sidebar.js`      | Create smart accounts with delegated permissions, and request advanced permissions. |
-| Services            | `services/`                 | `services-sidebar.js`   | Ease dapp development using Infura and related infrastructure APIs.                 |
-| Snaps               | `snaps/`                    | `snaps-sidebar.js`      | Extend MetaMask by creating custom mini-apps.                                       |
-| Developer dashboard | `developer-tools/dashboard` | `dashboard-sidebar.js`  | Manage Infura API keys, monitor usage, and access account info.                     |
+| Product             | Path                        | Sidebar file              | Description                                                                         |
+| ------------------- | --------------------------- | ------------------------- | ----------------------------------------------------------------------------------- |
+| MetaMask Connect    | `metamask-connect/`         | `mm-connect-sidebar.js`   | Connect dapps to MetaMask extension and mobile, across EVM, Solana, and multichain. |
+| Embedded Wallets    | `embedded-wallets/`         | `ew-sidebar.js`           | Embed wallet functionality directly into applications.                              |
+| Smart Accounts Kit  | `smart-accounts-kit/`       | `gator-sidebar.js`        | Create smart accounts with delegated permissions, and request advanced permissions. |
+| Agent Wallet        | `agent-wallet/`             | `agent-wallet-sidebar.js` | Give AI agents programmatic wallet access via the `mm` CLI with mandatory security. |
+| Services            | `services/`                 | `services-sidebar.js`     | Ease dapp development using Infura and related infrastructure APIs.                 |
+| Snaps               | `snaps/`                    | `snaps-sidebar.js`        | Extend MetaMask by creating custom mini-apps.                                       |
+| Developer dashboard | `developer-tools/dashboard` | `dashboard-sidebar.js`    | Manage Infura API keys, monitor usage, and access account info.                     |
 
 ## Editorial standards
 
@@ -22,7 +27,9 @@ Follow these guides when writing or editing documentation:
 - [Consensys documentation style guide](https://docs-template.consensys.net/contribute/style-guide)
 - [Consensys Markdown formatting guide](https://docs-template.consensys.net/contribute/format-markdown)
 - [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
+<!-- vale off -->
 - [Diataxis framework](https://diataxis.fr/) for content structure
+<!-- vale on -->
 
 The rules under `.cursor/rules/` cover the most actionable parts of these references.
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution workflow.

@@ -0,0 +1,53 @@
+// @ts-check
+
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebar = {
+  agentWalletSidebar: [
+    {
+      type: 'doc',
+      label: 'Overview',
+      id: 'README',
+    },
+    {
+      type: 'doc',
+      label: 'Quickstart',
+      id: 'quickstart',
+    },
+    {
+      type: 'doc',
+      label: 'Use the CLI directly',
+      id: 'use-the-cli-directly',
+    },
+    {
+      type: 'category',
+      label: 'Guides',
+      collapsed: false,
+      items: [
+        'guides/send-tokens',
+        'guides/swap-and-bridge',
+        'guides/trade-perpetuals',
+        'guides/trade-prediction-markets',
+        'guides/check-balances-and-prices',
+        'guides/sign-messages-and-transactions',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Reference',
+      collapsed: true,
+      items: [
+        'reference/architecture',
+        'reference/commands',
+        'reference/error-codes',
+        'reference/supported-chains',
+      ],
+    },
+    {
+      type: 'doc',
+      id: 'troubleshooting',
+      label: 'Troubleshooting',
+    },
+  ],
+}
+
+module.exports = sidebar
@@ -0,0 +1,107 @@
+---
+title: MetaMask Agent Wallet
+sidebar_label: Overview
+description: Give your AI agent a self-custody wallet. Install the mm CLI and agent skills, then use natural language in Claude Code, Codex, Cursor, and other agents.
+keywords: [MetaMask, Agent Wallet, mm, AI agents, skills]
+---
+
+import CardList from '@site/src/components/CardList'
+
+A fully self-custodial agent wallet that lets AI agents trade autonomously without forcing users to give up control. Deploying an agent on a self-custody wallet can mean choosing between giving the agent freedom to act and keeping users’ funds safe. MetaMask Agent Wallet ends that trade-off. Your agent operates inside user-defined limits.
+
+:::info Early Access
+MetaMask Agent Wallet is available through the
+[Early Access Program](https://metamask.io/agent-wallet).
+:::
+
+## What your agent can do
+
+After setup, prompt your agent in plain language:
+
+<!-- vale off -->
+
+| You ask your agent                                 | What happens                                                      |
+| -------------------------------------------------- | ----------------------------------------------------------------- |
+| "Show the wallet address and USDC balance on Base" | Your agent checks auth, then queries balances.                    |
+| "Send 10 USDT to 0x123… on Base"                   | Your agent confirms details, then submits a transfer.             |
+| "Swap 0.1 ETH to USDC on Base"                     | Your agent fetches a quote, confirms with you, then executes.     |
+| "Open a 5x long on BTC with $100 on Hyperliquid"   | Your agent deposits if needed, quotes, and opens the position.    |
+| "Bet 10 USDT on YES for BTC 5-min price up"        | Your agent searches markets, confirms odds, and places the order. |
+
+<!-- vale on -->
+
+## MetaMask safety-checks every transaction before it lands
+
+Security by default, not configuration.
+Supported EVM transactions pass through a mandatory 3-step security pipeline.
+Backed by Transaction Protection: transactions through Agent Wallet deemed safe are guaranteed
+against loss up to $10,000.\*
+
+1. **Transaction simulation**: What will this transaction actually do? Balance changes, approvals,
+   and gas are surfaced before signing.
+2. **[Transaction Shield](https://support.metamask.io/manage-crypto/transactions/transaction-shield/)**:
+   Automated security checks flag malicious contracts and scams; flagged transactions require your
+   approval before they execute.
+3. **[Smart Transactions](https://support.metamask.io/manage-crypto/transactions/smart-transactions/)**:
+   Smart transaction execution with built-in MEV protection, fewer fails, and better gas where
+   supported on the target chain.
+
+:::note
+
+Learn more in [Architecture](reference/architecture.md). See [Transaction Shield](https://support.metamask.io/manage-crypto/transactions/transaction-shield/)
+for eligibility, coverage limits, and terms.
+
+:::
+
+## Capabilities
+
+The `mm` CLI exposes a full command surface for wallet operations.
+Your agent routes natural-language requests to these commands through installed skills.
+
+<!-- vale off -->
+
+| Area                                                                | What your agent can do                                  |
+| ------------------------------------------------------------------- | ------------------------------------------------------- |
+| [Authentication](quickstart.md)                                     | Sign in, check session, sign out                        |
+| [Wallet](guides/check-balances-and-prices.md)                       | Create wallet, show address, check balances             |
+| [Send](guides/send-tokens.md)                                       | Transfer native tokens and ERC-20s                      |
+| [Sign / raw transactions](guides/sign-messages-and-transactions.md) | Sign messages, typed data, and raw EVM transactions     |
+| [Decode calldata](guides/sign-messages-and-transactions.md)         | Inspect unfamiliar EVM calldata before signing          |
+| [Swap / bridge](guides/swap-and-bridge.md)                          | Quote, execute, and track swaps and cross-chain bridges |
+| [Perpetuals](guides/trade-perpetuals.md)                            | Trade on Hyperliquid (deposit, open, modify, close)     |
+| [Prediction markets](guides/trade-prediction-markets.md)            | Search, quote, and trade on Polymarket                  |
+| [Market data](guides/check-balances-and-prices.md)                  | Spot prices, token discovery, supported chains          |
+
+<!-- vale on -->
+
+See the [commands reference](reference/commands.md) for every flag and subcommand.
+
+## Supported chains
+
+MetaMask Agent Wallet supports multiple EVM chains.
+Run `mm chains list` for the authoritative list for your CLI version.
+See [Supported chains](reference/supported-chains.md) for typical networks.
+
+## Set up
+
+<CardList
+  items={[
+    {
+      href: '/agent-wallet/quickstart',
+      title: 'Quickstart',
+      description:
+        'Install the CLI, add skills to your agent, sign in, and send your first transfer.',
+    },
+    {
+      href: '/agent-wallet/reference/architecture',
+      title: 'Architecture',
+      description:
+        'Wallet modes, Transaction Protection, Transaction Shield, Smart Transactions, and 2FA.',
+    },
+    {
+      href: '/agent-wallet/guides/trade-perpetuals',
+      title: 'Trade perpetuals',
+      description: 'Deposit, open, modify, and close Hyperliquid positions.',
+    },
+  ]}
+/>
@@ -0,0 +1,75 @@
+---
+description: Check wallet balances, token prices, and discover tokens with mm.
+keywords: [MetaMask, Agent Wallet, balance, price, market data, mm]
+---
+
+# Check balances and prices
+
+Query wallet balances, spot prices, and token metadata without submitting transactions.
+
+## Ask your agent
+
+```text
+You (to your agent): "What's my USDC balance on Base?"
+```
+
+```text
+You (to your agent): "What's the current price of ETH?"
+```
+
+```text
+You (to your agent): "Show me trending tokens on Base"
+```
+
+Read-only queries like these do not require confirmation before your agent runs them.
+
+## Commands
+
+1. Confirm your wallet address:
+
+   ```bash
+   mm wallet address
+   ```
+
+2. Query balances, prices, or token lists using the commands in the following sections.
+
+## Wallet balance
+
+```bash
+mm wallet balance
+mm wallet balance --chain 8453
+mm wallet balance --token USDC
+```
+
+If `--token` with a symbol returns no balance or an error, pass the ERC-20 contract address for that
+chain. Run `mm token list search --query <symbol> --chain <chain-id>` to look up the address.
+
+## Spot prices
+
+```bash
+mm price spot --asset-ids <ASSET_IDS> --vs USD
+mm price currencies
+mm price networks
+```
+
+Use `mm token assets` to resolve asset identifiers for tokens you care about.
+
+## Token discovery
+
+```bash
+mm token list popular --chain ethereum
+mm token list search --query uniswap --chain ethereum
+mm token list trending --chain base
+mm token networks
+```
+
+## Supported chains
+
+```bash
+mm chains list
+```
+
+## Related commands
+
+See [Commands reference](../reference/commands.md) for `mm wallet balance`, `mm price`, and
+`mm token`.