Skip to content

Commit 2f3da9f

Browse files
yashovardhanyashovardhan
committed
Update agent wallet docs
1 parent 7c81555 commit 2f3da9f

11 files changed

Lines changed: 221 additions & 78 deletions

File tree

‎.cursor/rules/product-agent-wallet.mdc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ Do not add comparative security claims beyond approved product copy.
5656
| ---------------- | ------------------------------------------------- |
5757
| Root (`README.mdx`, `quickstart.md`, `use-the-cli-directly.md`) | Overview, quickstart, headless CLI |
5858
| `guides/` | Task-oriented how-to guides |
59-
| `reference/` | Architecture, CLI commands, error codes, supported chains |
59+
| `reference/` | Architecture, trading modes, outflow policy, CLI commands, error codes, supported chains |
6060
| `troubleshooting/` | Symptom-based fixes (single page in v1) |
6161

6262
Do not paste content from `.agents/skills/metamask-agent-wallet/` into documentation pages.

‎agent-wallet-sidebar.js‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,11 @@ const sidebar = {
3434
{
3535
type: 'category',
3636
label: 'Reference',
37-
collapsed: true,
37+
collapsed: false,
3838
items: [
3939
'reference/architecture',
40+
'reference/trading-modes',
41+
'reference/outflow-policy',
4042
'reference/commands',
4143
'reference/error-codes',
4244
'reference/supported-chains',

‎agent-wallet/quickstart.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -57,20 +57,21 @@ commands.
5757

5858
### Sign in
5959

60-
During `mm login`, choose QR code, Google, or email.
60+
During `mm login`, choose Google or email.
61+
QR code sign-in with MetaMask Mobile is coming soon.
6162
Your sign-in method also determines how you receive 2-factor authentication approvals when a
6263
transaction needs your confirmation.
6364

64-
| Sign-in method | 2FA delivery |
65-
| --------------- | ----------------------------------- |
66-
| QR code | MetaMask Mobile push notification |
67-
| Google or email | Email link with transaction details |
65+
| Sign-in method | 2FA delivery |
66+
| --------------------- | ----------------------------------- |
67+
| Google or email | Email link with transaction details |
68+
| QR code (coming soon) | MetaMask Mobile push notification |
6869

69-
:::info QR code sign-in
70+
:::note QR code sign-in (coming soon)
7071

7172
Sign in with MetaMask Mobile by scanning the QR code the CLI displays.
72-
The CLI and your agent can access only the dedicated Agent Wallet created for this setup, not your
73-
main MetaMask wallet or its accounts.
73+
When available, the CLI and your agent can access only the dedicated Agent Wallet created for this
74+
setup, not your main MetaMask wallet or its accounts.
7475
When a transaction needs approval, you receive a 2-factor authentication prompt in MetaMask Mobile.
7576

7677
:::
@@ -95,7 +96,7 @@ During `mm init`, choose a wallet mode and, for server-wallet, a trading mode.
9596
- **Beast Mode**: designed for power users. Keeps the threat scanning guardrail only. Malicious
9697
transactions and risky contracts are blocked and surfaced for 2-factor authentication approval.
9798

98-
See [Trading modes](reference/architecture.md#trading-modes) for guardrails and approval conditions.
99+
See [Trading modes](reference/trading-modes.md) for guardrails and approval conditions.
99100

100101
Confirm your choices with `mm init show`.
101102

‎agent-wallet/reference/architecture.md‎

Lines changed: 3 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -87,63 +87,9 @@ where supported on the target chain.
8787
## Trading modes
8888

8989
Trading modes apply to server-wallet only.
90-
During `mm init`, you set outflow limits and allowlists, then choose a trading mode that defines how
91-
those policies are enforced.
92-
Choose during `mm init` with `--mode` or at the interactive prompt.
93-
94-
| Mode | CLI flag | Summary |
95-
| ------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------- |
96-
| Guard Mode (Recommended) | `--mode guard` | Designed for everyday traders. Transactions outside your policy limits require 2-factor authentication approval. |
97-
| Beast Mode | `--mode beast` | Designed for power users. Malicious transactions are still blocked and surfaced for 2-factor authentication approval. |
98-
99-
### Guard Mode (Recommended)
100-
101-
Designed for everyday traders.
102-
Transactions outside your policy limits require 2-factor authentication approval.
103-
104-
**Guardrails**
105-
106-
- Threat scanning
107-
- Network allowlist
108-
- Token recipient allowlist
109-
- Address allowlist
110-
- Outflow limit (rolling 24h)
111-
112-
**Approval required for**
113-
114-
- Malicious transactions
115-
- Addresses or contracts not in allowlist
116-
- Networks not in allowlist
117-
- Recipients not in allowlist
118-
- Raising outflow limit
119-
120-
### Beast Mode
121-
122-
Designed for power users.
123-
Malicious transactions are still blocked and surfaced for 2-factor authentication approval.
124-
125-
**Guardrails**
126-
127-
- Threat scanning
128-
129-
**Approval required for**
130-
131-
- Malicious transactions
132-
- Risky contracts
133-
134-
When 2-factor authentication is required, the CLI pauses the job until you approve or reject it.
135-
Your sign-in method during `mm login` determines which channel the CLI uses:
136-
137-
| Sign-in method | Approval channel |
138-
| --------------- | ----------------------------------- |
139-
| QR code | MetaMask Mobile push notification |
140-
| Google or email | Email link with transaction details |
141-
142-
The agent cannot proceed without your approval on flagged or policy-violating transactions.
143-
144-
Switch modes by re-running `mm init` with a different `--mode` value.
145-
Confirm the active configuration with `mm init show`.
146-
See [Trading modes](../use-the-cli-directly.md#trading-modes-server-wallet-only).
90+
During `mm init`, you set allowlists and choose Guard Mode or Beast Mode to define how those policies
91+
are enforced.
92+
See [Trading modes](trading-modes.md) for the full guardrail and approval comparison.
14793

14894
## Server-wallet async model
14995

‎agent-wallet/reference/commands.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,16 +38,17 @@ Environment variables: `MM_MNEMONIC`, `MM_PASSWORD` (bring your own wallet encry
3838
Sign in to MetaMask Agent Wallet.
3939

4040
```bash
41-
mm login [qr | google | email] [--token <token>] [--no-wait]
42-
mm login qr
41+
mm login [google | email] [--token <token>] [--no-wait]
4342
mm login google [--no-wait]
4443
mm login email [--no-wait]
4544
```
4645

46+
QR code sign-in (`mm login qr`) is coming soon.
47+
4748
| Flag | Required | Description |
4849
| ----------- | -------- | ------------------------------------------------------------------------------------ |
4950
| `--token` | No | Pre-minted token as `cliToken:cliRefreshToken`. Environment variable: `MM_CLI_TOKEN` |
50-
| `--no-wait` | No | Print sign-in URL and exit (not supported for QR) |
51+
| `--no-wait` | No | Print sign-in URL and exit |
5152

5253
## `mm auth status`
5354

‎agent-wallet/reference/outflow-policy.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
description: How Agent Wallet enforces rolling 24-hour outflow limits on server-wallet transactions.
3+
keywords: [MetaMask, Agent Wallet, outflow policy, outflow limit, server-wallet, Guard Mode, 2FA]
4+
---
5+
6+
# Outflow policy
7+
8+
Your outflow limit caps the total value that can leave the server-wallet in a rolling 24-hour window.
9+
MetaMask tracks outflows automatically and requests 2-factor authentication approval when a transaction
10+
would exceed the limit.
11+
12+
Outflow limits apply in **Guard Mode (Recommended)** when using server-wallet.
13+
See [Trading modes](trading-modes.md) for how Guard Mode enforces this policy alongside other
14+
guardrails.
15+
16+
## Setting your outflow limit
17+
18+
You're prompted to set your outflow limit on your first transaction, or whenever a transaction would
19+
exceed your current limit.
20+
When you set your 24-hour outflow limit, it counts the transaction you're approving now plus all
21+
subsequent transactions in the rolling window.
22+
23+
## How outflow is calculated
24+
25+
Before signing, MetaMask simulates the transaction value and adds that value to your 24-hour total once
26+
the transaction is confirmed (submitted successfully).
27+
28+
For example, if you swap 10 USDC to ETH and later swap the ETH to DAI, this counts as a \$10 outflow for
29+
USDC to ETH and another \$10 for ETH to DAI.
30+
31+
You'll receive a 2-factor authentication request when the transaction exceeds your 24-hour outflow
32+
limit.
33+
34+
## What's included
35+
36+
The following transaction types count toward your outflow limit:
37+
38+
- Swaps and liquidity deposits (like on Uniswap).
39+
- Polymarket USDC deposits to deposit addresses and collateral onramp contracts.
40+
- Hyperliquid deposits to bridge and deposit contracts.
41+
42+
## Limitations
43+
44+
Outflow tracking can be imprecise if transactions are not submitted through our backend.
45+
46+
When an outflow can't be tracked reliably, such as when a transaction can't be simulated, fall back on
47+
your allowlists.
48+
49+
Signatures (for example, Permit2) are not included in the outflow calculation as of now.
50+
51+
## Related
52+
53+
- [Trading modes](trading-modes.md)
54+
- [Architecture](architecture.md)

‎agent-wallet/reference/trading-modes.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
description: Guard Mode and Beast Mode trading policies for server-wallet, including guardrails and 2FA approval.
3+
keywords:
4+
[
5+
MetaMask,
6+
Agent Wallet,
7+
trading modes,
8+
Guard Mode,
9+
Beast Mode,
10+
server-wallet,
11+
2FA,
12+
allowlist,
13+
outflow limit,
14+
]
15+
---
16+
17+
# Trading modes
18+
19+
Trading modes apply to server-wallet only.
20+
During `mm init`, you are prompted to choose a trading mode.
21+
22+
## Guard Mode vs Beast Mode
23+
24+
Guard Mode enforces all of your policies and asks for approval on anything outside them.
25+
26+
Beast Mode is for power users who want fewer interruptions.
27+
It still blocks and surfaces dangerous transactions.
28+
29+
:::info
30+
31+
We recommend **Guard Mode** for most users.
32+
33+
:::
34+
35+
## Comparison
36+
37+
### Guardrails
38+
39+
Policies enforced automatically before a transaction can proceed.
40+
41+
| Guardrail | Guard Mode | Beast Mode |
42+
| ------------------------------- | ---------- | ---------- |
43+
| Threat scanning | ✓ | ✓ |
44+
| Network allowlist | ✓ | — |
45+
| Address allowlist | ✓ | — |
46+
| Token recipient allowlist | ✓ | — |
47+
| Rolling 24-hour outflow limit\* | ✓ | — |
48+
49+
In Guard Mode, untrusted contracts, networks, and recipients are caught by your allowlists.
50+
In Beast Mode there are no allowlists.
51+
52+
### Requires 2FA approval
53+
54+
Transactions that pause the job until you approve or reject them.
55+
56+
| Condition | Guard Mode | Beast Mode |
57+
| -------------------------------- | ---------- | ---------- |
58+
| Malicious transactions | ✓ | ✓ |
59+
| Risky contracts | ✓ | ✓ |
60+
| Anything outside your allowlists | ✓ | — |
61+
| Raising your outflow limit | ✓ | — |
62+
63+
In Beast Mode, only malicious and risky transactions trigger approval.
64+
65+
:::note
66+
67+
See [Outflow policy](outflow-policy.md) for how outflows are tracked.
68+
69+
:::
70+
71+
## Set your trading mode
72+
73+
Set the mode with the `--mode` flag, or pick it at the interactive prompt:
74+
75+
```bash
76+
mm init --mode guard # or --mode beast
77+
```
78+
79+
## How 2FA approval works
80+
81+
When a transaction needs approval, the CLI pauses the job until you approve or reject it.
82+
The agent cannot proceed on a flagged or policy-violating transaction without your response.
83+
84+
Your sign-in method during `mm login` determines where the approval request is sent:
85+
86+
| Sign-in method | Approval channel |
87+
| ----------------------------- | --------------------------------- |
88+
| MetaMask Mobile (QR code)\*\* | MetaMask Mobile push notification |
89+
| Google or email | Email link |
90+
91+
\*\* QR code sign-in (`mm login qr`) is coming soon.
92+
93+
## Switch modes
94+
95+
Re-run `mm init` with a different `--mode` value to change modes.
96+
Confirm your active configuration with:
97+
98+
```bash
99+
mm init show
100+
```
101+
102+
## Outflow policy
103+
104+
Guard Mode enforces a rolling 24-hour outflow limit on server-wallet outgoing transfers.
105+
You're prompted to set the limit on your first transaction, or when a transaction would exceed your
106+
current limit.
107+
If a transaction would exceed the limit, or you request a higher limit, the CLI requires
108+
2-factor authentication approval before the transaction proceeds.
109+
110+
See [Outflow policy](outflow-policy.md) for how outflows are calculated, what counts toward the
111+
limit, and known limitations.

‎agent-wallet/use-the-cli-directly.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,15 @@ mm login
2626
mm auth status
2727
```
2828

29-
During `mm login`, choose QR code, Google, or email.
29+
During `mm login`, choose Google or email.
30+
QR code sign-in with MetaMask Mobile is coming soon.
3031
Your sign-in method also determines how you receive 2FA approvals when a transaction needs your
3132
confirmation:
3233

33-
| Sign-in method | 2FA delivery |
34-
| --------------- | ----------------------------------- |
35-
| QR code | MetaMask Mobile push notification |
36-
| Google or email | Email link with transaction details |
34+
| Sign-in method | 2FA delivery |
35+
| --------------------- | ----------------------------------- |
36+
| Google or email | Email link with transaction details |
37+
| QR code (coming soon) | MetaMask Mobile push notification |
3738

3839
For headless or CI environments:
3940

@@ -85,8 +86,7 @@ rolling 24-hour outflow limit.
8586
Beast Mode keeps only the threat scanning guardrail.
8687
2FA is required for malicious transactions and risky contracts.
8788

88-
See [Trading modes](reference/architecture.md#trading-modes) for the full guardrail and approval
89-
lists.
89+
See [Trading modes](reference/trading-modes.md) for the full guardrail and approval lists.
9090

9191
Switch modes by re-running `mm init` with a different `--mode` value.
9292

‎src/components/SidebarSectionDropdown/configs.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,11 @@ export const SMART_ACCOUNTS_KIT_CONFIG: SidebarStaticTitleProps = {
3333
pathPattern: '/smart-accounts-kit',
3434
}
3535

36+
export const AGENT_WALLET_CONFIG: SidebarStaticTitleProps = {
37+
title: 'Agent Wallet',
38+
pathPattern: '/agent-wallet',
39+
}
40+
3641
export function isPathInSections(
3742
pathname: string,
3843
sections: SidebarSectionDropdownProps['sections']

0 commit comments

Comments
 (0)