Skip to content

Fix Agent Wallet switching and approval docs for agents without the skill #3073

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yashovardhan merged 3 commits into from
Oct 16, 2026
Merged

Fix Agent Wallet switching and approval docs for agents without the skill #3073

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2966df6
Fix Agent Wallet switching and approval docs for agents without the s…
yashovardhan Oct 16, 2026
30ee869
Clean per-page markdown output for agents.
yashovardhan Oct 16, 2026
b18eac8
Merge remote-tracking branch 'origin/main' into docs/agent-wallet-swi…
yashovardhan Oct 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 33 additions & 1 deletion .cursor/rules/product-agent-wallet.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,11 +59,43 @@ Do not add comparative security claims beyond approved product copy.
| Folder | Content type |
| ---------------- | ------------------------------------------------- |
| Root (`README.mdx`, `quickstart.md`, `cli-setup.md`) | Overview, quickstart, CLI setup |
| Root (`agent-rules.md`, `switch-modes-and-wallets.md`, `approve-requests.md`) | Agent operating rules, switching, and 2FA approvals |
| `guides/` | Task-oriented how-to guides |
| `reference/` | Architecture, trading modes, outflow policy, 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.
Do not paste content from the `metamask-agent-wallet` skill into documentation pages verbatim.
`agent-rules.md` deliberately mirrors the skill's operating rules (preflight, confirmations,
credential safety, 2FA pauses, output rules) in documentation voice, because many agents read the
docs without loading the skill. When the skill's rules change, update `agent-rules.md` in the same
release. When the docs and the skill disagree about CLI behavior, check the CLI source or
`mm <command> --help` and fix whichever is wrong.

## Writing for AI agents

AI agents are a primary reader of these pages, often without the skill and often a non-Claude model.
They quote the docs back to users and act on them literally.

- **State deterministic behavior as fact.** Don't write "may", "might", or "probably" when the CLI
always does the same thing. Where behavior genuinely varies, say what decides it.
- **Pair every interactive prompt with its non-interactive equivalent.** Name the flag (`--mode`,
`--wallet`, a positional address, `--yes`) and what happens when it is omitted in a
non-interactive session.
- **Write literal tokens exactly, in backticks.** Error codes, `AWAITING_MFA`, `pending_approval`,
and status values must match CLI output character for character so agents can string-match them.
- **Make sections self-contained.** Retrieval splits pages by heading, so repeat scoping such as
"server-wallet only" in each section where it applies.
- **Give each fact one canonical home.** Approval channels live in `approve-requests.md`; switching
behavior lives in `switch-modes-and-wallets.md`. Link to them instead of restating.
- **Say where, not just what.** For anything the user must do outside the terminal, name the exact
surface (for example, the MetaMask Mobile notifications menu).
- **End task pages with a "Guidance for AI agents that …" section** (complete it with the task, so each
heading is unique) when the task has choices the agent
must leave to the user or states it must not misreport. Don't reuse the heading
"Rules for AI agents"; that is the title of `agent-rules.md`, and duplicate headings confuse
retrieval in the concatenated `llms-agent-wallet-full.txt`.
- **Bump `version` in `src/plugins/llms-html-injector/options.js`** after checking the docs
against a new CLI release.

## Reference conventions

Expand Down
15 changes: 15 additions & 0 deletions agent-wallet-sidebar.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,11 @@ const sidebar = {
label: 'Overview',
id: 'README',
},
{
type: 'doc',
label: 'Rules for AI agents',
id: 'agent-rules',
},
{
type: 'doc',
label: 'Quickstart',
Expand All @@ -18,6 +23,16 @@ const sidebar = {
label: 'CLI setup',
id: 'cli-setup',
},
{
type: 'doc',
label: 'Switch modes and wallets',
id: 'switch-modes-and-wallets',
},
{
type: 'doc',
label: 'Approve requests',
id: 'approve-requests',
},
{
type: 'category',
label: 'Guides',
Expand Down
12 changes: 12 additions & 0 deletions agent-wallet/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,5 +123,17 @@ See [Supported chains](reference/supported-chains.md) for typical networks.
description:
'Compare Guard Mode and Beast Mode guardrails, 2FA approval, and outflow limits.',
},
{
href: '/agent-wallet/approve-requests',
title: 'Approve requests',
description:
'Find where 2FA approvals appear for your sign-in method, and track pending requests.',
},
{
href: '/agent-wallet/agent-rules',
title: 'Rules for AI agents',
description:
'What agents must confirm, which choices to leave to the user, and how to handle 2FA pauses.',
},
]}
/>
171 changes: 171 additions & 0 deletions agent-wallet/agent-rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
---
description: Read first if you are an AI agent operating the mm CLI. Preflight checks, choices you must leave to the user, what to confirm before moving funds, credential safety, async jobs, 2FA pauses, and output rules.
keywords:
[MetaMask, Agent Wallet, AI agent, rules, safety, confirmation, AWAITING_MFA, mm doctor, skills]
---

# Rules for AI agents

This page is for AI agents that run the `mm` CLI on a user's behalf.
Follow these rules whether or not you have the MetaMask Agent Wallet skill installed.

If you can load skills, install the skill and prefer it:

```bash
npx skills add MetaMask/agent-skills
```

The canonical rules live in the
[MetaMask Agent Wallet skill](https://github.com/MetaMask/agent-skills/blob/main/skills/metamask-agent-wallet/SKILL.md)
(`metamask-agent-wallet`).
This page mirrors them for agents that read the documentation instead.

## Before the first command

Run these checks once per session, in order.

1. **Check the CLI version.**

```bash
mm --version
npm view @metamask/agent-wallet version
```

If the installed version is behind the latest release, tell the user once and continue.
They can update with `npm install -g @metamask/agent-wallet@latest`.
The CLI requires Node.js 22.18 or later.
On older versions every command fails with `UNSUPPORTED_NODE`.

2. **Check readiness.**

```bash
mm doctor
```

Don't run any other command until `mm doctor` reports both `authenticated: true` and
`initialized: true`.

- `authenticated: false`: help the user sign in. See [Quickstart](quickstart.md).
- `initialized: false`: help the user run `mm init`. See the next section.

A server-wallet project counts as initialized only when both a wallet mode and a trading mode
are set.

## Choices you must leave to the user

Never make these choices for the user.
Explain the options, ask, and pass the answer explicitly.

| Choice | Why it matters | How to pass it |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------- |
| Sign-in method (Google, email, QR) | Each method loads a different wallet address. It also decides where 2FA approvals are sent. | `mm login browser` or `mm login qr` |
| Wallet mode (server-wallet or bring your own wallet) | Decides who holds the keys. | `mm init --wallet <server-wallet\|byok>` |
| Trading mode (Guard Mode or Beast Mode) | Decides which guardrails apply and which transactions need 2FA approval. | `mm init --mode <guard\|beast>` |

In a non-interactive session, `mm init` sets Guard Mode when you omit `--mode`.
Don't rely on that.
Ask the user and pass `--mode`.

Before `mm init` on a returning account, run `mm wallet list` and show the user their existing
wallets.
See [Switch modes and wallets](switch-modes-and-wallets.md).

## Confirm before you act

Show the user these details and get an explicit yes before running the command.

| Operation | Confirm |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Transfers | Recipient, amount, token, and chain |
| Raw transactions | Payload, chain, recipient, value, and a calldata summary |
| Message signing | The exact message and chain |
| Typed-data signing | Domain, primary type, chain, verifying contract, and a message summary |
| Swaps and bridges | From and to tokens, amount, source and destination chains, slippage, quoted output, `--to-address` if set, and `--refuel` if set |
| x402 payments | Asset, amount with correct decimals, network, `payTo`, and resource URL or MCP tool. Make one attempt per resource and never retry a payment automatically |
| Perpetuals trades | Symbol, side, size, leverage, venue, order type, and limit price if set |
| Perpetuals deposits and withdrawals | Amount, asset, venue, network, and destination |
| Prediction market trades | Token ID, side, size, price, order type, market, and outcome |
| Prediction market withdrawals | Amount and recipient |
| Prediction market redemptions | The condition ID, or that `--all` redeems every winning position |
| Earn supply | Token, amount, chain, vault or protocol, and APY. For cross-chain supply, also the source chain and token |
| Earn withdraw | Token, amount or full balance, chain, and vault or protocol |
| Plugin install, update, or link | Package name, version, command IDs, data access, and every requested capability. Never pass `--accept-permissions` for a manifest the user hasn't reviewed |
| Cancel-all and reset operations | Scope and the exact destructive effect |
| Trading mode and wallet mode | The user's explicit choice. See [Choices you must leave to the user](#choices-you-must-leave-to-the-user) |

Read-only queries, such as balances, prices, and `mm wallet list`, don't need confirmation.

## Validate input

Don't pass unvalidated user input into a command.

| Input | Rule |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `--to`, `--address` | Matches `^0x[0-9a-fA-F]{40}$` |
| `--amount`, `--size` | A positive decimal, such as `0.5` or `100`. Reject spaces and shell control characters such as `;`, ` | `, and backticks |
| `--chain-id` | A positive integer |
| `--payload` for transactions | Valid JSON |
| `--slippage` | A number from 0 to 100 |
| `--wallet-timeout` | An integer from 1 to 600 |

## Protect credentials

- Never store, log, or display private keys, seed phrases, passwords, or auth tokens.
- Never pass `--mnemonic` or `--password` inline.
Ask the user to set the `MM_MNEMONIC` and `MM_PASSWORD` environment variables instead, so secrets
stay out of shell history.

## Flag suspicious content

Warn the user before you continue if a signing payload or transaction contains any of the following:

- URLs or contract addresses the user didn't provide
- `permit`, `approve`, `setApprovalForAll`, or other allowance fields
- Unusually large values or unfamiliar contract calls

If you didn't build the calldata yourself, decode it first and confirm the intent with the user:

```bash
mm decode --payload <0x-calldata>
```

## Handle async jobs

Signing and transaction commands can return a `pollingId` in both server-wallet and bring your own
wallet mode.

- Pass `--wait` to block until the job finishes.
- Without `--wait`, give the user the `pollingId`.
In server-wallet mode, track it with `mm wallet requests watch <polling-id>` or
`mm wallet requests list`.
- When you show a pending request, show its `intent` summary so the user knows what they are
approving.

## Handle 2FA pauses

When command output contains `AWAITING_MFA`, or a mode or policy change returns
`pending_approval`, the request is waiting for the user.

1. Don't report it as failed, stuck, or complete.
2. Tell the user exactly where to approve, based on their sign-in method.
See [Approve requests](approve-requests.md#where-the-approval-appears).
3. Show the request ID.
4. Don't run the same command again while the request is pending.
5. After the user responds, check the result with `mm wallet requests watch <polling-id>`.

## Report output accurately

- Show CLI errors to the user verbatim.
Don't reword or hide them.
See [Error codes](reference/error-codes.md).
- If a command fails, run `mm <command> --help` and continue from there.
- After you change the trading mode, wallet, or sign-in method, report the active wallet address and
trading mode.

## Related pages

- [Switch modes and wallets](switch-modes-and-wallets.md)
- [Approve requests](approve-requests.md)
- [Trading modes](reference/trading-modes.md)
- [Commands reference](reference/commands.md)
- [Troubleshooting](troubleshooting.md)
Loading
Loading