Update agent wallet docs

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

@@ -21,7 +21,7 @@ alwaysApply: false
 
 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).
+Sign-in method determines the 2FA approval channel: browser sign-in (Google or email in the MetaMask dashboard) → email link; QR code (MetaMask Mobile) → Mobile push. QR sign-in (`mm login qr`) is not available in production (`COMING_SOON`); document browser sign-in (`mm login browser`) as the production path. Do not document `mm login google` or `mm login email` (removed in CLI v3).
 
 CLI flags use `server-wallet`, `byok`, `guard`, and `beast`.
 
@@ -56,7 +56,7 @@ Do not add comparative security claims beyond approved product copy.
 | ---------------- | ------------------------------------------------- |
 | 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 |
+| `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.

agent-wallet-sidebar.js

@@ -27,16 +27,19 @@ const sidebar = {
         'guides/swap-and-bridge',
         'guides/trade-perpetuals',
         'guides/trade-prediction-markets',
+        'guides/lend-and-borrow-aave',
         'guides/check-balances-and-prices',
         'guides/sign-messages-and-transactions',
       ],
     },
     {
       type: 'category',
       label: 'Reference',
-      collapsed: true,
+      collapsed: false,
       items: [
         'reference/architecture',
+        'reference/trading-modes',
+        'reference/outflow-policy',
         'reference/commands',
         'reference/error-codes',
         'reference/supported-chains',

agent-wallet/README.mdx

@@ -37,9 +37,15 @@ Supported EVM transactions pass through a mandatory 3-step pipeline before they
 
 1. **Transaction simulation**: What will this transaction actually do? Balance changes, approvals,
    and gas are surfaced before signing.
+
+<!-- vale off -->
+
 2. **Threat scanning**: Powered by Blockaid and production-tested across millions of MetaMask
    transactions. Malicious transactions get auto-bounced. Flagged transactions require your approval
    before they execute.
+
+<!-- vale on -->
+
 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.
@@ -65,14 +71,15 @@ Your agent routes natural-language requests to these commands through installed
 
 | 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             |
+| [Authentication](quickstart.md)                                     | Sign in, verify with `mm doctor`, sign out              |
+| [Wallet](guides/check-balances-and-prices.md)                       | Create wallet, show address, check balances, tx history |
 | [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                  |
+| [Prediction markets](guides/trade-prediction-markets.md)            | Search, quote, trade, and redeem on Polymarket          |
+| [Aave V3](guides/lend-and-borrow-aave.md)                           | Supply, borrow, repay, and manage lending positions     |
 | [Market data](guides/check-balances-and-prices.md)                  | Spot prices, token discovery, supported chains          |
 
 <!-- vale on -->
@@ -106,5 +113,16 @@ See [Supported chains](reference/supported-chains.md) for typical networks.
       title: 'Trade perpetuals',
       description: 'Deposit, open, modify, and close Hyperliquid positions.',
     },
+    {
+      href: '/agent-wallet/guides/lend-and-borrow-aave',
+      title: 'Lend and borrow with Aave V3',
+      description: 'Supply, borrow, repay, and manage Aave V3 positions through your agent.',
+    },
+    {
+      href: '/agent-wallet/reference/trading-modes',
+      title: 'Trading modes',
+      description:
+        'Compare Guard Mode and Beast Mode guardrails, 2FA approval, and outflow limits.',
+    },
   ]}
 />

agent-wallet/guides/check-balances-and-prices.md

@@ -1,6 +1,6 @@
 ---
-description: Check wallet balances, token prices, and discover tokens with mm.
-keywords: [MetaMask, Agent Wallet, balance, price, market data, mm]
+description: Check wallet balances, spot prices, token metadata, and transaction history with mm.
+keywords: [MetaMask, Agent Wallet, balance, price, transaction history, market data, mm]
 ---
 
 # Check balances and prices
@@ -69,7 +69,17 @@ mm token networks
 mm chains list
 ```
 
+## Transaction history
+
+List recent transactions for your wallets:
+
+```bash
+mm tx history
+mm tx history --chain 1,8453 --limit 20
+mm tx history --type out
+```
+
 ## Related commands
 
-See [Commands reference](../reference/commands.md) for `mm wallet balance`, `mm price`, and
-`mm token`.
+See [Commands reference](../reference/commands.md) for `mm wallet balance`, `mm price`, `mm token`,
+and [`mm tx history`](../reference/commands.md#mm-tx-history).

agent-wallet/guides/lend-and-borrow-aave.md

@@ -0,0 +1,171 @@
+---
+description: Supply, borrow, and manage Aave V3 positions using mm wallet commands and the Aave GraphQL API.
+keywords: [MetaMask, Agent Wallet, Aave, DeFi, lending, borrowing, mm]
+---
+
+# Lend and borrow with Aave V3
+
+Supply assets, borrow against collateral, and manage Aave V3 positions through your agent.
+Agent Wallet has no dedicated `mm aave` command.
+Your agent uses `mm wallet` commands together with the [Aave V3 GraphQL API](https://api.v3.aave.com/graphql)
+to build and submit transactions.
+
+Install the `metamask-agent-wallet` skill for multi-step Aave workflow templates.
+
+## Ask your agent
+
+```text
+You (to your agent): "Supply 100 USDC to Aave on Base"
+```
+
+```text
+You (to your agent): "What's my Aave health factor on Ethereum?"
+```
+
+```text
+You (to your agent): "Borrow 0.5 ETH against my USDC collateral on Arbitrum"
+```
+
+Your agent resolves chain and token addresses, queries the Aave API for transaction payloads,
+confirms with you, then submits transactions with `mm wallet send-transaction`.
+
+## Prerequisites
+
+- [Quickstart](../quickstart.md) completed
+- Sufficient token and native-gas balances on the target chain
+- For borrows: supplied collateral with collateral enabled on at least one asset
+
+## Supported chains
+
+| Chain     | Chain ID | Pool address                                 |
+| --------- | -------- | -------------------------------------------- |
+| Ethereum  | 1        | `0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2` |
+| Polygon   | 137      | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Arbitrum  | 42161    | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Optimism  | 10       | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Avalanche | 43114    | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Base      | 8453     | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+
+Resolve token contract addresses with `mm token list search --query <SYMBOL> --chain <CHAIN_ID>`.
+
+## Common pattern
+
+Each Aave operation follows the same steps:
+
+1. Get your wallet address: `mm wallet address`
+2. Check balances or positions on the target chain
+3. Query the Aave V3 GraphQL API for the operation (supply, withdraw, borrow, repay, or collateral
+   toggle)
+4. Handle the response:
+   - **`TransactionRequest`**: confirm with the user, then send with `mm wallet send-transaction`
+   - **`ApprovalRequired`**: send the approval transaction first, then retry the original operation
+   - **`InsufficientBalanceError`**: fund the wallet or bridge tokens to the target chain
+5. Use `--wait` on server-wallet mode and include a descriptive `--intent` when supported
+
+Example transaction submission:
+
+```bash
+mm wallet send-transaction --chain-id <CHAIN_ID> --payload '{"to":"<TO>","value":"0x0","data":"<DATA>"}' --wait
+```
+
+For ERC-20 operations, the transaction `value` is typically `"0x0"`.
+For native token supplies, convert the amount to hex wei in the payload.
+
+Before signing unfamiliar calldata, run `mm decode --payload <0x-calldata>` and confirm the decoded
+intent.
+
+## Supply assets
+
+1. Confirm you hold enough of the supply token and native gas on the chain:
+
+   ```bash
+   mm wallet balance --chain <CHAIN_ID>
+   ```
+
+2. Query the Aave API for a supply execution plan (replace placeholders with your values):
+
+   ```bash
+   curl -s -X POST https://api.v3.aave.com/graphql \
+     -H 'Content-Type: application/json' \
+     -d '{
+       "query": "{ supply(request: { market: \"<POOL_ADDRESS>\", amount: { erc20: { currency: \"<ASSET_ADDRESS>\", value: \"<AMOUNT>\" } }, sender: \"<WALLET_ADDRESS>\", chainId: <CHAIN_ID> }) { __typename ... on TransactionRequest { to from data value chainId } ... on ApprovalRequired { approval { to from data value chainId } originalTransaction { to from data value chainId } } } }"
+     }'
+   ```
+
+3. If the response is `ApprovalRequired`, send the approval transaction, then retry supply.
+4. Confirm recipient, amount, token, and chain before executing.
+
+## Withdraw assets
+
+1. Query your positions (see [Check positions](#check-positions)).
+2. Before a full withdrawal, confirm no outstanding debt remains.
+   Full collateral withdrawal reverts if any debt exists.
+3. Query the Aave API for a withdraw execution plan and submit the transaction after confirmation.
+
+For partial withdrawals with outstanding borrows, preview the health factor impact through the Aave
+API `healthFactorPreview` query before proceeding.
+
+## Borrow assets
+
+1. Confirm supplied collateral with collateral enabled.
+2. Check available borrow capacity and that `borrowCapReached` is not `true` for the target asset.
+3. Preview health factor impact with the Aave `healthFactorPreview` query.
+4. Query the borrow execution plan and submit after confirmation.
+
+## Repay debt
+
+1. Query outstanding borrows from your positions.
+2. Query the Aave API for a repay execution plan.
+3. Handle `ApprovalRequired` if the debt asset is an ERC-20, then submit the repay transaction.
+
+## Toggle collateral
+
+Enable or disable an asset as collateral for borrowing.
+When disabling collateral with outstanding borrows, preview the health factor impact.
+Do not disable collateral if the health factor would drop below 1.0.
+
+## Check positions
+
+Query supply and borrow positions in one request:
+
+```bash
+curl -s -X POST https://api.v3.aave.com/graphql \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": "{ userSupplies(request: { markets: [{ address: \"<POOL_ADDRESS>\", chainId: <CHAIN_ID> }], user: \"<WALLET_ADDRESS>\" }) { currency { symbol decimals } balance { amount { value } usd } apy { formatted } isCollateral } userBorrows(request: { markets: [{ address: \"<POOL_ADDRESS>\", chainId: <CHAIN_ID> }], user: \"<WALLET_ADDRESS>\" }) { currency { symbol decimals } debt { amount { value } usd } apy { formatted } } }"
+  }'
+```
+
+Present supply balances, borrow balances, collateral status, and APY rates to the user.
+
+## Discover markets
+
+List available reserves, supply APY, borrow APY, and liquidity on a chain:
+
+```bash
+curl -s -X POST https://api.v3.aave.com/graphql \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": "{ markets(request: { chainIds: [<CHAIN_ID>] }) { reserves { underlyingToken { symbol decimals } supplyInfo { apy { formatted } } borrowInfo { apy { formatted } availableLiquidity { amount { value } usd } borrowCapReached } isFrozen isPaused } } }"
+  }'
+```
+
+Skip reserves where `isFrozen` or `isPaused` is `true`.
+
+## Common pitfalls
+
+:::caution Confirm before submitting
+Always confirm operation type, token, amount, chain, and health factor impact (for borrows and
+collateral changes) before calling `mm wallet send-transaction`.
+:::
+
+:::caution Guard Mode allowlists
+Aave pool contracts must be permitted by your server-wallet policy in Guard Mode.
+Transactions to untrusted contracts require 2-factor authentication approval.
+:::
+
+## Related commands
+
+- [`mm wallet send-transaction`](../reference/commands.md#mm-wallet-send-transaction)
+- [`mm decode`](../reference/commands.md#mm-decode)
+- [Check balances and prices](check-balances-and-prices.md)

agent-wallet/guides/swap-and-bridge.md

@@ -57,6 +57,29 @@ mm swap quote --from USDC --to USDC --amount 10 --from-chain 8453 --to-chain 421
 mm swap execute --quote-id <QUOTE_ID>
 ```
 
+### Send bridged tokens to another address
+
+Add `--to-address` to send output tokens to a recipient other than your wallet.
+Only valid for cross-chain bridges (`--to-chain` differs from `--from-chain`):
+
+```bash
+mm swap quote --from USDC --to USDC --amount 10 --from-chain 8453 --to-chain 42161 --to-address 0x742d35Cc6634C0532925a3b844Bc454e4438f08e
+```
+
+### Top up destination gas (refuel)
+
+When bridging to a chain where you hold no native gas token, add `--refuel` to bundle a small
+destination native-gas top-up into the quote:
+
+```bash
+mm swap quote --from USDC --to USDC --amount 50 --from-chain 1 --to-chain 42161 --refuel
+```
+
+Refuel is opt-in and cross-chain only.
+Do not use `--refuel` when the destination token is the destination chain's native gas asset (for
+example, bridging ETH to Arbitrum ETH).
+The backend returns `NO_QUOTES` in that case.
+
 ## Common pitfalls
 
 :::caution Verify the quote step succeeded

agent-wallet/guides/trade-prediction-markets.md

@@ -20,6 +20,10 @@ You (to your agent): "Bet 10 USDT on YES for BTC 5-min price up"
 You (to your agent): "Show my open prediction market positions"
 ```
 
+```text
+You (to your agent): "Redeem my winning Polymarket positions"
+```
+
 Your agent runs one-time setup if needed, shows current odds, confirms your bet, then places the
 order.
 
@@ -60,6 +64,14 @@ order.
    mm predict markets search "<QUERY>" --limit 5
    ```
 
+   Browse by event, series, or tag:
+
+   ```bash
+   mm predict events list --tag-slug politics --active
+   mm predict series list --recurrence weekly
+   mm predict tags list
+   ```
+
 2. Preview a quote:
 
    ```bash
@@ -86,8 +98,24 @@ order.
    ```bash
    mm predict orders
    mm predict positions
+   mm predict portfolio
    ```
 
+## Redeem winnings
+
+List redeemable winning positions:
+
+```bash
+mm predict redeem list
+```
+
+Redeem one condition or all winning positions:
+
+```bash
+mm predict redeem <CONDITION_ID> --wait
+mm predict redeem --all --wait
+```
+
 ## Common pitfalls
 
 :::caution One-time setup is required