@arispay/payagent-mcp 2.8.0 → 3.1.0

package/dist/index.js

@@ -15,6 +15,7 @@ import {
   launchAgent,
   listAgents,
   payFetchDelegated,
+  payFetchLocal,
   renameStoredAgent,
   syncAgents
 } from "payagent";
@@ -37,22 +38,8 @@ function platformToolsEnabled(raw = process.env.PAYAGENT_MCP_PROFILE) {
 var arispayUrl = getArispayUrl(process.env.ARISPAY_URL);
 var legacyAgentKey = process.env.ARISPAY_AGENT_KEY;
 var legacyWalletAddress = process.env.PAYAGENT_WALLET;
-function resolveAgent(name) {
-  if (name) return getAgent(name);
-  const agents = listAgents();
-  return agents[0];
-}
-function resolveAgentKey(name) {
-  if (name) {
-    const stored = getAgent(name);
-    if (stored) return { key: stored.apiKey, source: `agent \`${name}\`` };
-    return void 0;
-  }
-  if (legacyAgentKey) return { key: legacyAgentKey, source: "ARISPAY_AGENT_KEY" };
-  const first = listAgents()[0];
-  if (first) return { key: first.apiKey, source: `agent \`${first.name}\`` };
-  return void 0;
-}
+var SELF_ENDUSER_EXTERNAL_ID = "self";
+var buyformeUrl = process.env.BUYFORME_URL?.replace(/\/$/, "") ?? "https://buyforme.arispay.app";
 function requireDevKey() {
   const key = getApiKey();
   if (!key) {
@@ -68,34 +55,357 @@ function textResult(text, isError = false) {
     ...isError ? { isError } : {}
   };
 }
+async function resolveWallet(client, name) {
+  const list = await client.listWallets();
+  return list.wallets.find((w) => w.name === name);
+}
+async function resolveSelfEndUserId(client) {
+  try {
+    const user = await client.getEndUserByExternalId(SELF_ENDUSER_EXTERNAL_ID);
+    return user.id;
+  } catch {
+    return void 0;
+  }
+}
 var server = new McpServer({
   name: "payagent",
-  version: "2.1.0"
+  version: "3.0.0"
 });
+server.tool(
+  "create_user",
+  "Cold-start in one call: create an ArisPay user account plus the master funding account. Safe to re-run \u2014 it recovers the existing account instead of creating duplicates.",
+  {
+    email: z.string().describe("Email for the new ArisPay account."),
+    name: z.string().optional().describe("Human name. Falls back to the email local-part.")
+  },
+  async ({ email, name }) => {
+    try {
+      const result = await bootstrapAgent({
+        email,
+        name,
+        arispayUrl: process.env.ARISPAY_URL,
+        clientId: "payagent-mcp-bootstrap"
+      });
+      const devKey = getApiKey();
+      if (devKey) {
+        const client = new DelegationClient(arispayUrl, devKey);
+        try {
+          await client.createEndUser({
+            externalId: SELF_ENDUSER_EXTERNAL_ID,
+            email,
+            findOrCreate: true
+          });
+        } catch {
+        }
+      }
+      const lines = [
+        `\u2713 Account: ${result.email}  (org \`${result.orgName}\`)`,
+        `\u2713 Master funding account ready.`,
+        "",
+        "Next steps:",
+        "  1. create_wallet({ name: 'Daily', perTx, daily, monthly })",
+        "  2. fund_wallet({ wallet: 'Daily', rail: 'europ' }) for SEPA / EUR\xD8P",
+        "     or fund_wallet({ wallet: 'Daily', rail: 'card' }) for card top-up."
+      ];
+      return textResult(lines.join("\n"));
+    } catch (err) {
+      if (err instanceof BootstrapError) {
+        return textResult(`create_user failed (${err.code}): ${err.message}`, true);
+      }
+      return textResult(
+        `create_user failed: ${err instanceof Error ? err.message : String(err)}`,
+        true
+      );
+    }
+  }
+);
+server.tool(
+  "create_wallet",
+  "Create a sub-wallet / spending profile. Sub-wallets draw from the master funding account and enforce per-transaction, daily, and monthly spend limits.",
+  {
+    name: z.string().describe("Human name for this sub-wallet, e.g. 'Daily' or 'Travel'."),
+    perTx: z.number().int().positive().describe("Per-transaction spend cap in cents."),
+    daily: z.number().int().positive().describe("Daily spend cap in cents."),
+    monthly: z.number().int().positive().describe("Monthly spend cap in cents."),
+    allowedDomains: z.array(z.string()).optional().describe("If provided, restrict this sub-wallet to paying only these domains.")
+  },
+  async ({ name, perTx, daily, monthly, allowedDomains }) => {
+    try {
+      const devKey = requireDevKey();
+      const client = new DelegationClient(arispayUrl, devKey);
+      const wallet = await client.createWallet({
+        name,
+        perTx,
+        daily,
+        monthly,
+        allowedDomains
+      });
+      const lines = [
+        `\u2713 Sub-wallet \`${wallet.name}\` created.`,
+        `  id: ${wallet.id}`,
+        `  limits: ${wallet.limits.perTx ?? "\u2014"}\xA2 / tx, ${wallet.limits.daily ?? "\u2014"}\xA2 / day, ${wallet.limits.monthly ?? "\u2014"}\xA2 / month`,
+        "",
+        `Fund it with fund_wallet({ wallet: "${wallet.name}", rail: "europ" | "card" }).`
+      ];
+      return textResult(lines.join("\n"));
+    } catch (err) {
+      return textResult(
+        `create_wallet failed: ${err instanceof Error ? err.message : String(err)}`,
+        true
+      );
+    }
+  }
+);
+server.tool(
+  "list_wallets",
+  "List all sub-wallets under this account.",
+  {},
+  async () => {
+    try {
+      const devKey = requireDevKey();
+      const client = new DelegationClient(arispayUrl, devKey);
+      const list = await client.listWallets();
+      if (!list.wallets.length) {
+        return textResult(
+          "No sub-wallets yet. Create one with create_wallet({ name, perTx, daily, monthly })."
+        );
+      }
+      const lines = list.wallets.map(
+        (w) => [
+          `\`${w.name}\` (${w.id})`,
+          `  status:  ${w.status}`,
+          `  limits:  ${w.limits.perTx ?? "\u2014"}\xA2 / tx, ${w.limits.daily ?? "\u2014"}\xA2 / day, ${w.limits.monthly ?? "\u2014"}\xA2 / month`,
+          `  balance: ${w.balance} ${w.balanceCurrency}`
+        ].join("\n")
+      );
+      return textResult(lines.join("\n\n"));
+    } catch (err) {
+      return textResult(
+        `list_wallets failed: ${err instanceof Error ? err.message : String(err)}`,
+        true
+      );
+    }
+  }
+);
+server.tool(
+  "fund_wallet",
+  "Add money to the master funding account so a sub-wallet can spend. rail='europ' opens the Schuman KYC / vIBAN flow in a browser; rail='card' mints a hosted card-setup URL.",
+  {
+    wallet: z.string().describe("Name of a sub-wallet (used only for handoff context)."),
+    rail: z.enum(["europ", "card"]).describe("Funding rail: 'europ' for SEPA/EUR\xD8P, 'card' for debit/credit card."),
+    amount: z.number().positive().optional().describe("Optional preset amount in dollars.")
+  },
+  async ({ wallet, rail, amount }) => {
+    try {
+      const devKey = requireDevKey();
+      const client = new DelegationClient(arispayUrl, devKey);
+      const resolved = await resolveWallet(client, wallet);
+      if (!resolved) {
+        return textResult(`No sub-wallet named \`${wallet}\`. Run list_wallets().`, true);
+      }
+      if (rail === "europ") {
+        const handoffUrl = `${buyformeUrl}/onboarding/fund-europ?agentId=${encodeURIComponent(
+          resolved.id
+        )}`;
+        const lines2 = [
+          `Fund the master wallet for \`${wallet}\` with EUR\xD8P via Schuman:`,
+          "",
+          `  ${handoffUrl}`,
+          "",
+          "Open that link in a browser to:",
+          "  1. Verify your identity with Schuman Financial (one-time KYC).",
+          "  2. Receive a dedicated SEPA vIBAN.",
+          "  3. Send EUR by bank transfer; Schuman mints EUR\xD8P once it clears.",
+          "",
+          "After the deposit clears, the master funding account is credited and this sub-wallet can spend."
+        ];
+        return textResult(lines2.join("\n"));
+      }
+      const endUserId = await resolveSelfEndUserId(client);
+      if (!endUserId) {
+        return textResult(
+          "No payer record found. Run create_user first, then retry fund_wallet with rail='card'.",
+          true
+        );
+      }
+      const session = await client.createCardSetupSession({ endUserId });
+      const lines = [
+        `Add a card to fund the master wallet for \`${wallet}\`:`,
+        "",
+        `  ${session.setupUrl}`,
+        "",
+        `  Expires at: ${session.expiresAt}`,
+        "",
+        "After the card is verified, you can top up. Card top-ups are not yet exposed via MCP; use the BuyForMe web app or the ArisPay dashboard for now."
+      ];
+      return textResult(lines.join("\n"));
+    } catch (err) {
+      return textResult(
+        `fund_wallet failed: ${err instanceof Error ? err.message : String(err)}`,
+        true
+      );
+    }
+  }
+);
+server.tool(
+  "get_balance",
+  "Show the master funding-account balance(s) and a sub-wallet's spend limits. If no wallet is named, lists all sub-wallets.",
+  {
+    wallet: z.string().optional().describe("Optional sub-wallet name. Omit to list all sub-wallets.")
+  },
+  async ({ wallet }) => {
+    try {
+      const devKey = requireDevKey();
+      const client = new DelegationClient(arispayUrl, devKey);
+      if (!wallet) {
+        const list = await client.listWallets();
+        if (!list.wallets.length) {
+          return textResult("No sub-wallets yet. Create one with create_wallet().");
+        }
+        const lines2 = list.wallets.map((w) => {
+          const lim = `limits: ${w.limits.perTx ?? "\u2014"}\xA2 / tx, ${w.limits.daily ?? "\u2014"}\xA2 / day, ${w.limits.monthly ?? "\u2014"}\xA2 / month`;
+          return `\`${w.name}\` \u2014 ${w.balance} ${w.balanceCurrency} \u2014 ${lim}`;
+        });
+        return textResult(lines2.join("\n"));
+      }
+      const resolved = await resolveWallet(client, wallet);
+      if (!resolved) {
+        return textResult(`No sub-wallet named \`${wallet}\`.`, true);
+      }
+      const bal = await client.getWalletBalance(resolved.id);
+      const lines = [
+        `Sub-wallet: \`${bal.wallet.name}\``,
+        `  status:  ${bal.wallet.status}`,
+        `  limits:  ${bal.wallet.limits.perTx ?? "\u2014"}\xA2 / tx, ${bal.wallet.limits.daily ?? "\u2014"}\xA2 / day, ${bal.wallet.limits.monthly ?? "\u2014"}\xA2 / month`,
+        "",
+        "Master funding accounts:"
+      ];
+      if (!bal.fundingAccounts.length) {
+        lines.push("  No funded accounts yet. Use fund_wallet() to add money.");
+      } else {
+        for (const acct of bal.fundingAccounts) {
+          lines.push(`  ${acct.currency}: ${acct.balance}\xA2 (${acct.provider ?? "internal"})`);
+        }
+      }
+      return textResult(lines.join("\n"));
+    } catch (err) {
+      return textResult(
+        `get_balance failed: ${err instanceof Error ? err.message : String(err)}`,
+        true
+      );
+    }
+  }
+);
+server.tool(
+  "pay_merchant",
+  "Pay a merchant from the master wallet through a sub-wallet. For balance-rail payments (from FundingAccount), merchantId is required. For card-rail payments, the user must have a verified card on file.",
+  {
+    wallet: z.string().describe("Name of the sub-wallet to spend through."),
+    merchantUrl: z.string().describe("Canonical merchant URL for this payment."),
+    amount: z.number().int().positive().describe("Amount in cents."),
+    memo: z.string().describe("Human-readable memo, e.g. 'T-shirt from getwatta.com'."),
+    merchantId: z.string().optional().describe("Required for balance-rail payments to a registered merchant."),
+    currency: z.string().optional().describe("Currency code. Default: USD."),
+    rail: z.enum(["balance", "card"]).optional().describe("Force balance or card rail. Default: server picks based on available funding.")
+  },
+  async ({ wallet, merchantUrl, amount, memo, merchantId, currency, rail }) => {
+    try {
+      const devKey = requireDevKey();
+      const client = new DelegationClient(arispayUrl, devKey);
+      const resolved = await resolveWallet(client, wallet);
+      if (!resolved) {
+        return textResult(`No sub-wallet named \`${wallet}\`.`, true);
+      }
+      const endUserId = await resolveSelfEndUserId(client);
+      if (!endUserId) {
+        return textResult(
+          "No payer record found. Run create_user first, then retry the payment.",
+          true
+        );
+      }
+      const payment = await client.createPayment(resolved.id, {
+        userId: endUserId,
+        amount,
+        currency: currency ?? "USD",
+        memo,
+        merchantUrl,
+        merchantId,
+        rail
+      });
+      const lines = [
+        `Payment ${payment.id}: ${payment.status}`,
+        `  rail:    ${payment.rail}`,
+        `  amount:  ${payment.amount}\xA2 ${payment.currency}`
+      ];
+      if (payment.merchantName) lines.push(`  merchant: ${payment.merchantName}`);
+      if (payment.txHash) lines.push(`  tx hash:  ${payment.txHash}`);
+      if (payment.spend) {
+        const fmtCap = (v) => v == null ? "no cap" : `${v}\xA2`;
+        lines.push(
+          `  budget:  ${fmtCap(payment.spend.remainingDaily)} left today, ${fmtCap(payment.spend.remainingMonthly)} this month`
+        );
+      }
+      if (payment.nextAction?.challengeUrl) {
+        lines.push(`  3DS challenge URL: ${payment.nextAction.challengeUrl}`);
+      }
+      if (payment.error) {
+        lines.push(`  error:   ${payment.error.code} \u2014 ${payment.error.message}`);
+      }
+      return textResult(lines.join("\n"), payment.status === "failed");
+    } catch (err) {
+      return textResult(
+        `pay_merchant failed: ${err instanceof Error ? err.message : String(err)}`,
+        true
+      );
+    }
+  }
+);
 server.tool(
   "pay_api",
-  "Make an HTTP request to a paid API, transparently paying any x402 (HTTP 402) challenge with USDC under the agent's spend limits. THE tool for fetching paid resources \u2014 never bypass a 402 or hand-roll payment.",
+  "Advanced: make an HTTP request to an x402-protected API, paying with USDC on Base via delegated signing. This is a separate rail from the wallet-centric balance/card flows.",
   {
-    url: z.string().describe("The full URL of the API endpoint to call"),
-    method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).default("GET").describe("HTTP method"),
-    headers: z.record(z.string(), z.string()).optional().describe("Additional HTTP headers"),
-    body: z.string().optional().describe("Request body (for POST/PUT/PATCH)"),
-    agent: z.string().optional().describe(
-      "Optional: name of a locally-stored agent to pay with. Defaults to ARISPAY_AGENT_KEY or the first stored agent."
-    )
+    url: z.string().describe("The full URL of the API endpoint to call."),
+    method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).default("GET"),
+    headers: z.record(z.string(), z.string()).optional(),
+    body: z.string().optional(),
+    agent: z.string().optional().describe("Optional name of a stored x402 payer agent.")
   },
   async ({ url, method, headers, body, agent }) => {
-    const resolved = resolveAgentKey(agent);
-    if (!resolved) {
+    const localKey = process.env.PAYAGENT_PRIVATE_KEY;
+    if (localKey) {
+      try {
+        const fetch402 = payFetchLocal({ privateKey: localKey });
+        const response = await fetch402(url, { method, headers, body });
+        const responseBody = await response.text();
+        return textResult(
+          [
+            `HTTP ${response.status} (paid locally \u2014 permissionless mode, no server-enforced limits)`,
+            "",
+            responseBody
+          ].join("\n")
+        );
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (looksLikeInsufficientFunds(message)) {
+          return textResult(
+            [
+              `Error: ${message}`,
+              "",
+              "The local wallet is out of USDC. Fund it on Base, or unset PAYAGENT_PRIVATE_KEY to use delegated custody."
+            ].join("\n"),
+            true
+          );
+        }
+        return textResult(`Error: ${message}`, true);
+      }
+    }
+    const stored = agent ? getAgent(agent) : listAgents()[0];
+    if (!stored?.apiKey) {
       return textResult(
         [
-          "No agent available. Cold-start in one call:",
-          '  bootstrap_agent({ email: "you@example.com", name: "<your-name>" })',
-          "",
-          "Or, if a developer key is already paired (`npx payagent init`):",
-          "  create_agent({ name, perTx, daily, monthly })",
-          "",
-          "Or set ARISPAY_AGENT_KEY for legacy single-agent mode."
+          "No x402 payer agent available. For wallet-centric payments use pay_merchant.",
+          "To create an x402 agent, use create_agent({ name, perTx, daily, monthly }).",
+          "Or set PAYAGENT_PRIVATE_KEY to pay with a local key (permissionless mode \u2014 no ArisPay account)."
         ].join("\n"),
         true
       );
@@ -104,14 +414,14 @@ server.tool(
       let paymentInfo;
       const fetch402 = payFetchDelegated({
         arispayUrl,
-        apiKey: resolved.key,
+        apiKey: stored.apiKey,
         onPayment: (info) => {
           paymentInfo = info;
         }
       });
       const response = await fetch402(url, { method, headers, body });
       const responseBody = await response.text();
-      const statusLine = paymentInfo ? `HTTP ${response.status} (paid ${paymentInfo.amountCents}\xA2 via ${resolved.source} \u2014 budget left: ${paymentInfo.remainingDaily}\xA2 today, ${paymentInfo.remainingMonthly}\xA2 this month)` : `HTTP ${response.status} (paid via ${resolved.source})`;
+      const statusLine = paymentInfo ? `HTTP ${response.status} (paid ${paymentInfo.amountCents}\xA2 via \`${stored.name}\` \u2014 budget left: ${paymentInfo.remainingDaily}\xA2 today, ${paymentInfo.remainingMonthly}\xA2 this month)` : `HTTP ${response.status} (paid via \`${stored.name}\`)`;
       return textResult([statusLine, "", responseBody].join("\n"));
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -120,9 +430,7 @@ server.tool(
           [
             `Error: ${message}`,
             "",
-            "This looks like the agent wallet is out of USDC. Fund it and retry:",
-            "  Use the `fund_agent` tool (rail='usdc' for the wallet address,",
-            "  or rail='europ' to fund via SEPA/EUR\xD8P in the browser)."
+            "The x402 agent wallet is out of USDC. Fund it with fund_agent({ name }) or switch to wallet-centric pay_merchant."
           ].join("\n"),
           true
         );
@@ -131,49 +439,17 @@ server.tool(
     }
   }
 );
-server.tool(
-  "check_wallet",
-  `Show the current agent's credentials, wallet address, and on-chain USDC balance \u2014 the quick "what state am I in" probe.`,
-  {
-    agent: z.string().optional().describe(
-      "Optional: name of a locally-stored agent. Defaults to legacy ARISPAY_WALLET mode."
-    )
-  },
-  async ({ agent }) => {
-    const resolved = resolveAgent(agent);
-    const walletAddress = resolved?.walletAddress ?? legacyWalletAddress;
-    const keyTail = resolved?.apiKey.slice(-4) ?? (legacyAgentKey ? legacyAgentKey.slice(-4) : void 0);
-    const lines = [`ArisPay URL: ${arispayUrl}`];
-    if (resolved) lines.push(`Agent:       ${resolved.name} (${resolved.agentId})`);
-    if (keyTail) lines.push(`Agent key:   ap_\u2026${keyTail}`);
-    if (walletAddress) {
-      lines.push(`Wallet:      ${walletAddress}`);
-      try {
-        const raw = await getUSDCBalance(walletAddress, resolved?.network ?? "base");
-        lines.push(`Balance:     ${formatUSDC(raw)} USDC on ${resolved?.network ?? "base"}`);
-      } catch (err) {
-        lines.push(
-          `Balance:     unavailable (${err instanceof Error ? err.message : String(err)})`
-        );
-      }
-    } else {
-      lines.push("", "No wallet known. Use `create_agent` or set PAYAGENT_WALLET for legacy mode.");
-    }
-    lines.push("", "Manage limits + full history: https://arispay.app/dashboard");
-    return textResult(lines.join("\n"));
-  }
-);
 server.tool(
   "create_agent",
-  "Provision an additional x402 payment agent (wallet + spend limits) under the already-paired developer account.",
+  "Advanced: provision an x402 payer agent with its own Base USDC wallet. Use create_wallet instead unless you specifically need to pay x402-protected HTTP resources.",
   {
-    name: z.string().describe("Local identifier for this agent. Used by later tools."),
+    name: z.string().describe("Local identifier for this x402 agent."),
     perTx: z.number().int().positive().describe("Per-transaction spend cap in cents."),
     daily: z.number().int().positive().describe("Daily spend cap in cents."),
     monthly: z.number().int().positive().describe("Monthly spend cap in cents."),
-    allowedDomains: z.array(z.string()).optional().describe("If provided, restrict this agent to paying only these domains."),
-    network: z.enum(["base", "base-sepolia", "ethereum", "polygon"]).default("base").describe("EVM network the agent pays on."),
-    agentType: z.string().optional().describe('Optional metadata label (e.g. "hermes").')
+    allowedDomains: z.array(z.string()).optional(),
+    network: z.enum(["base", "base-sepolia", "ethereum", "polygon"]).default("base"),
+    agentType: z.string().optional()
   },
   async ({ name, perTx, daily, monthly, allowedDomains, network, agentType }) => {
     try {
@@ -186,13 +462,13 @@ server.tool(
         agentType
       });
       const lines = [
-        `\u2713 Agent \`${name}\` created.`,
+        `\u2713 x402 agent \`${name}\` created.`,
         `  Agent ID:  ${agent.agentId}`,
         `  Wallet:    ${agent.walletAddress}`,
         `  Network:   ${agent.network}`,
         `  Limits:    ${perTx}\xA2 / tx, ${daily}\xA2 / day, ${monthly}\xA2 / month`,
         "",
-        `  Fund the wallet with USDC on ${agent.network}, then call \`get_balance\` with name="${name}".`
+        `  Fund the wallet with USDC on ${agent.network}, then call get_balance_agent with name="${name}".`
       ];
       return textResult(lines.join("\n"));
     } catch (err) {
@@ -203,57 +479,35 @@ server.tool(
     }
   }
 );
-var buyformeUrl = process.env.BUYFORME_URL?.replace(/\/$/, "") ?? "https://buyforme.arispay.app";
 server.tool(
   "fund_agent",
-  "Get funding instructions for an agent's wallet. Use rail='usdc' for the direct USDC deposit address on Base, or rail='europ' for a browser handoff to complete Schuman identity verification and receive a SEPA vIBAN that credits EUR\xD8P.",
+  "Advanced: get the USDC deposit address for an x402 payer agent.",
   {
-    name: z.string().describe("Name of a locally-stored agent."),
-    rail: z.enum(["usdc", "europ"]).default("usdc").describe(
-      "Funding rail: 'usdc' sends stablecoin directly to the agent wallet; 'europ' opens the BuyForMe EUR\xD8P onboarding flow in a browser to verify identity and get a vIBAN."
-    )
+    name: z.string().describe("Name of a locally-stored x402 agent.")
   },
-  async ({ name, rail }) => {
+  async ({ name }) => {
     const stored = getAgent(name);
-    if (!stored) return textResult(`No locally-stored agent named \`${name}\`.`, true);
-    if (rail === "europ") {
-      const handoffUrl = `${buyformeUrl}/onboarding/fund-europ?agentId=${encodeURIComponent(
-        stored.agentId
-      )}`;
-      const lines2 = [
-        `Fund \`${name}\` with EUR\xD8P via Schuman:`,
-        "",
-        `  ${handoffUrl}`,
-        "",
-        "Open that link in a browser to:",
-        "  1. Verify your identity with Schuman Financial (one-time KYC).",
-        "  2. Receive a dedicated SEPA vIBAN.",
-        "  3. Send EUR by bank transfer; Schuman mints EUR\xD8P to your wallet once it clears.",
-        "",
-        "After the deposit clears, call `get_balance` to confirm the agent's USDC balance."
-      ];
-      return textResult(lines2.join("\n"));
-    }
+    if (!stored) return textResult(`No x402 agent named \`${name}\`.`, true);
     const lines = [
-      `Fund \`${name}\` by sending USDC on ${stored.network ?? "base"} to:`,
+      `Fund x402 agent \`${name}\` by sending USDC on ${stored.network ?? "base"} to:`,
       "",
       `  ${stored.walletAddress}`,
       "",
       "Only send USDC on the network shown above. Other tokens or networks may be lost.",
-      "Call `get_balance` when the deposit lands."
+      "Call get_balance_agent when the deposit lands."
     ];
     return textResult(lines.join("\n"));
   }
 );
 server.tool(
-  "get_balance",
-  "Server-side USDC balance + funding status for one named agent.",
+  "get_balance_agent",
+  "Advanced: on-chain USDC balance for an x402 payer agent.",
   {
-    name: z.string().describe("Name of a locally-stored agent.")
+    name: z.string().describe("Name of a locally-stored x402 agent.")
   },
   async ({ name }) => {
     const stored = getAgent(name);
-    if (!stored) return textResult(`No locally-stored agent named \`${name}\`.`, true);
+    if (!stored) return textResult(`No x402 agent named \`${name}\`.`, true);
     try {
       const devKey = requireDevKey();
       const client = new DelegationClient(arispayUrl, devKey);
@@ -267,7 +521,72 @@ server.tool(
       return textResult(lines.join("\n"));
     } catch (err) {
       return textResult(
-        `get_balance failed: ${err instanceof Error ? err.message : String(err)}`,
+        `get_balance_agent failed: ${err instanceof Error ? err.message : String(err)}`,
+        true
+      );
+    }
+  }
+);
+server.tool(
+  "list_agents",
+  "Advanced: list x402 payer agents with on-chain wallets.",
+  {
+    withBalance: z.boolean().optional().describe("Fetch on-chain USDC balance per agent.")
+  },
+  async ({ withBalance }) => {
+    const devKey = getApiKey();
+    if (!devKey) {
+      return textResult("No developer key found. Run create_user or npx payagent init.");
+    }
+    try {
+      const result = await syncAgents({ includeBalance: withBalance === true });
+      if (!result.agents.length) {
+        return textResult("No x402 agents found. Use create_agent to provision one.");
+      }
+      const lines = result.agents.map((a) => {
+        const balanceLine = a.usdcBalance !== void 0 ? `  balance:   ${formatUSDC(BigInt(a.usdcBalance || "0"))} USDC` : null;
+        return [
+          a.name,
+          `  agent id:  ${a.agentId}`,
+          `  wallet:    ${a.walletAddress}`,
+          `  network:   ${a.network}`,
+          `  limits:    ${a.limits.maxPerTx}\xA2 / tx, ${a.limits.maxDaily}\xA2 / day, ${a.limits.maxMonthly}\xA2 / month`,
+          ...balanceLine ? [balanceLine] : []
+        ].join("\n");
+      });
+      return textResult(lines.join("\n\n"));
+    } catch (err) {
+      return textResult(
+        `list_agents failed: ${err instanceof Error ? err.message : String(err)}`,
+        true
+      );
+    }
+  }
+);
+server.tool(
+  "rename_agent",
+  "Advanced: rename an x402 payer agent.",
+  {
+    name: z.string().describe("Current local name of the x402 agent."),
+    newName: z.string().describe("New name.")
+  },
+  async ({ name, newName }) => {
+    if (name === newName) {
+      return textResult(`Agent \`${name}\` already has that name.`);
+    }
+    const stored = getAgent(name);
+    if (!stored) {
+      return textResult(`No x402 agent named \`${name}\`.`, true);
+    }
+    try {
+      const devKey = requireDevKey();
+      const client = new DelegationClient(arispayUrl, devKey);
+      const result = await client.renameAgent(stored.agentId, newName);
+      renameStoredAgent(name, result.name);
+      return textResult(`\u2713 Renamed \`${name}\` \u2192 \`${result.name}\`.`);
+    } catch (err) {
+      return textResult(
+        `rename_agent failed: ${err instanceof Error ? err.message : String(err)}`,
         true
       );
     }
@@ -276,24 +595,22 @@ server.tool(
 if (platformToolsEnabled()) {
   server.tool(
     "create_enduser",
-    "Platform mode: register an end-customer (EndUser) under your account, keyed by your own externalId.",
+    "Platform mode: register an end-customer under your account.",
     {
-      externalId: z.string().describe("Your own stable id for this customer (e.g. `tg:12345`)."),
-      email: z.string().optional().describe("Optional email for compliance / receipts."),
-      findOrCreate: z.boolean().optional().describe("If true, return the existing user instead of erroring on externalId collision.")
+      externalId: z.string().describe("Your own stable id for this customer."),
+      email: z.string().optional(),
+      findOrCreate: z.boolean().optional()
     },
     async ({ externalId, email, findOrCreate }) => {
       try {
         const devKey = requireDevKey();
         const client = new DelegationClient(arispayUrl, devKey);
         const user = await client.createEndUser({ externalId, email, findOrCreate });
-        const lines = [
-          `\u2713 End-user \`${externalId}\` ready.`,
-          `  ArisPay id:   ${user.id}`,
-          `  Has card:     ${user.hasPaymentMethod ? "yes" : "no"}`,
-          `  Has wallet:   ${user.hasWallet ? "yes" : "no"}`
-        ];
-        return textResult(lines.join("\n"));
+        return textResult(
+          `\u2713 End-user \`${externalId}\` ready.
+  ArisPay id: ${user.id}
+  Has card: ${user.hasPaymentMethod ? "yes" : "no"}`
+        );
       } catch (err) {
         return textResult(
           `create_enduser failed: ${err instanceof Error ? err.message : String(err)}`,
@@ -304,10 +621,10 @@ if (platformToolsEnabled()) {
   );
   server.tool(
     "attach_card_for_user",
-    "Platform mode: mint a hosted card-entry URL for an end-user (ArisPay handles tokenization + 3DS).",
+    "Platform mode: mint a hosted card-entry URL for an end-user.",
     {
-      userId: z.string().describe("The ArisPay-internal end-user id (not externalId)."),
-      agentName: z.string().optional().describe("Optional locally-stored agent name to scope the card-setup session to.")
+      userId: z.string().describe("ArisPay-internal end-user id."),
+      agentName: z.string().optional().describe("Optional x402 agent name to scope the session to.")
     },
     async ({ userId, agentName }) => {
       try {
@@ -315,17 +632,11 @@ if (platformToolsEnabled()) {
         const client = new DelegationClient(arispayUrl, devKey);
         const agentId = agentName ? getAgent(agentName)?.agentId : void 0;
         const session = await client.createCardSetupSession({ endUserId: userId, agentId });
-        const lines = [
-          `Card-entry URL for user \`${userId}\`:`,
-          "",
-          `  ${session.setupUrl}`,
-          "",
-          `  Expires at: ${session.expiresAt}`,
-          "",
-          "Share this URL with the end-user. They enter the card on ArisPay's hosted page; we handle tokenization + 3DS.",
-          "Call `get_user_status` afterwards to confirm the card is attached."
-        ];
-        return textResult(lines.join("\n"));
+        return textResult(
+          [`Card-entry URL:`, `  ${session.setupUrl}`, `  Expires at: ${session.expiresAt}`].join(
+            "\n"
+          )
+        );
       } catch (err) {
         return textResult(
           `attach_card_for_user failed: ${err instanceof Error ? err.message : String(err)}`,
@@ -336,22 +647,20 @@ if (platformToolsEnabled()) {
   );
   server.tool(
     "set_user_limits",
-    "Platform mode: set per-(user, agent) spend caps in integer cents plus MCC allow/block rules.",
+    "Platform mode: set per-(user, agent) spend caps.",
     {
-      userId: z.string().describe("ArisPay-internal end-user id."),
-      agentName: z.string().describe("Locally-stored agent name."),
-      perTx: z.number().int().optional().describe("Per-transaction cap in cents. Omit to inherit agent defaults."),
-      daily: z.number().int().optional().describe("Daily cap in cents."),
-      monthly: z.number().int().optional().describe("Monthly cap in cents."),
-      allowedMcc: z.array(z.string()).optional().describe("Allowed Merchant Category Codes."),
-      blockedMcc: z.array(z.string()).optional().describe("Blocked MCCs.")
+      userId: z.string(),
+      agentName: z.string(),
+      perTx: z.number().int().optional(),
+      daily: z.number().int().optional(),
+      monthly: z.number().int().optional(),
+      allowedMcc: z.array(z.string()).optional(),
+      blockedMcc: z.array(z.string()).optional()
     },
     async ({ userId, agentName, perTx, daily, monthly, allowedMcc, blockedMcc }) => {
       try {
         const stored = getAgent(agentName);
-        if (!stored) {
-          return textResult(`No locally-stored agent named \`${agentName}\`.`, true);
-        }
+        if (!stored) return textResult(`No x402 agent named \`${agentName}\`.`, true);
         const devKey = requireDevKey();
         const client = new DelegationClient(arispayUrl, devKey);
         const limit = await client.setUserLimits(userId, {
@@ -363,10 +672,7 @@ if (platformToolsEnabled()) {
           blockedMerchantCategories: blockedMcc
         });
         return textResult(
-          [
-            `\u2713 Limits set for \`${userId}\` on agent \`${agentName}\`.`,
-            `  per-tx ${limit.maxPerTransaction ?? "inherit"}\xA2, daily ${limit.maxDaily ?? "inherit"}\xA2, monthly ${limit.maxMonthly ?? "inherit"}\xA2`
-          ].join("\n")
+          `\u2713 Limits set. per-tx ${limit.maxPerTransaction ?? "inherit"}\xA2, daily ${limit.maxDaily ?? "inherit"}\xA2, monthly ${limit.maxMonthly ?? "inherit"}\xA2`
         );
       } catch (err) {
         return textResult(
@@ -378,9 +684,9 @@ if (platformToolsEnabled()) {
   );
   server.tool(
     "get_user_status",
-    "Platform mode: report an end-user's card, wallet, and payment readiness.",
+    "Platform mode: report an end-user's card and wallet readiness.",
     {
-      userId: z.string().describe("ArisPay-internal end-user id.")
+      userId: z.string()
     },
     async ({ userId }) => {
       try {
@@ -389,21 +695,9 @@ if (platformToolsEnabled()) {
         const user = await client.getEndUser(userId);
         const lines = [
           `${user.externalId} (${user.id})`,
-          `  email:    ${user.email ?? "\u2014"}`,
-          `  card:     ${user.hasPaymentMethod ? `${user.cardBrand ?? "card"} \u2026${user.cardLast4 ?? "????"}` : "\u2014"}`,
-          `  wallet:   ${user.walletAddress ?? "\u2014"}${user.walletChain ? ` on ${user.walletChain}` : ""}`
+          `  card:   ${user.hasPaymentMethod ? `${user.cardBrand ?? "card"} \u2026${user.cardLast4 ?? "????"}` : "\u2014"}`,
+          `  wallet: ${user.walletAddress ?? "\u2014"}${user.walletChain ? ` on ${user.walletChain}` : ""}`
         ];
-        if (user.hasWallet) {
-          try {
-            const w = await client.getWalletStatus(userId);
-            lines.push(`  balance:   ${w.usdcBalance} USDC base units`);
-            lines.push(
-              `  allowance: ${w.usdcAllowance} (${w.allowanceSufficient ? "ok" : "insufficient"})`
-            );
-            lines.push(`  ready:     ${w.ready}`);
-          } catch {
-          }
-        }
         return textResult(lines.join("\n"));
       } catch (err) {
         return textResult(
@@ -413,231 +707,32 @@ if (platformToolsEnabled()) {
       }
     }
   );
-  server.tool(
-    "pay_merchant",
-    "Direct payment to a known merchant via ArisPay rails (card / crypto / balance / MPP) when you already know the amount. For x402-protected HTTP resources use `pay_api` instead.",
-    {
-      agentName: z.string().describe("Name of the locally-stored agent making the payment."),
-      merchantUrl: z.string().describe("Canonical merchant URL (stored on the payment record)."),
-      amount: z.number().int().positive().describe("Amount in cents."),
-      memo: z.string().describe("Human-readable memo attached to the payment."),
-      userId: z.string().optional().describe("Optional ArisPay end-user id. Required when the agent is in platform mode."),
-      rail: z.enum(["card", "crypto", "balance", "mpp"]).optional().describe("Force a specific rail. Default: server-picked based on agent mode + userId."),
-      merchantName: z.string().optional().describe("Optional human-readable merchant name."),
-      merchantCategoryCode: z.string().optional().describe("MCC for spend-limit enforcement.")
-    },
-    async ({
-      agentName,
-      merchantUrl,
-      amount,
-      memo,
-      userId,
-      rail,
-      merchantName,
-      merchantCategoryCode
-    }) => {
-      try {
-        const stored = getAgent(agentName);
-        if (!stored) {
-          return textResult(`No locally-stored agent named \`${agentName}\`.`, true);
-        }
-        const devKey = requireDevKey();
-        const client = new DelegationClient(arispayUrl, devKey);
-        const payment = await client.createPayment(stored.agentId, {
-          amount,
-          memo,
-          merchantUrl,
-          merchantName,
-          merchantCategoryCode,
-          userId,
-          rail
-        });
-        const lines = [
-          `Payment ${payment.id}: ${payment.status}`,
-          `  rail:    ${payment.rail}`,
-          `  amount:  ${payment.amount}\xA2 ${payment.currency}`
-        ];
-        if (payment.merchantName) lines.push(`  merchant: ${payment.merchantName}`);
-        if (payment.txHash) lines.push(`  tx hash:  ${payment.txHash}`);
-        if (payment.spend) {
-          const fmtCap = (v) => v == null ? "no cap" : `${v}\xA2`;
-          lines.push(
-            `  budget:  ${fmtCap(payment.spend.remainingDaily)} left today, ${fmtCap(payment.spend.remainingMonthly)} this month`
-          );
-        }
-        if (payment.nextAction) {
-          lines.push(`  next action: ${payment.nextAction.type}`);
-          if (payment.nextAction.challengeUrl) {
-            lines.push(`  3DS challenge URL: ${payment.nextAction.challengeUrl}`);
-          }
-        }
-        if (payment.error) {
-          lines.push(`  error:   ${payment.error.code} \u2014 ${payment.error.message}`);
-        }
-        return textResult(lines.join("\n"), payment.status === "failed");
-      } catch (err) {
-        return textResult(
-          `pay_merchant failed: ${err instanceof Error ? err.message : String(err)}`,
-          true
-        );
-      }
-    }
-  );
 }
 server.tool(
-  "bootstrap_agent",
-  "Cold-start in one call: create (or recover) an ArisPay account plus a payment agent from just an email. Run this first on a fresh machine; safe to re-run \u2014 it recovers the existing agent and wallet set instead of creating duplicates.",
-  {
-    email: z.string().describe("Email for the new ArisPay developer account."),
-    name: z.string().optional().describe("Human name. Falls back to the email local-part."),
-    orgName: z.string().optional().describe(`Workspace / org name. Falls back to "<name>'s Team".`),
-    agentName: z.string().optional().describe('Local name for the provisioned agent. Default: "default".'),
-    perTx: z.number().int().positive().optional().describe("Per-tx cap in cents. Default: 50."),
-    daily: z.number().int().positive().optional().describe("Daily cap in cents. Default: 1000."),
-    monthly: z.number().int().positive().optional().describe("Monthly cap in cents. Default: 10000."),
-    allowedDomains: z.array(z.string()).optional().describe("Domains the agent may pay. Empty = unrestricted.")
-  },
-  async ({ email, name, orgName, agentName, perTx, daily, monthly, allowedDomains }) => {
-    try {
-      const result = await bootstrapAgent({
-        email,
-        name,
-        orgName,
-        agentName,
-        limits: { perTx, daily, monthly },
-        allowedDomains,
-        arispayUrl: process.env.ARISPAY_URL,
-        clientId: "payagent-mcp-bootstrap"
-      });
-      const lines = [
-        `\u2713 Account: ${result.email}  (org \`${result.orgName}\`)`,
-        `\u2713 Agent:   ${result.agentName}  (${result.agentId})`,
-        `  Wallet:  ${result.walletAddress}  (${result.network})`,
-        `  Limits:  ${result.limits.perTx}\xA2 / tx, ${result.limits.daily}\xA2 / day, ${result.limits.monthly}\xA2 / month`,
-        "",
-        `Fund the wallet by sending USDC on ${result.network} to ${result.walletAddress}.`,
-        `Or call \`fund_agent\` with name="${result.agentName}" and rail="usdc" or rail="europ".`
-      ];
-      if (result.pairing) {
-        lines.push("");
-        lines.push("\u{1F4F1} Open BuyForMe on your phone (signs you into the same account):");
-        lines.push(`   ${result.pairing.url}`);
-        lines.push(`   Link expires: ${result.pairing.expiresAt}`);
-      }
-      return textResult(lines.join("\n"));
-    } catch (err) {
-      if (err instanceof BootstrapError) {
-        return textResult(`bootstrap_agent failed (${err.code}): ${err.message}`, true);
-      }
-      return textResult(
-        `bootstrap_agent failed: ${err instanceof Error ? err.message : String(err)}`,
-        true
-      );
-    }
-  }
-);
-server.tool(
-  "list_agents",
-  "List all wallets under this account (server-authoritative; rehydrates the local cache).",
+  "check_wallet",
+  "Legacy diagnostic for x402 payer agents. Use get_balance for wallet-centric balances.",
   {
-    withBalance: z.boolean().optional().describe(
-      "When true, fetch on-chain USDC balance per agent (adds one round-trip per wallet)."
-    )
+    agent: z.string().optional().describe("Optional name of a locally-stored x402 agent.")
   },
-  async ({ withBalance }) => {
-    const devKey = getApiKey();
-    if (!devKey) {
-      const local = listAgents();
-      if (!local.length) {
-        return textResult(
-          "No developer key set and no agents cached locally. Run `bootstrap_agent` or set ARISPAY_API_KEY."
-        );
-      }
-      const lines = local.map(
-        (a) => [
-          a.name,
-          `  agent id:  ${a.agentId}`,
-          `  wallet:    ${a.walletAddress}`,
-          `  network:   ${a.network ?? "base"}`,
-          `  limits:    ${a.limits.perTx}\xA2 / tx, ${a.limits.daily}\xA2 / day, ${a.limits.monthly}\xA2 / month`,
-          `  created:   ${a.createdAt}`,
-          "  (local cache only \u2014 set ARISPAY_API_KEY to sync from the server)"
-        ].join("\n")
-      );
-      return textResult(lines.join("\n\n"));
-    }
-    try {
-      const result = await syncAgents({ includeBalance: withBalance === true });
-      if (!result.agents.length) {
-        return textResult(
-          "No wallets found under this developer key. Create one with `create_agent` or `bootstrap_agent`."
-        );
+  async ({ agent }) => {
+    const stored = agent ? getAgent(agent) : listAgents()[0];
+    const walletAddress = stored?.walletAddress ?? legacyWalletAddress;
+    const keyTail = stored?.apiKey.slice(-4) ?? (legacyAgentKey ? legacyAgentKey.slice(-4) : void 0);
+    const lines = [`ArisPay URL: ${arispayUrl}`];
+    if (stored) lines.push(`Agent:       ${stored.name} (${stored.agentId})`);
+    if (keyTail) lines.push(`Agent key:   ap_\u2026${keyTail}`);
+    if (walletAddress) {
+      lines.push(`Wallet:      ${walletAddress}`);
+      try {
+        const raw = await getUSDCBalance(walletAddress, stored?.network ?? "base");
+        lines.push(`Balance:     ${formatUSDC(raw)} USDC on ${stored?.network ?? "base"}`);
+      } catch (err) {
+        lines.push(`Balance:     unavailable (${err instanceof Error ? err.message : String(err)})`);
       }
-      const lines = result.agents.map((a) => {
-        const balanceLine = a.usdcBalance !== void 0 ? `  balance:   ${formatUSDC(BigInt(a.usdcBalance || "0"))} USDC` : null;
-        const fundedLine = a.fundedAt ? `  funded:    ${a.fundedAt}` : "  funded:    not yet";
-        const domainsLine = a.allowedDomains.length ? `  domains:   ${a.allowedDomains.join(", ")}` : "  domains:   (unrestricted)";
-        const suspendedLine = a.suspended ? "  status:    SUSPENDED" : null;
-        return [
-          a.name,
-          `  agent id:  ${a.agentId}`,
-          `  wallet:    ${a.walletAddress}`,
-          `  network:   ${a.network}`,
-          `  limits:    ${a.limits.maxPerTx}\xA2 / tx, ${a.limits.maxDaily}\xA2 / day, ${a.limits.maxMonthly}\xA2 / month`,
-          domainsLine,
-          fundedLine,
-          ...balanceLine ? [balanceLine] : [],
-          ...suspendedLine ? [suspendedLine] : [],
-          `  created:   ${a.createdAt}`
-        ].join("\n");
-      });
-      return textResult(
-        `${result.agents.length} wallet${result.agents.length === 1 ? "" : "s"} under this account (synced from server):
-
-${lines.join("\n\n")}`
-      );
-    } catch (err) {
-      return textResult(
-        `list_agents failed: ${err instanceof Error ? err.message : String(err)}`,
-        true
-      );
-    }
-  }
-);
-server.tool(
-  "rename_agent",
-  "Rename an agent on the server and in the local cache (names are unique per account).",
-  {
-    name: z.string().describe("Current local name of the agent to rename."),
-    newName: z.string().describe(
-      "New name. Letters, numbers, spaces, hyphens, underscores, dots. 1-64 chars. Must be unique per account."
-    )
-  },
-  async ({ name, newName }) => {
-    if (name === newName) {
-      return textResult(`Agent \`${name}\` already has that name \u2014 nothing to do.`);
-    }
-    const stored = getAgent(name);
-    if (!stored) {
-      return textResult(
-        `No locally-cached agent named \`${name}\`. Run \`list_agents\` first to sync, or check the spelling.`,
-        true
-      );
-    }
-    try {
-      const devKey = requireDevKey();
-      const client = new DelegationClient(arispayUrl, devKey);
-      const result = await client.renameAgent(stored.agentId, newName);
-      renameStoredAgent(name, result.name);
-      return textResult(
-        `\u2713 Renamed \`${name}\` \u2192 \`${result.name}\`. Wallet ${result.walletAddress ?? stored.walletAddress} is unchanged.`
-      );
-    } catch (err) {
-      return textResult(
-        `rename_agent failed: ${err instanceof Error ? err.message : String(err)}`,
-        true
-      );
+    } else {
+      lines.push("", "No wallet known.");
     }
+    return textResult(lines.join("\n"));
   }
 );
 async function main() {