How to set up MetaMask Agent Wallet and make your first trade
Install the CLI, add skills to your agent, pick a sign-in method and safety mode, fund your wallet, and place a first trade. Here's the full path.
- MetaMask
- Before you start
- Step 1: Install the CLI
- Step 2: Add skills to your agent
- Step 3: Start setup with one prompt
- Step 4: Sign in with one method, and keep using it
- Step 5: Choose your wallet mode and trading mode
- Step 6: Fund your wallet
- Step 7: Make your first trade
- If setup stalls
- Where to go next
Setting up MetaMask Agent Wallet takes three moves: install the mm CLI, add skills to your AI agent, and paste one prompt. Your agent then walks you through signing in and choosing your safety settings. Once you fund the wallet, it can swap tokens from a plain-language request. Perps and prediction markets add a funding step of their own, covered in their guides. This guide follows the official quickstart from install to first trade.
This is a setup guide, not an explainer. For what an agentic wallet is, see what is an agentic wallet. For how the transaction lifecycle and security pipeline work, see how agentic wallets work and agentic wallet security.
Before you start
You need:
- Node.js 22.18 or later. Check with node --version.
Node.js 22.18 or later. Check with node --version.
- An AI agent that supports skills, such as Claude Code, Codex, Cursor, OpenClaw, or Hermes Agent. (No skills? Step 3 covers a terminal-only path.)
An AI agent that supports skills, such as Claude Code, Codex, Cursor, OpenClaw, or Hermes Agent. (No skills? Step 3 covers a terminal-only path.)
- Funds you can send from another wallet or an exchange.
Funds you can send from another wallet or an exchange.
Step 1: Install the CLI
The mm CLI is how your agent signs in, checks balances, and sends transactions.
npm install -g @metamask/agent-wallet@latest
Yarn, pnpm, and Bun work too (yarn global add, pnpm add -g, or bun add --global, with the same package). Run mm doctor afterward to confirm the CLI version and skill compatibility. Hints about missing skills are expected until step 2.
Step 2: Add skills to your agent
Skills teach your agent which mm commands to run and when to ask for your confirmation before moving funds.
npx skills add MetaMask/agent-skills
Step 3: Start setup with one prompt
Open your agent and paste:
Set up MetaMask Agent Wallet: help me pick a sign-in method, wallet mode, and trading mode, then show my address.
Your agent asks which sign-in method you want, then runs the setup commands. The next two steps cover the choices it asks you to make.
Prefer the terminal, or running an agent without skills? Run mm doctor, mm login, mm init, then mm doctor again. The CLI setup guide covers each command.
Step 4: Sign in with one method, and keep using it
Method
How you sign in
Where approvals arrive later
Continue with Google in the browser dashboard
Email link
Email passwordless
Continue with email in the browser dashboard
Email link
MetaMask Mobile QR
Scan a QR code with MetaMask Mobile
MetaMask Mobile push notification
Google, email, and MetaMask Mobile QR each load a different server wallet address, even if you use the same address for email and Google login (when you choose Mobile QR, no email address is used). Pick one method, use it every time, and run mm wallet address after each sign-in to confirm you're looking at the address you funded.
For Google or email, your agent opens the Agent Wallet dashboard in your browser. Sign in, click Authorize, then copy the CLI token from the browser and paste it into your terminal if prompted. Email sign-in adds a verification code from your inbox: enter it in the browser before you click Authorize. That code is not the CLI token, so don't paste it into the terminal.
For MetaMask Mobile QR, your agent shows a QR code in the terminal. Open MetaMask Mobile, scan the code, and approve the connection in the app.
Step 5: Choose your wallet mode and trading mode
Your agent asks how it should hold funds:
Wallet mode
Best for
Server wallet
Most users. Keys stay secured via TEE, so your agent gets a dedicated wallet without access to your main one.
Bring your own wallet
You already have a seed phrase and want keys to stay on your machine.
If you bring your own wallet, set the MM_MNEMONIC environment variable rather than passing the phrase on the command line:
export MM_MNEMONIC = ""
With a server wallet, your agent also asks for a trading mode:
Trading mode
Best for
Guard Mode (recommended)
Everyday use. Allowlists, a rolling 24-hour outflow limit, and your approval for anything outside your policy.
Beast Mode
Power users who want fewer limits. Threat scanning stays on, and malicious transactions still need your approval.
Guard Mode is the recommended choice for most users. You can change modes later with mm wallet trading-mode set guard or mm wallet trading-mode set beast. For the full guardrail-by-guardrail comparison, see trading modes.
Step 6: Fund your wallet
When setup finishes, your agent shows your wallet address. Confirm it matches what you expect, then send funds from another wallet or an exchange. You can ask your agent for it anytime:
Show my wallet address and balance.
Two things to know before you send:
- Balances are per chain. Fund the chain you plan to trade on. Run mm chains list to see supported networks and which features (swap, predict, perps) each one supports.
Balances are per chain. Fund the chain you plan to trade on. Run mm chains list to see supported networks and which features (swap, predict, perps) each one supports.
- Check the chain's coverage. On chains marked "No" in the Transaction Shield column of the supported chains list, threat scanning is unavailable. Ethereum, Base, Arbitrum, Optimism, and Polygon are among the covered chains.
Check the chain's coverage. On chains marked "No" in the Transaction Shield column of the supported chains list, threat scanning is unavailable. Ethereum, Base, Arbitrum, Optimism, and Polygon are among the covered chains.
Before your first transaction, run mm doctor and confirm both authenticated and initialized show true. If either is false, follow the hints in the output, then run it again.
Step 7: Make your first trade
Ask your agent for a small swap:
Swap 0.01 ETH to USDC on Base.
Your agent fetches a quote, shows you the route and output, then executes after you confirm. If you want a lower-stakes warm-up first, ask "What's my USDC balance?" or "What's the current price of ETH?" Read-only requests run without a confirmation prompt.
Guard Mode asks for your input in two places early on. You're prompted to set your rolling 24-hour outflow limit on your first transaction, and anything outside your allowlists or that limit pauses for two-factor approval. Your agent can't proceed on a flagged transaction until you respond. Approvals arrive as an email link if you signed in with Google or email, or as a push notification in MetaMask Mobile if you used QR (check the notifications menu if no push shows up).
If setup stalls
Start with mm doctor. It reports whether you're signed in and initialized, and its hints say what to fix. For the common error codes:
What you see
What to do
UNSUPPORTED_NODE
Upgrade to Node.js 22.18 or later, then run mm doctor again.
NOT_INITIALIZED
Run mm init, then mm doctor.
PAIRING_EXPIRED, INVALID_OTP, or a terminal timeout during browser sign-in
Run mm login browser again. Paste the CLI token shown after Authorize right away, not the email verification code.
MWP_TIMEOUT or MWP_CANCELLED during QR sign-in
Run mm login qr again, scan the new code, and approve promptly.
A different wallet address after signing in again
You used a different sign-in method. Run mm logout, then sign in with the method you used when you funded the wallet.
The troubleshooting page covers more cases.
Where to go next
Once your first trade lands, pick an asset class. For leveraged positions on Hyperliquid, see how to trade perps with MetaMask Agent Wallet. For same-chain swaps and cross-chain bridges, see how to swap and bridge tokens. For Polymarket, see how to trade prediction markets. The docs also cover yield vaults and x402 payments.
Frequently asked questions about setting up MetaMask Agent Wallet
- Not with a server wallet. In that mode, keys are managed and secured server-side in a trusted execution environment, so your agent can't access your main wallet, and you retain self-custody. With bring your own wallet, you supply a BIP-39 mnemonic and keys stay on your machine. Set it with the MM_MNEMONIC environment variable, never as a command-line flag.
Not with a server wallet. In that mode, keys are managed and secured server-side in a trusted execution environment, so your agent can't access your main wallet, and you retain self-custody. With bring your own wallet, you supply a BIP-39 mnemonic and keys stay on your machine. Set it with the MM_MNEMONIC environment variable, never as a command-line flag.
- Harnesses that support skills, such as Claude Code, Codex, Cursor, OpenClaw, and Hermes Agent. Even without skills, Agent Wallet can still be used—agents will fall back to using the --help command to figure out how to work the CLI.
Harnesses that support skills, such as Claude Code, Codex, Cursor, OpenClaw, and Hermes Agent. Even without skills, Agent Wallet can still be used—agents will fall back to using the --help command to figure out how to work the CLI.
- Not always. When your wallet's native balance can't cover gas, the CLI routes ERC-20 transfers and eligible swap quotes through a gasless relay, on chains that support it. Native-token sends aren't covered, and some flows still need native gas: a prediction market deposit needs POL on Polygon, for example. mm chains list --json shows a relaySupported flag for each chain.
Not always. When your wallet's native balance can't cover gas, the CLI routes ERC-20 transfers and eligible swap quotes through a gasless relay, on chains that support it. Native-token sends aren't covered, and some flows still need native gas: a prediction market deposit needs POL on Polygon, for example. mm chains list --json shows a relaySupported flag for each chain.
- Yes, with mm wallet trading-mode set guard or mm wallet trading-mode set beast. The change needs two-factor approval, and switching to Beast Mode prompts for confirmation first.
Yes, with mm wallet trading-mode set guard or mm wallet trading-mode set beast. The change needs two-factor approval, and switching to Beast Mode prompts for confirmation first.
- Run mm doctor: authenticated and initialized should both be true. Then run mm wallet address to confirm the address you funded and mm wallet balance to confirm your funds arrived.
Run mm doctor: authenticated and initialized should both be true. Then run mm wallet address to confirm the address you funded and mm wallet balance to confirm your funds arrived.
- No, not as of this writing.
No, not as of this writing.
- MetaMaskMetaMask, formerly Consensys Software Inc, is the world's largest self-custodial financial platform, giving people a single place to hold, spend, save and grow their money across both crypto and traditional assets. The company is building the consumer platform where that happens, bringing payments, savings, investing and digital assets together in one seamless experience. Having grown from the world's most widely used self-custodial wallet, MetaMask gives users direct control over their money and assets, with reach across approximately 190 countries. MetaMask has played a foundational role in Ethereum's growth since 2016. Today, MetaMask sits at the center of the onchain economy, building the operating system for Open Money and putting people in full control of their financial lives.Read all articles
MetaMask, formerly Consensys Software Inc, is the world's largest self-custodial financial platform, giving people a single place to hold, spend, save and grow their money across both crypto and traditional assets. The company is building the consumer platform where that happens, bringing payments, savings, investing and digital assets together in one seamless experience. Having grown from the world's most widely used self-custodial wallet, MetaMask gives users direct control over their money and assets, with reach across approximately 190 countries. MetaMask has played a foundational role in Ethereum's growth since 2016. Today, MetaMask sits at the center of the onchain economy, building the operating system for Open Money and putting people in full control of their financial lives.
- LATESTIntroducing MetaMask Transaction ShieldGet Transaction Protection and priority support for added peace of mind.
Introducing MetaMask Transaction Shield
Get Transaction Protection and priority support for added peace of mind.
- User updateMetaMask is responding to an incident affecting infrastructure. We have identified no immediate threat to MetaMask wallets.
User update
MetaMask is responding to an incident affecting infrastructure. We have identified no immediate threat to MetaMask wallets.
- ALPHANations League action continues + more: this week's trending marketsSpain leads the Nations League market while the Dodgers and Brewers lead the World Series race. This week's Alpha also tracks a $350M HYPE unlock, NEAR's 100%+ month, and earnings from Applied Digital, PepsiCo, plus AMD's $1 trillion run.
Nations League action continues + more: this week's trending markets
Spain leads the Nations League market while the Dodgers and Brewers lead the World Series race. This week's Alpha also tracks a $350M HYPE unlock, NEAR's 100%+ month, and earnings from Applied Digital, PepsiCo, plus AMD's $1 trillion run.
