MetaMask

Set up your agent wallet, fund it with test USDC and purchase your AgentRouter key.

Install the wallet

Use a terminal on your Mac or Linux computer. You need Node.js 22.18+, npm, Python 3 and Git. The purchase and inference steps also use curl, jq and uuidgen. Install missing tools before continuing. Run the wallet commands without sudo.

This guide uses MetaMask Agent Wallet 7.1.0. Keep the terminal open through setup and purchase.

Shell

mkdir -p "$HOME/.local/share/h07-metamask"
npx --yes --package=npm@10 npm install \
  --prefix "$HOME/.local/share/h07-metamask" \
  --save-exact @metamask/[email protected]

Expected result

The installation completes without an error. The next step checks the installed CLI.

Check the CLI

Add the installed CLI to this terminal's PATH and check it.

Shell

export PATH="$HOME/.local/share/h07-metamask/node_modules/.bin:$PATH"
mm doctor

Expected result

Check that cli is 7.1.0. Before sign-in, authenticated and initialized are false.

Get the payment helper

Download the official MetaMask payment helper at the tested revision. Keep this directory and the METAMASK_SKILL_DIR setting for the purchase step.

Shell

git clone --no-checkout https://github.com/MetaMask/agent-skills.git \
  "$HOME/.local/share/h07-metamask/agent-skills" &&
git -C "$HOME/.local/share/h07-metamask/agent-skills" checkout --detach \
  317df8eb6efc7cdecc867465bb17f96306759369

export METAMASK_SKILL_DIR="$HOME/.local/share/h07-metamask/agent-skills/skills/metamask-agent-wallet"
python3 "$METAMASK_SKILL_DIR/scripts/x402_pay.py" --help

Expected result

Help lists inspect, pay, mcp-inspect and mcp-sign.

Connect your phone

Scan the QR with MetaMask Mobile and approve the connection. Your phone identifies you to the Agent Wallet service. This does not copy your personal wallet's seed or transfer funds.

Keep the QR, login URL and tokens private. Your personal wallet and the agent wallet remain separate.

Shell

mm login qr

Expected result

The phone connection completes. Check authentication in the next step.

Check authentication

After approving the connection on your phone, check the wallet again.

Shell

mm doctor

Expected result

authenticated is true. initialized stays false until the next step.

Create the agent wallet

Choose Server Wallet, then Guard mode in the interactive setup.

MetaMask holds this agent wallet's signing key in a trusted execution environment on its infrastructure. Your computer requests signatures without downloading the private key. Wallet access depends on MetaMask's service. Local credentials are sensitive and are not a private-key backup.

Wallet architecture · Guard mode

Shell

mm init

Expected result

Setup completes. Check the wallet address, mode and allowed chains next.

Check wallet and network

Keep the agent wallet's address for funding. Use Base Sepolia only even if the default policy also allows mainnets.

A zero daily USD limit does not guarantee zero x402 spending. Signatures are excluded from that limit. A payment can proceed without a phone prompt, even in Guard mode. Review the offer and obtain the wallet owner's spending approval.

Spending-limit behavior

Shell

mm doctor
mm chains list
mm wallet show

Expected result

Authentication and initialization are true. Base Sepolia (84532) is listed, and the wallet shows guard mode with 84532 in allowed_chains.

Check testnet funds

Read token amounts under Base Sepolia. unpriced and totalValue: 0 can reflect missing testnet prices, not an empty wallet. USDC may be omitted when its balance is zero.

Shell

mm wallet balance --testnet-chain-ids 84532 \
  --token-contracts 0x036CbD53842c5426634e7929541eC2318f3dCF7e

Expected result

Read each token's amount. Have enough Base Sepolia test USDC for the inspected offer before purchasing.

Get test USDC

With the wallet owner's approval, open the Circle faucet. Select USDC and Base Sepolia, paste the agent wallet address from the wallet check and choose Send 20 USDC.

After confirmation, repeat the balance check. Use test tokens only. The documented x402 flow has the facilitator submit the transfer; it does not require ETH in your wallet.

MetaMask x402 guide

Expected result

After a successful 20-USDC faucet transfer to an initially empty wallet, the USDC amount is 20.

Read the purchase offer

This unpaid request returns HTTP 402 with a PAYMENT-REQUIRED header and an empty body. It neither signs nor pays. The header contains standard-base64 x402 v2 JSON; your wallet client reads it in the next step.

Check the current offer before authorizing payment: exact, Base Sepolia (eip155:84532), USDC asset 0x036CbD53842c5426634e7929541eC2318f3dCF7e, amount 1000000 (1 test USDC), and the recipient. Stop if the terms differ from what you intend to buy. The quote is for access credit, not the price of one model request.

No AgentRouter account or proprietary recovery header is required. The wallet owner still needs to authorize wallet setup and spending.

Shell

curl -sS -X POST https://api.agentrouter.cc/v1/purchase \
  -D - -o /dev/null

Expected result

HTTP 402 Payment Required, Cache-Control: no-store, a PAYMENT-REQUIRED header and an empty body. The decoded header has x402Version: 2, resource.url: /v1/purchase and an accepts array. Each option supplies its network, asset, amount, recipient and EIP-3009 signing metadata. A 402 error without that header is not a usable offer.

Prepare one wallet

Use the same wallet in the purchase step. These checks do not authorize a payment. Keep wallet/session output private.

The purchase command also uses jq to load the delivered key privately. Have at least 1 test USDC and inspect the offer's amount, network, asset and recipient. The wallet client handles signing; never paste a wallet private key into a prompt or this site.

Tested with MetaMask Agent Wallet 7.1.0 in server-wallet mode and its official payment helper. Complete vendor setup. Set METAMASK_SKILL_DIR to that helper's metamask-agent-wallet directory. It needs Python 3 and mm on PATH.

Expect authenticated/initialized and eligible: true for the offer. Eligibility alone does not prove settlement.

Shell

mm doctor
mm wallet balance --testnet-chain-ids 84532 \
  --token-contracts 0x036CbD53842c5426634e7929541eC2318f3dCF7e
python3 "${METAMASK_SKILL_DIR:?set the official helper directory}/scripts/x402_pay.py" inspect \
  https://api.agentrouter.cc/v1/purchase --method POST

Expected result

These readiness checks should not return a bearer key or settle a payment.

Compare the decoded offer with step 1. Do not proceed on missing funds, an unavailable wallet, an unsupported offer or unapproved terms. New wallet versions need their own compatibility check.

Buy once and keep the key

Run the block for your chosen wallet once, with the owner's spending approval. After buying, use the delivered key. Switching wallets is not another step and does not undo a purchase.

The command saves the full result in a new private directory and loads AGENTROUTER_KEY without displaying it. Keep the terminal open for inference. Do not run these commands with shell tracing, paste the result into model context, or put it in a served directory.

The client handles PAYMENT-SIGNATURE and the PAYMENT-RESPONSE receipt. If any command fails, times out, or delivery is uncertain, stop; do not rerun pay. Another invocation can create another purchase. Preserve the private response and receipt. These stock-client examples do not retain an optional recovery capability, so self-service lost-key recovery is not available for this flow. Never repay automatically to recover a key.

MetaMask's tested helper has no purchase-cap flag: inspect the current offer immediately before running pay --confirm. Its signature may authorize payment without another phone prompt.

Expect status: settled, the API body in resource, and the decoded settlement receipt.

Shell

umask 077
PURCHASE_DIR="$(mktemp -d "$HOME/agentrouter-purchase.XXXXXX")" &&
python3 "${METAMASK_SKILL_DIR:?set the official helper directory}/scripts/x402_pay.py" pay \
  https://api.agentrouter.cc/v1/purchase --method POST \
  --network eip155:84532 \
  --asset 0x036CbD53842c5426634e7929541eC2318f3dCF7e --confirm \
  >"$PURCHASE_DIR/result.json" 2>"$PURCHASE_DIR/error.log" &&
AGENTROUTER_KEY="$(jq -er '.resource.key | select(type == "string" and length > 0)' "$PURCHASE_DIR/result.json")" &&
export AGENTROUTER_KEY

Expected result

The API returns HTTP 200 with key, usage and PAYMENT-RESPONSE.

The commands export the opaque bearer key without printing it. A zero client exit code alone is insufficient: the response must contain the key and confirmed payment receipt. Keep the original response privately. Inspect the transaction through the Base Sepolia explorer, without sharing the bearer key.

Use your key

Continue to Discover models, then use the OpenAI-compatible API or Anthropic-compatible API. These steps are shared by both wallets.

Need help? Troubleshooting · Restore a MetaMask session