For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 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.

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

Set up the wallet

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 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.

{
  "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, use this entry in its place.

Trade an Agent Vault with your MetaMask agent

  1. Choose My own agent wallet and paste the address from mm wallet address.

  2. Set your limits, approve and fund the vault as usual.

  3. Add the vault address to the MCP environment:

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 without the MCP. See MetaMask's x402 guide 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.

  • 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, or pause the vault. Pausing needs no cooperation from the agent.

Start with small limits and a small deposit.