> For the complete documentation index, see [llms.txt](https://docs.beamswap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.beamswap.io/metamask-agent-wallet.md).

# Use a MetaMask Agent Wallet

Give your AI a MetaMask Agent Wallet so it signs Beamswap calls and vault trades without a raw private key in its config.

[MetaMask Agent Wallet](https://docs.metamask.io/agent-wallet) gives an AI agent its own self-custodial wallet through the `mm` command line tool. The keys stay in MetaMask's secure enclave, never in your AI's config or chat. The wallet can sign messages, typed data and transactions, and pay x402 APIs, and MetaMask can ask you for two-factor approval, scan transactions for threats and simulate them first. On Base it is a good fit for Beamswap: your local MCP needs no `BEAMSWAP_WALLET_KEY`, and your own agent can trade an [Agent Vault](https://docs.beamswap.io/agent-vaults).

**Version note:** the signer mode and the own-agent vault tools below need `@beamswapio/mcp@0.3.0` or later.

## Set up the wallet

```sh
npm install -g @metamask/agent-wallet@latest
npx skills add MetaMask/agent-skills
mm login
mm init
mm wallet address
```

`mm login` signs you in to MetaMask. `mm init` creates the wallet. Choose a server wallet and turn on Guard Mode, which MetaMask recommends. `mm wallet address` prints the 0x address of your agent wallet. Fund it with a little USDC on Base for paid calls, and ETH if it will send transactions itself. Follow [MetaMask's guide](https://docs.metamask.io/agent-wallet) for the current steps.

## Connect the Beamswap MCP

Add the local server to your AI client with the signer set to MetaMask. Do not set `BEAMSWAP_WALLET_KEY`.

```json
{
  "mcpServers": {
    "beamswap": {
      "command": "npx",
      "args": ["-y", "@beamswapio/mcp@0.3.0"],
      "env": {
        "BEAMSWAP_SIGNER": "metamask"
      }
    }
  }
}
```

Paid calls are signed by your MetaMask Agent Wallet, so it needs USDC on Base. MetaMask may ask you for two-factor approval before it signs. Where your client shows the file path for [local mode](https://docs.beamswap.io/connect-your-ai), use this entry in its place.

## Trade an Agent Vault with your MetaMask agent

1. Open [Set up your agent](https://app.beamswap.io/agent/setup).
2. Choose **My own agent wallet** and paste the address from `mm wallet address`.
3. Set your limits, approve and fund the vault as usual.
4. Add the vault address to the MCP environment:

```json
"env": {
  "BEAMSWAP_SIGNER": "metamask",
  "BEAMSWAP_VAULT_ADDRESS": "0xYourVaultAddress"
}
```

This adds the vault tools: `vault_status`, `vault_trade`, `vault_limit_order`, `vault_cancel`, `vault_pause` and `vault_activity`. Your agent signs each trade through MetaMask and Beamswap's relayer pays the gas. Every trade stays inside the vault's rules. This needs `@beamswapio/mcp@0.3.0`.

## Swap from the wallet itself

If you would rather not use a vault, `swap_route` returns an unsigned transaction. Your agent sends it with `mm wallet send-transaction`. MetaMask simulates and scans the transaction before it is signed, and may ask for your approval. The swap spends the agent wallet's own balance, with none of the vault's limits, so keep that balance small.

## Pay per call without the MCP

Beamswap's paid API answers with an x402 `402` challenge. MetaMask's x402 helper can pay it directly from your agent wallet with USDC on Base, so any script or agent can call the [API](https://docs.beamswap.io/api-reference) without the MCP. See [MetaMask's x402 guide](https://docs.metamask.io/agent-wallet/guides/pay-for-apis-x402/) for the command.

## What protects you

* **Vault trades are limited by the vault.** The per-trade and daily USD limits, the price guard, the token list and owner-only withdrawal are enforced by the contract on Base. See [Review before you approve](https://docs.beamswap.io/safety-and-permissions).
* **MetaMask protects the key.** It keeps the key out of your AI's reach and adds two-factor approval and threat scanning to direct transactions.
* **They do not overlap on trades.** A vault trade is a signature, not a transaction from the wallet, so MetaMask's outflow limits do not count it. Only the vault's rules limit those trades.
* **To stop the agent,** set a new agent address in your [agent dashboard](https://app.beamswap.io/agent), or pause the vault. Pausing needs no cooperation from the agent.

Start with small limits and a small deposit.