---
name: migrate-agentcash
description: Manually inspect and migrate an AgentCash 1 disk-wallet installation to AgentCash Web, including an optional approved transfer of AC1 funds to the new Web wallet, without leaving both MCP generations or stale AgentCash skills in an agent's context. Use when a user mentions agentcash@0.17.0, npx agentcash, a global agentcash CLI, agentcash1-mcp, local AgentCash wallet files, duplicate AgentCash tools, transferring an AC1 balance, or moving from AC1 to the remote AgentCash MCP.
---

# Migrate AgentCash

Move a user to one active AgentCash generation while preserving their choice
about funds in the AC1 disk wallet. Perform discovery and account lookups
read-only, then group every authorized mutation into one migration plan and one
approval.

## Guardrails

- Never read, print, upload, or copy private keys or wallet-file contents.
- Never delete `~/.agentcash`, `~/.x402scan-mcp`, or another wallet directory
  during MCP cleanup.
- Ask for one approval covering the complete migration plan. Include the
  install and configuration changes, whether AC1 funds will move, each source
  account and amount, the authenticated same-network Web account as the
  destination, and a fee cap.
- Do not ask again for read-only address or balance lookups, an in-scope send,
  or post-migration verification.
- Before sending, display and verify the resolved destination address, network,
  amount, and quoted fees against the approved plan. Stop if any value falls
  outside that scope.
- Treat an unexpected destination, network, amount, fee, or retry as a revised
  plan that requires a new approval. This is an exception, not the normal flow.
- Never leave AC1 and AgentCash Web MCPs or skills active in the same agent
  context.
- Detect AC1 MCPs from command and arguments, not the server key. Names such as
  `agentcash1-mcp`, `payments`, and `wallet` may all invoke AC1.
- Keep the unscoped package pinned as `agentcash@0.17.0`. Do not repoint or
  upgrade it.
- Back up each config file before editing it. Remove only entries positively
  identified as AC1.

## Inventory Manually

Inspect the user's machine without modifying it.

Check for AC1 wallet files at:

```text
~/.agentcash/wallet.json
~/.agentcash/solana-wallet.json
~/.x402scan-mcp/wallet.json
~/.x402scan-mcp/solana-wallet.json
```

Report existence and paths only. Do not read the files.

Inspect MCP configuration in the installed clients, including:

- Claude Desktop:
  `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
  `%APPDATA%\Claude\claude_desktop_config.json` on Windows, or
  `~/.config/Claude/claude_desktop_config.json` on Linux.
- Claude Code: `~/.claude.json`.
- Codex: `${CODEX_HOME:-~/.codex}/config.toml`.
- Cursor: `~/.cursor/mcp.json`.
- Gemini CLI: `~/.gemini/settings.json`.
- Goose: `~/.config/goose/config.yaml`.
- OpenCode: `~/.config/opencode/opencode.json` or `opencode.jsonc`.
- Windsurf: `~/.codeium/windsurf/mcp_config.json`.
- Zed: `~/.config/zed/settings.json`.

Read only the MCP server blocks needed to classify entries. An AC1 entry invokes
unscoped `agentcash` in its command or arguments, including
`agentcash@latest`, `agentcash@0.17.0`, and `npx -y agentcash`. A Web entry uses
`https://mcp.agentcash.dev`. Do not classify from the server key.

Check exact `agentcash` skill directories under the detected agent's global and
project skill roots, including `.agents/skills`, `.claude/skills`,
`.codex/skills`, `.cursor/skills`, and `.gemini/skills`. Check whether a global
unscoped `agentcash` executable is on `PATH`.

Summarize:

- AC1 wallet paths.
- AC1 MCP entries, skills, and global executable.
- AgentCash Web MCP entries.
- Whether both generations are active.

Wallet files alone are not an active agent integration. Preserve them when the
user leaves funds in AC1.

## Record the AC1 Balance

Use only the pinned AC1 CLI's public, read-only commands. No approval is needed
for these lookups:

```bash
npx agentcash@0.17.0 balance
npx agentcash@0.17.0 accounts
```

Record the public addresses, networks, and balances. If the command is
unavailable or the balance cannot be verified, stop the money-moving portion
and preserve the wallet files.

## Approve One Migration Plan

After the read-only inventory and balance lookup, show one complete plan and ask
for approval exactly once:

1. Keep AC1 disk mode. Leave the installation in place, keep MCP commands
   pinned to `agentcash@0.17.0`, and do not install AgentCash Web.
2. Move to AgentCash Web. List the scoped CLI command, browser login, every
   configuration backup and replacement, stale skill removal, any missing Web
   network-wallet provisioning and MCP reauthorization, and any global
   unscoped package uninstall.

For a Web migration, include one funds choice in the same plan:

- Leave every AC1 balance in the preserved disk wallets.
- Transfer the listed amount from each recorded AC1 source account to the
  address returned by the authenticated AgentCash Web account on the same
  network. Include a maximum acceptable fee for each send.

The user's confirmation of this plan is the sole approval for every in-scope
installation, authentication, configuration edit, address lookup, transfer,
and verification step below. Do not split it into additional prompts.

Leaving funds does not require leaving the AC1 MCP or skill active. Preserve the
wallet files so the funds remain recoverable.

## Prepare AgentCash Web

Sign the CLI into the web account when CLI authentication is needed:

```bash
npx @agentcash/cli login
npx @agentcash/cli whoami
```

The CLI uses a browser device-authorization flow. Its session is distinct from
MCP authorization.

The remote MCP URL is:

```text
https://mcp.agentcash.dev
```

Do not add it to a client that still has an AC1 entry. Prepare the exact
replacement first. Do not configure `@agentcash/cli` or unscoped `agentcash` as
the new MCP command.

## Cut Over Atomically

Execute the approved changes without asking again:

1. Create a timestamped backup beside every config file that will change.
2. Quit or stop every affected agent client.
3. In one planned edit per client, remove every MCP entry whose command or
   arguments invoke unscoped `agentcash`, including
   `npx -y agentcash@latest` and pinned AC1 variants, and add exactly one remote
   AgentCash Web MCP entry.
4. Remove stale `agentcash` skill directories or links from the detected agent
   skill locations before restarting any client.
5. If the approved plan includes a detected global unscoped package, uninstall
   it with `npm uninstall -g agentcash`.
6. Preserve all wallet and session files by default.
7. Restart each affected client and let the remote MCP complete its own OAuth
   flow.

Do not remove unrelated servers based only on a name containing `cash`.

If remote authentication fails, do not restore AC1 while a Web entry or skill
is present. Either troubleshoot Web with AC1 still inactive, or revert
atomically by removing Web before restoring the pinned AC1 configuration.

For a fresh installation with no AC1 MCP, skill, or global executable, simply
add the remote MCP and complete its OAuth flow.

## Get AgentCash Web Addresses

After the new remote MCP authenticates, run the read-only account lookup without
asking for approval. Use the AgentCash Web `accounts` tool when available. If
the client exposes addresses through `get_balance`, use its returned public
addresses; otherwise use the signed-in Web wallet.

Record one authenticated destination address for every network with a nonzero
AC1 balance. Match Base to Base, Solana to Solana, and Tempo to Tempo. Validate
the address format and show the network-address mapping to the user. Never infer
an address, reuse an address under a different network label, or send across
networks. Stop the transfer for any network without a verified destination.

If the AC1 Solana balance is nonzero but `get_balance.accounts` has no
`network: "solana"` entry, do not treat the missing destination as a permanent
blocker. The Web account may predate automatic Solana-wallet provisioning:

1. Keep the AC1 Solana funds untouched.
2. Have the user open `https://app.agentcash.dev/wallet`. If the signed-in Web
   wallet does not show Solana, have them sign out and sign back into the same
   AgentCash Web account. The browser sign-in provisions missing network
   wallets; CLI login alone does not verify that provisioning occurred.
3. Reconnect or reauthorize the existing remote AgentCash Web MCP so its wallet
   authorization includes the provisioned Solana wallet. Do not add a second
   AgentCash MCP entry or reactivate AC1.
4. Run `get_balance` again and accept only the address from the account whose
   network is exactly `solana`.

This recovery is part of the approved Web authentication and destination
lookup, not approval to send to an unverified address. Attempt the provisioning
and reauthorization recovery once. If `get_balance` still has no verified
Solana account, stop only the Solana transfer, preserve its AC1 wallet and
funds, and continue verifying any other independently valid network transfers.

Show the network-address mapping as a progress update and continue under the
single approved plan.

## Transfer AC1 Funds Through `/api/send`

Use the pinned legacy CLI only after the AC1 MCP and skill are inactive. This
one-off wallet command does not reactivate the old agent integration. Never use
`agentcash@latest`.

For each network, first inspect the exact dynamic payment requirement without
sending:

```bash
npx agentcash@0.17.0 check https://agentcash.dev/api/send \
  --method POST \
  --body '{"address":"DESTINATION_ADDRESS","network":"NETWORK","amount":AMOUNT}'
```

Then show the user:

- The source AC1 public address and verified balance.
- The authenticated AgentCash Web destination address.
- The network.
- The exact USDC amount.
- The quoted service and network fees. If a fee cannot be determined, label it
  unknown instead of assuming zero.
- The exact command that will run.

Compare those details with the approved plan. Continue without another approval
only when the source and amount were listed, the destination is the
authenticated Web address on the same network, and the known fees do not exceed
the approved cap. Otherwise stop and present one revised plan for approval.

When every check matches, send through AgentCash's paid endpoint:

```bash
npx agentcash@0.17.0 fetch https://agentcash.dev/api/send \
  --method POST \
  --body '{"address":"DESTINATION_ADDRESS","network":"NETWORK","amount":AMOUNT}' \
  --payment-protocol x402 \
  --payment-network NETWORK \
  --max-amount AMOUNT
```

Use the exact lowercase network returned by the account tools as `NETWORK`.
Continue only when the check response offers a payment requirement for that
same network. The endpoint charges the matching legacy wallet and pays the body
address. Never send more than the verified balance. If the user requests the
full balance, confirm the exact numeric amount rather than substituting the word
`all`.

Treat a response containing payment information as paid even if the endpoint
returns an error. Do not retry automatically. A retry is outside the original
plan; check both wallet balances again and obtain approval for the revised plan.

Verify a successful response and record its transaction identifier. Recheck the
legacy and Web balances on that network without asking again. Never claim
success from the command's exit code alone.

## Verify

Repeat the manual inventory. Complete a Web migration only when no AC1 MCP,
skill, or global executable remains active and the remote MCP authenticates.
Preserved wallet files are expected when the user left funds behind.

If the user chose AC1 disk mode, complete only when no Web MCP was added and all
AC1 MCP commands are pinned to `agentcash@0.17.0`.

Report each attempted transfer's network, amount, destination, result, and
transaction identifier, or state that the funds were deliberately left in the
preserved wallet. Never claim that funds moved without a verified transaction
result.