mpp32-mcp-server 1.2.3 → 1.3.1

package/CHANGELOG.md

@@ -4,6 +4,98 @@ All notable changes to `mpp32-mcp-server` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1] - 2026-05-15
+
+### Fixed
+
+* **Diagnostics tool referenced non-existent `query_intelligence`.** The
+  `get_mpp32_diagnostics` "Ready to pay" message told users to try
+  `query_intelligence`, which was never a tool name. Now correctly says
+  `get_solana_token_intelligence`.
+
+* **`protocol` filter missing from `list_mpp32_services`.** The tool
+  description and the backend both support filtering by payment protocol
+  (x402, tempo, acp, ap2, agtp), but the parameter was never wired
+  through. Added `protocol` as an optional enum parameter and forwarded
+  it to the backend query string.
+
+* **`server.json` version stuck at 1.2.2.** The MCP registry manifest
+  was never bumped past 1.2.2, causing the official registry listing to
+  advertise the wrong version. Updated to 1.3.1 with all new env vars.
+
+* **`server.json` missing `MPP32_PREFERRED_NETWORK` and `MPP32_TIMEOUT_MS`
+  environment variables.** Both were supported since 1.2.3 and 1.1.2
+  respectively but never declared in the registry manifest.
+
+### Added
+
+* **README now documents all M32-gated tools.** `get_m32_whale_tracker`,
+  `compare_tokens_m32`, and `scan_portfolio_m32` were live in the server
+  but missing from the README's tools section.
+
+* **README now documents `MPP32_SOLANA_RPC_URL` and `MPP32_TIMEOUT_MS`**
+  in the configuration table.
+
+## [1.3.0] - 2026-05-14
+
+### Added
+
+* **Economic Circuit Breakers — infrastructure-level spending guardrails.**
+  The first MCP payment server with built-in budget enforcement. No more
+  runaway agent bills.
+
+  - **`manage_agent_budget` tool** — new MCP tool to view, set, or reset
+    spending limits directly from Claude, Cursor, or any MCP client.
+    Supports three actions:
+    - `get`: View current budget status (remaining balance, hourly velocity,
+      circuit breaker state, per-service spending breakdown).
+    - `set`: Configure `budgetLimitUsd` (total session cap), `velocityLimitUsd`
+      (hourly max), and `alertThresholdPercent` (warning threshold).
+    - `reset`: Manually clear a tripped circuit breaker so the session can
+      resume spending.
+
+  - **Per-session budget limits** — set a maximum total spend in USD when
+    creating a session or at any time via the new `manage_agent_budget` tool.
+    When the limit is reached, the circuit breaker trips and all paid calls
+    are blocked until manually reset or the budget is increased.
+
+  - **Velocity (hourly) limits** — cap how fast an agent can spend. Prevents
+    infinite-loop scenarios where an agent drains a wallet in minutes.
+
+  - **Automatic circuit breaker** — trips instantly when budget or velocity
+    limits are exceeded. Sticky by design: agents cannot auto-resume spending.
+    Requires explicit reset via the MCP tool or API.
+
+  - **Budget status in every response** — all `call_mpp32_endpoint` and
+    `get_solana_token_intelligence` responses now include remaining budget,
+    utilization percentage, and circuit breaker state when limits are
+    configured.
+
+  - **Circuit breaker error handling** — when a circuit breaker is tripped,
+    the MCP server returns a clear, actionable message explaining what
+    happened and how to resume (via `manage_agent_budget`).
+
+### Changed
+
+* **`formatExecuteSuccess` now includes budget status.** When budget limits
+  are configured, successful responses include a one-line budget summary
+  (remaining balance and utilization %).
+
+## [1.2.4] - 2026-05-11
+
+### Fixed
+
+* **Self-payment now fails fast with a useful error.** When the wallet
+  derived from `MPP32_SOLANA_PRIVATE_KEY` (or `MPP32_PRIVATE_KEY`) is the
+  same address as a challenge's `payTo`, the signer used to construct the
+  transaction anyway and the facilitator surfaced an opaque "transaction
+  failed simulation" error a few seconds later. Both the SVM and EVM
+  signers now detect this case before signing and return:
+  `Refusing to sign an x402 payment to yourself: the wallet derived from
+  MPP32_SOLANA_PRIVATE_KEY (<addr>) is also the payment recipient (payTo)
+  for this service.` This happens most often when an operator uses their
+  own receiving wallet to test a paid endpoint they themselves run.
+
 ## [1.2.3] - 2026-05-11
 
 ### Fixed

package/README.md

@@ -9,7 +9,18 @@
   </p>
 </p>
 
-One install. Five payment rails. Thousands of paid APIs your agent can reach without you setting up a single account.
+One install. Pay any x402 endpoint on Solana from your agent. Browse a federated index of thousands of machine payable APIs without setting up a single provider account.
+
+## What works today
+
+| Rail | Status | Network | Asset |
+|:-----|:-------|:--------|:------|
+| x402 | Production | Solana (mainnet) | USDC |
+| x402 | Production | Base | USDC |
+| Tempo | Envelope wired, gated off in production until the client flow is verified end to end | Ethereum L2 | pathUSD |
+| ACP / AP2 / AGTP | Envelopes wired, gated off in production | Multi chain | per protocol |
+
+The MCP server ships signers for both Solana and Base out of the box. When a paid call returns a 402, the server picks the network that matches the key you configured and settles the payment in one round trip.
 
 ## Why this beats running your own integrations
 
@@ -24,23 +35,12 @@ MPP32 replaces all of that with one MCP server. Your agent asks for a service by
 * Run real time Solana token intelligence with alpha scoring, rug risk, whale flow, and 24 hour pump probability.
 * Track every call, every dollar settled, and every protocol used from a dashboard at mpp32.org.
 * Get an automatic 20 percent or 40 percent discount on native services for holding M32 once your wallet is verified.
-
-## Payment rails it speaks natively
-
-| Rail | Settles in | Network |
-|:-----|:-----------|:--------|
-| x402 | USDC | Solana |
-| Tempo | pathUSD | Ethereum L2 |
-| ACP | Checkout session | Multi chain |
-| AP2 | W3C verifiable credentials | Chain agnostic |
-| AGTP | HMAC signed agent certificates | Chain agnostic |
-
-Every native endpoint accepts all five. The server picks whichever your wallet is funded for and falls back gracefully if the first attempt fails.
+* Access M32-gated exclusive APIs: Whale Tracker (1M M32), Token Comparison (2.5M M32), and Portfolio Scanner (5M M32) — free for holders, unavailable to non-holders.
 
 ## Install
 
 ```bash
-npx mpp32-mcp-server
+npx -y mpp32-mcp-server@latest
 ```
 
 ### Claude Desktop, Claude Code, Cursor, Windsurf
@@ -52,30 +52,58 @@ Drop this into the MCP servers section of your client config.
   "mcpServers": {
     "mpp32": {
       "command": "npx",
-      "args": ["mpp32-mcp-server"],
+      "args": ["-y", "mpp32-mcp-server@latest"],
       "env": {
         "MPP32_AGENT_KEY": "mpp32_agent_…",
-        "MPP32_SOLANA_PRIVATE_KEY": "your_solana_private_key_for_usdc"
+        "MPP32_SOLANA_PRIVATE_KEY": "<your base58 Solana secret key>"
       }
     }
   }
 }
 ```
 
-Get an `MPP32_AGENT_KEY` at [mpp32.org/agent-console](https://mpp32.org/agent-console). No signup, no email, just a session form. With an agent key every call is attributed to your dashboard so you can see spend, success rate, and protocol breakdown. Without it the server still works but you only see native services and the calls stay anonymous.
+Config file locations:
+
+* **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
+* **Cursor:** `~/.cursor/mcp.json`
+* **Windsurf:** `~/.codeium/windsurf/mcp_config.json`
 
-`MPP32_SOLANA_PRIVATE_KEY` and `MPP32_PRIVATE_KEY` are only needed for paid services. Free services in the catalog work without any key.
+Fully quit and reopen the client after editing. The MCP child process inherits env vars from this file at launch.
+
+Get an `MPP32_AGENT_KEY` at [mpp32.org/agent-console](https://mpp32.org/agent-console). No signup, no email, just click **Create Agent Session** and the form returns a key plus this exact config snippet ready to copy. With an agent key every call is attributed to your dashboard so you can see spend, success rate, and protocol breakdown. Without it the server still works but you only see native services and the calls stay anonymous.
+
+`MPP32_SOLANA_PRIVATE_KEY` is only needed for paid services. Free services in the catalog work without any payment key.
+
+### What format does `MPP32_SOLANA_PRIVATE_KEY` take?
+
+A base58 encoded 64 byte Solana secret key. The same string that Phantom shows under **export private key** (not the seed phrase). If you have a `keypair.json` (the 64 byte array Solana CLI uses), convert it once with:
+
+```bash
+node -e "console.log(require('bs58').encode(Buffer.from(JSON.parse(require('fs').readFileSync('keypair.json')))))"
+```
+
+Then paste the resulting string into the env block. Treat it like a password. It can spend any USDC and SOL in the wallet.
+
+### Fund the wallet with both USDC and SOL
+
+x402 settles the payment in USDC, but Solana itself charges a tiny native SOL fee on every transaction. A USDC only wallet will fail with `insufficient funds for rent` even though the USDC balance is plentiful. About `0.001 SOL` covers many calls.
+
+Tip: call the `get_mpp32_diagnostics` tool from inside Claude. It probes the API, reports which env vars actually reached the MCP process, and prints `Ready to pay: YES` once everything is wired.
 
 ## Configuration
 
 | Variable | When you need it | What it does |
 |:---------|:-----------------|:-------------|
 | `MPP32_AGENT_KEY` | Recommended | Session key from mpp32.org/agent-console. Unlocks the full federated catalog and dashboard tracking. Also accepted as `MPP32_API_KEY`. |
-| `MPP32_SOLANA_PRIVATE_KEY` | Paid x402 calls | Solana key used to sign USDC payments locally. |
-| `MPP32_PRIVATE_KEY` | Paid Tempo calls | EVM key used to sign pathUSD payments locally on Ethereum L2. |
+| `MPP32_SOLANA_PRIVATE_KEY` | Paid x402 calls on Solana | Base58 encoded Solana secret key. Used to sign USDC payments locally. Never leaves your machine. |
+| `MPP32_PRIVATE_KEY` | Paid x402 calls on Base | 0x prefixed EVM private key. Used to sign USDC payments on Base when a provider only accepts EVM. |
+| `MPP32_PREFERRED_NETWORK` | Optional override | When both keys are configured and the challenge advertises multiple networks, force one. Accepts `solana`, `base`, `evm`, or a full CAIP-2 string. |
+| `MPP32_SOLANA_RPC_URL` | Optional | Override the Solana RPC endpoint used to fetch recent blockhashes when building x402 transactions. Defaults to `https://api.mainnet-beta.solana.com`. Set this if you hit public rate limits. |
+| `MPP32_TIMEOUT_MS` | Optional | Request timeout in milliseconds for all outbound API calls. Range 1000 to 300000. Defaults to 30000 (30 seconds). |
 | `MPP32_API_URL` | Custom deployments | Override the API base URL. Defaults to `https://mpp32.org`. |
 
-Private keys stay on your machine. They sign payments locally and never travel to MPP32 servers. Provide one or both for paid calls. If both are present, x402 is tried first and Tempo is used as a fallback.
+Private keys stay on your machine. They sign payments locally and never travel to MPP32 servers. Provide either or both for paid calls. If both are present and a challenge advertises both networks, EVM is preferred unless `MPP32_PREFERRED_NETWORK` is set; if only one key is configured, that network wins automatically.
 
 ## Tools your agent will see
 
@@ -111,15 +139,67 @@ Under the hood:
 
 No payment logic in your code. No per provider keys to juggle.
 
+### `get_mpp32_diagnostics`
+
+Reports the MCP server version, which env vars actually reached the child process, the API URL it will hit, and a live API reachability probe. Prints `Ready to pay: YES` only when an agent key plus at least one signing key are detected and the API is reachable. Call this first if anything misbehaves. Also available as `debug_mpp32`.
+
 ### `get_solana_token_intelligence`
 
-Real time analysis of any Solana token. Pulls live data from DexScreener, Jupiter, and CoinGecko and merges it into one report. Returns an alpha score from 0 to 100, rug risk, whale activity, smart money signals, 24 hour pump probability, projected ROI ranges, and full market data. Costs $0.008 per call, paid automatically through x402 or Tempo when a key is set.
+Real time analysis of any Solana token. Pulls live data from DexScreener, Jupiter, and CoinGecko and merges it into one report. Returns an alpha score from 0 to 100, rug risk, whale activity, smart money signals, 24 hour pump probability, projected ROI ranges, and full market data. Costs $0.008 per call, paid automatically through x402 when a Solana key is set.
 
 ```json
 { "token": "BONK" }
 ```
 
-M32 holders get tiered discounts (20 percent at 250k, 40 percent at 1M) the moment their wallet is verified at the agent console.
+M32 holders get tiered discounts (20 percent at 250k, 40 percent at 1M) once SIWS wallet signature verification ships. The discount path is gated off in production until then so it cannot be claimed by spoofing a wallet header. M32 holders also get exclusive access to three token-gated APIs: Whale Tracker (1M M32), Token Comparison (2.5M M32), and Portfolio Scanner (5M M32) — these are live now and require passing your wallet address via the `X-Wallet-Address` header.
+
+### `get_m32_whale_tracker`
+
+M32-gated whale analysis for any Solana token. Returns top 20 holders, concentration risk, holder distribution, and buy/sell pressure. Requires the caller to hold 1,000,000+ M32 tokens (balance verified on-chain). Free for qualifying holders.
+
+```json
+{ "token": "<mint-address>", "walletAddress": "<your-solana-wallet>" }
+```
+
+### `compare_tokens_m32`
+
+M32-gated head-to-head intelligence comparison of two Solana tokens. Returns side-by-side alpha scores, rug risk, whale activity, volume, liquidity, and a winner verdict. Requires 2,500,000+ M32 tokens.
+
+```json
+{ "tokenA": "<mint-A>", "tokenB": "<mint-B>", "walletAddress": "<your-solana-wallet>" }
+```
+
+### `scan_portfolio_m32`
+
+M32-gated full wallet portfolio scan. Discovers all SPL tokens in a wallet, runs intelligence on top holdings, and returns per-token analysis with aggregate risk metrics. Requires 5,000,000+ M32 tokens.
+
+```json
+{ "wallet": "<wallet-to-scan>", "walletAddress": "<your-solana-wallet>" }
+```
+
+### `manage_agent_budget`
+
+View, set, or reset the economic circuit breaker for your agent session. Prevents runaway spending with infrastructure-level budget enforcement.
+
+```json
+{ "action": "get" }
+```
+
+```json
+{ "action": "set", "budgetLimitUsd": 10.0, "velocityLimitUsd": 1.0, "alertThresholdPercent": 80 }
+```
+
+```json
+{ "action": "reset" }
+```
+
+Three actions:
+
+* **get** returns current budget status: remaining balance, hourly velocity, circuit breaker state, and per-service spending breakdown.
+* **set** configures `budgetLimitUsd` (max total session spend), `velocityLimitUsd` (max spend per hour), and `alertThresholdPercent` (warn at this percentage of budget used). All three are optional and can be set independently.
+* **reset** clears a tripped circuit breaker so the session can resume spending. Circuit breakers trip automatically when limits are exceeded and stay tripped until manually reset.
+
+Budget limits can also be set at session creation time via the agent console at mpp32.org/agent-console or by passing `budgetLimitUsd`, `velocityLimitUsd`, and `alertThresholdPercent` to `POST /api/agent/sessions`.
 
 ## How discovery works
 
@@ -147,13 +227,13 @@ Sessions are scoped, revocable, and rotate cleanly. The key is hashed at rest on
 
 ## How payment verification actually works
 
-x402 payments are verified on chain through the Solana facilitator. Tempo payments are verified cryptographically through the mppx SDK. ACP sessions are database backed with a real checkout flow. AP2 mandates use ECDSA P-256 signature verification. AGTP uses HMAC SHA256 signed agent certificates with a server held salt so signatures cannot be forged from a public agent id alone.
+x402 payments are verified on chain through the Solana facilitator (for SVM) or the Base facilitator (for EVM). MPP32 never holds custody of funds. Every paid call settles directly from the caller's wallet to the provider's wallet.
 
-Every protocol has its own verification path. None of them are stubbed. MPP32 never holds custody of funds. Every paid call settles directly from the caller's wallet to the provider's wallet.
+Tempo, ACP, AP2, and AGTP envelopes are implemented in the proxy and tested against synthetic challenges, but the corresponding client signing flows are not yet exposed by this MCP. Those rails stay disabled in production until each has a verified end to end client flow. Treat the catalog as an x402 catalog today; the rest will light up as their clients land.
 
 ## For API providers
 
-List your endpoint once and get paid through every protocol automatically. MPP32 handles the payment negotiation, the on chain verification, the discovery listings via OpenAPI and A2A and MCP standards, the 24 hour health re check, and the analytics dashboard. Settlement lands in USDC or pathUSD straight to your wallet.
+List your endpoint once and receive payment over x402. MPP32 handles the payment negotiation, the on chain verification, the discovery listings via OpenAPI and A2A and MCP standards, the periodic health re check, and the analytics dashboard. Settlement lands in USDC on Solana or Base straight to your wallet.
 
 Register at [mpp32.org/build](https://mpp32.org/build).
 

package/dist/index.js

@@ -3,7 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { signX402Payment } from "./x402-signers.js";
-const SERVER_VERSION = "1.2.3";
+const SERVER_VERSION = "1.3.1";
 // ── Env loading: trim and sanitize aggressively ─────────────────────────────
 // Copy-paste from Claude Desktop / Cursor / Windsurf JSON config UIs frequently
 // adds trailing \n, \r, NBSP, BOM, or wraps the value in literal quotes. Any
@@ -252,7 +252,7 @@ server.tool("get_mpp32_diagnostics", "Report what the mpp32-mcp-server detected
         `- x402 (USDC on Solana) payment: ${SOLANA_PRIVATE_KEY ? "yes" : "no — set MPP32_SOLANA_PRIVATE_KEY"}`,
         `- x402 (USDC on Base/EVM) payment: ${PRIVATE_KEY ? "yes" : "no — set MPP32_PRIVATE_KEY"}`,
         ``,
-        `**Ready to pay end-to-end:** ${readyToPay ? "YES — try `query_intelligence` with token=\"M32\" to confirm." : "NO — see the missing items above."}`,
+        `**Ready to pay end-to-end:** ${readyToPay ? "YES — try `get_solana_token_intelligence` with token=\"M32\" to confirm." : "NO — see the missing items above."}`,
         ``,
         `**If a variable shows NOT SET but you set it in claude_desktop_config.json:**`,
         `1. Confirm the file path Claude Desktop actually reads:`,
@@ -308,6 +308,10 @@ server.tool("list_mpp32_services", "Browse the MPP32 federated catalog of 4,500+
         .enum(["native", "x402-bazaar", "mcp-registry", "curated", "free"])
         .optional()
         .describe("Filter by catalog source. 'native' = callable end-to-end; 'curated'/'free' = often callable; 'x402-bazaar'/'mcp-registry' = mostly listing-only."),
+    protocol: z
+        .enum(["x402", "tempo", "acp", "ap2", "agtp"])
+        .optional()
+        .describe("Filter by payment protocol (e.g. 'x402' for USDC-settled services)."),
     limit: z
         .number()
         .int()
@@ -315,7 +319,7 @@ server.tool("list_mpp32_services", "Browse the MPP32 federated catalog of 4,500+
         .max(500)
         .optional()
         .describe("Max results (default 100, max 500)."),
-}, async ({ category, q, source, limit }) => {
+}, async ({ category, q, source, protocol, limit }) => {
     try {
         const url = new URL("/api/agent/services", API_URL);
         if (category)
@@ -324,6 +328,8 @@ server.tool("list_mpp32_services", "Browse the MPP32 federated catalog of 4,500+
             url.searchParams.set("q", q);
         if (source)
             url.searchParams.set("source", source);
+        if (protocol)
+            url.searchParams.set("protocol", protocol);
         url.searchParams.set("limit", String(limit ?? 100));
         const res = await fetchWithTimeout(url.toString(), { headers: buildHeaders() });
         if (!res.ok) {
@@ -460,6 +466,221 @@ server.tool("get_solana_token_intelligence", "Get real-time Solana token intelli
     // Legacy path — direct call to /api/intelligence with manual 402 handling.
     return await legacyIntelligenceCall(token, walletAddress);
 });
+// ── Tool 4: M32-gated Whale Tracker ───────────────────────────────────────
+server.tool("get_m32_whale_tracker", "M32-gated whale analysis for any Solana token. Returns top 20 holders, concentration risk, holder distribution, and buy/sell pressure. Requires the caller to hold 1,000,000+ M32 tokens (balance verified on-chain via X-Wallet-Address header). Free for qualifying holders — no payment required. Returns 403 if the wallet holds insufficient M32.", {
+    token: z
+        .string()
+        .describe("Solana token mint address to analyze for whale activity."),
+    walletAddress: z
+        .string()
+        .describe("Your Solana wallet address. M32 balance is checked on-chain to verify you hold 1M+ M32."),
+}, async ({ token, walletAddress }) => {
+    try {
+        const res = await fetchWithTimeout(`${API_URL}/api/m32/whale-tracker`, {
+            method: "POST",
+            headers: buildHeaders({
+                "Content-Type": "application/json",
+                "X-Wallet-Address": safeHeaderValue("walletAddress", walletAddress),
+            }),
+            body: JSON.stringify({ token }),
+        });
+        const text = await res.text();
+        let formatted;
+        try {
+            formatted = JSON.stringify(JSON.parse(text), null, 2);
+        }
+        catch {
+            formatted = text;
+        }
+        if (res.status === 403) {
+            return { content: [{ type: "text", text: `**Access denied.** Whale Tracker requires holding 1,000,000+ M32 tokens. Your wallet does not meet the threshold.\n\nBuy M32: https://raydium.io/swap/?inputMint=sol&outputMint=6hKtz8FV7cAQMrbjcBZeTQAcrYep3WCM83164JpJpump` }] };
+        }
+        return { content: [{ type: "text", text: `**Whale Tracker** — \`${token}\`\n\n\`\`\`json\n${formatted}\n\`\`\`` }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+});
+// ── Tool 5: M32-gated Token Comparison ────────────────────────────────────
+server.tool("compare_tokens_m32", "M32-gated head-to-head intelligence comparison of two Solana tokens. Returns side-by-side alpha scores, rug risk, whale activity, volume, liquidity, market data, and a winner verdict. Requires the caller to hold 2,500,000+ M32 tokens (balance verified on-chain via X-Wallet-Address header). Free for qualifying holders. Returns 403 if insufficient M32.", {
+    tokenA: z
+        .string()
+        .describe("First Solana token mint address."),
+    tokenB: z
+        .string()
+        .describe("Second Solana token mint address."),
+    walletAddress: z
+        .string()
+        .describe("Your Solana wallet address. M32 balance is checked on-chain to verify you hold 2.5M+ M32."),
+}, async ({ tokenA, tokenB, walletAddress }) => {
+    try {
+        const res = await fetchWithTimeout(`${API_URL}/api/m32/compare`, {
+            method: "POST",
+            headers: buildHeaders({
+                "Content-Type": "application/json",
+                "X-Wallet-Address": safeHeaderValue("walletAddress", walletAddress),
+            }),
+            body: JSON.stringify({ tokenA, tokenB }),
+        });
+        const text = await res.text();
+        let formatted;
+        try {
+            formatted = JSON.stringify(JSON.parse(text), null, 2);
+        }
+        catch {
+            formatted = text;
+        }
+        if (res.status === 403) {
+            return { content: [{ type: "text", text: `**Access denied.** Token Comparison requires holding 2,500,000+ M32 tokens. Your wallet does not meet the threshold.\n\nBuy M32: https://raydium.io/swap/?inputMint=sol&outputMint=6hKtz8FV7cAQMrbjcBZeTQAcrYep3WCM83164JpJpump` }] };
+        }
+        return { content: [{ type: "text", text: `**Token Comparison** — \`${tokenA}\` vs \`${tokenB}\`\n\n\`\`\`json\n${formatted}\n\`\`\`` }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+});
+// ── Tool 6: M32-gated Portfolio Scanner ───────────────────────────────────
+server.tool("scan_portfolio_m32", "M32-gated full wallet portfolio scan. Discovers all SPL tokens in a Solana wallet, runs intelligence on top holdings, and returns per-token analysis with aggregate portfolio risk metrics. Requires the caller to hold 5,000,000+ M32 tokens (balance verified on-chain via X-Wallet-Address header). Free for qualifying holders. Returns 403 if insufficient M32.", {
+    wallet: z
+        .string()
+        .describe("Solana wallet address to scan for token holdings."),
+    walletAddress: z
+        .string()
+        .describe("Your Solana wallet address. M32 balance is checked on-chain to verify you hold 5M+ M32."),
+}, async ({ wallet, walletAddress }) => {
+    try {
+        const res = await fetchWithTimeout(`${API_URL}/api/m32/portfolio`, {
+            method: "POST",
+            headers: buildHeaders({
+                "Content-Type": "application/json",
+                "X-Wallet-Address": safeHeaderValue("walletAddress", walletAddress),
+            }),
+            body: JSON.stringify({ wallet }),
+        });
+        const text = await res.text();
+        let formatted;
+        try {
+            formatted = JSON.stringify(JSON.parse(text), null, 2);
+        }
+        catch {
+            formatted = text;
+        }
+        if (res.status === 403) {
+            return { content: [{ type: "text", text: `**Access denied.** Portfolio Scanner requires holding 5,000,000+ M32 tokens. Your wallet does not meet the threshold.\n\nBuy M32: https://raydium.io/swap/?inputMint=sol&outputMint=6hKtz8FV7cAQMrbjcBZeTQAcrYep3WCM83164JpJpump` }] };
+        }
+        return { content: [{ type: "text", text: `**Portfolio Scanner** — wallet \`${wallet}\`\n\n\`\`\`json\n${formatted}\n\`\`\`` }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+});
+// ── Tool 8: manage_agent_budget ────────────────────────────────────────────
+server.tool("manage_agent_budget", "View, set, or reset the spending circuit breaker for your MPP32 agent session. Use 'get' to check current budget status (remaining budget, hourly velocity, circuit breaker state). Use 'set' to configure spending limits (budget cap in USD, hourly velocity limit, alert threshold percentage). Use 'reset' to manually reset a tripped circuit breaker so the session can resume spending. Circuit breakers trip automatically when budget or velocity limits are exceeded, preventing runaway agent spending.", {
+    action: z.enum(["get", "set", "reset"]).describe("Action: 'get' = view budget status, 'set' = update limits, 'reset' = clear tripped circuit breaker"),
+    budgetLimitUsd: z.number().positive().max(1_000_000).optional().describe("Maximum total session spend in USD. Only used with action='set'."),
+    velocityLimitUsd: z.number().positive().max(1_000_000).optional().describe("Maximum spend per hour in USD. Only used with action='set'."),
+    alertThresholdPercent: z.number().int().min(1).max(100).optional().describe("Budget percentage at which to warn (e.g. 80 = warn at 80% spent). Only used with action='set'."),
+}, async ({ action, budgetLimitUsd, velocityLimitUsd, alertThresholdPercent }) => {
+    if (!AGENT_KEY) {
+        return {
+            content: [{ type: "text", text: "**MPP32_AGENT_KEY not configured.** Set it in your MCP config to manage budgets." }],
+        };
+    }
+    try {
+        if (action === "get") {
+            const res = await fetchWithTimeout(new URL("/api/agent/spending", API_URL).toString(), { headers: buildHeaders() });
+            if (!res.ok) {
+                const err = await res.json().catch(() => null);
+                return { content: [{ type: "text", text: `Error fetching budget: ${err?.error?.message ?? res.statusText}` }] };
+            }
+            const data = (await res.json()).data;
+            const lines = [
+                `**MPP32 Session Budget Status**`,
+                ``,
+            ];
+            if (data.budgetLimitUsd != null) {
+                lines.push(`Budget: $${data.totalSpentUsd.toFixed(4)} spent of $${data.budgetLimitUsd.toFixed(4)} ($${data.remainingBudgetUsd.toFixed(4)} remaining, ${data.budgetUtilizationPercent}% used)`);
+            }
+            else {
+                lines.push(`Budget: unlimited (no cap set)`);
+                lines.push(`Total spent: $${data.totalSpentUsd.toFixed(4)} across ${data.totalSettledCalls} settled calls`);
+            }
+            if (data.velocityLimitUsd != null) {
+                lines.push(`Velocity: $${data.hourlySpendUsd.toFixed(4)}/hr of $${data.velocityLimitUsd.toFixed(4)}/hr limit (${data.hourlySettledCalls} calls this hour)`);
+            }
+            if (data.circuitBreakerTripped) {
+                lines.push(``);
+                lines.push(`**CIRCUIT BREAKER TRIPPED** — ${data.circuitBreakerReason}`);
+                lines.push(`Tripped at: ${data.circuitBreakerTrippedAt}`);
+                lines.push(`Use action="reset" to resume spending.`);
+            }
+            if (data.byService?.length) {
+                lines.push(``);
+                lines.push(`**Spending by service:**`);
+                for (const s of data.byService) {
+                    lines.push(`- ${s.service}: $${s.totalSpentUsd.toFixed(4)} (${s.count} calls)`);
+                }
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        if (action === "set") {
+            const payload = {};
+            if (budgetLimitUsd !== undefined)
+                payload.budgetLimitUsd = budgetLimitUsd;
+            if (velocityLimitUsd !== undefined)
+                payload.velocityLimitUsd = velocityLimitUsd;
+            if (alertThresholdPercent !== undefined)
+                payload.alertThresholdPercent = alertThresholdPercent;
+            if (Object.keys(payload).length === 0) {
+                return { content: [{ type: "text", text: "Provide at least one of: budgetLimitUsd, velocityLimitUsd, alertThresholdPercent." }] };
+            }
+            const res = await fetchWithTimeout(new URL("/api/agent/budget", API_URL).toString(), {
+                method: "PATCH",
+                headers: buildHeaders({ "Content-Type": "application/json" }),
+                body: JSON.stringify(payload),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => null);
+                return { content: [{ type: "text", text: `Error updating budget: ${err?.error?.message ?? res.statusText}` }] };
+            }
+            const data = (await res.json()).data;
+            const lines = [
+                `**Budget updated successfully.**`,
+                ``,
+                data.budgetLimitUsd != null ? `Budget limit: $${data.budgetLimitUsd.toFixed(4)}` : `Budget limit: unlimited`,
+                data.velocityLimitUsd != null ? `Velocity limit: $${data.velocityLimitUsd.toFixed(4)}/hr` : `Velocity limit: unlimited`,
+                `Total spent: $${data.totalSpentUsd.toFixed(4)}`,
+                data.remainingBudgetUsd != null ? `Remaining: $${data.remainingBudgetUsd.toFixed(4)}` : ``,
+                data.circuitBreakerTripped ? `\n**Note:** Circuit breaker is still tripped. Use action="reset" to resume.` : ``,
+            ].filter(Boolean);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        if (action === "reset") {
+            const res = await fetchWithTimeout(new URL("/api/agent/circuit-breaker/reset", API_URL).toString(), {
+                method: "POST",
+                headers: buildHeaders({ "Content-Type": "application/json" }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => null);
+                return { content: [{ type: "text", text: `Error resetting circuit breaker: ${err?.error?.message ?? res.statusText}` }] };
+            }
+            const data = (await res.json()).data;
+            const lines = [
+                data.previousReason
+                    ? `**Circuit breaker reset.** Previous reason: ${data.previousReason}.`
+                    : `**Circuit breaker was not tripped.** No action needed.`,
+                ``,
+                data.budgetLimitUsd != null ? `Budget: $${data.totalSpentUsd.toFixed(4)} / $${data.budgetLimitUsd.toFixed(4)} ($${data.remainingBudgetUsd.toFixed(4)} remaining)` : ``,
+                `Session can resume spending.`,
+            ].filter(Boolean);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        return { content: [{ type: "text", text: "Unknown action. Use 'get', 'set', or 'reset'." }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+});
 // ── Core: agent/execute path with 402 sign-and-retry ────────────────────────
 async function callViaAgentExecute(service, method, body, query, path) {
     try {
@@ -637,6 +858,10 @@ function formatExecuteSuccess(resp, protoOverride) {
     else if (meta?.paymentMethod === "unsettled") {
         lines.push(`Service responded but no payment was verified. This should not happen for paid services.`);
     }
+    if (meta?.budget && meta.budget.budgetLimitUsd != null) {
+        const b = meta.budget;
+        lines.push(`Budget: $${b.remainingBudgetUsd.toFixed(4)} remaining (${b.budgetUtilizationPercent}% of $${b.budgetLimitUsd.toFixed(4)} used)`);
+    }
     lines.push("");
     lines.push("```json");
     lines.push(formatted);
@@ -645,6 +870,25 @@ function formatExecuteSuccess(resp, protoOverride) {
 }
 function formatExecuteHardError(status, body) {
     const code = body?.error?.code;
+    if (code === "MPP32_CIRCUIT_BREAKER_TRIPPED" || (status === 429 && body?.error?.budgetStatus)) {
+        const bs = body?.error?.budgetStatus;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `**Circuit breaker tripped** — spending limit reached.`,
+                        ``,
+                        body?.error?.message ?? "Session budget exhausted.",
+                        bs?.budgetLimitUsd != null ? `Budget: $${bs.totalSpentUsd?.toFixed(4) ?? "?"} / $${bs.budgetLimitUsd.toFixed(4)}` : "",
+                        bs?.velocityLimitUsd != null ? `Velocity: $${bs.hourlySpendUsd?.toFixed(4) ?? "?"}/hr of $${bs.velocityLimitUsd.toFixed(4)}/hr limit` : "",
+                        ``,
+                        `To resume: use \`manage_agent_budget\` with action="reset", or increase the budget with action="set".`,
+                    ].filter(Boolean).join("\n"),
+                },
+            ],
+        };
+    }
     if (code === "NOT_HTTP_CALLABLE") {
         return {
             content: [

package/dist/x402-signers.js

@@ -129,6 +129,18 @@ export async function signX402PaymentSvm(requirements, rawKey, rpcUrlOverride, e
     const mintAddress = deps.address(requirements.asset);
     const recipientAddress = deps.address(requirements.payTo);
     const feePayerAddress = deps.address(requirements.extra.feePayer);
+    // Self-payment guard. An SPL TransferChecked where source ATA == destination
+    // ATA is a no-op the Solana runtime rejects, and the resulting facilitator
+    // error is opaque ("transaction failed simulation"). This usually means the
+    // user configured the same wallet as both their MPP32_SOLANA_PRIVATE_KEY and
+    // the upstream payTo (e.g. calling their own listed service, or testing
+    // against the MPP32 oracle from the operator wallet). Catch it here with a
+    // clear, actionable message before we burn an RPC round-trip.
+    if (String(payerAddress) === String(recipientAddress)) {
+        throw new Error(`Refusing to sign an x402 payment to yourself: the wallet derived from MPP32_SOLANA_PRIVATE_KEY ` +
+            `(${String(payerAddress)}) is also the payment recipient (payTo) for this service. ` +
+            `Use a different wallet to call this endpoint, or fund a separate payer key.`);
+    }
     // Derive both sides' associated token accounts (classic SPL Token program).
     const [sourceAtaTuple, destinationAtaTuple] = await Promise.all([
         deps.findAssociatedTokenPda({
@@ -203,6 +215,14 @@ export async function signX402PaymentEvm(requirements, rawKey, echoedVersion = 1
     }
     const { privateKeyToAccount } = await loadEvmDeps();
     const account = privateKeyToAccount(keyHex);
+    // Self-payment guard (EVM). EIP-3009 transferWithAuthorization with
+    // from == to is rejected on-chain by USDC. Surfacing this here keeps the
+    // error message useful instead of an opaque facilitator failure.
+    if (account.address.toLowerCase() === recipientAddr.toLowerCase()) {
+        throw new Error(`Refusing to sign an x402 payment to yourself: the wallet derived from MPP32_PRIVATE_KEY ` +
+            `(${account.address}) is also the payment recipient (payTo) for this service. ` +
+            `Use a different wallet to call this endpoint, or fund a separate payer key.`);
+    }
     const now = Math.floor(Date.now() / 1000);
     const validAfter = BigInt(0);
     const validBefore = BigInt(now + (requirements.maxTimeoutSeconds ?? 600));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mpp32-mcp-server",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "mcpName": "io.github.MPP32/mpp32-mcp-server",
   "description": "Payment layer for AI agents. One MCP, five protocols, thousands of paid APIs your agent can call.",
   "type": "module",