feat: add OpenClaw plugin, --verbose flag, and MPP session fixes

- OpenClaw plugin (src/openclaw/): x_balance tool, x_payment tool,
  /x_wallet command, HTTP route proxy for upstream x402 endpoints
- --verbose flag on fetch command for debugging protocol negotiation,
  headers, session lifecycle, and payment flow
- Fix Headers instances silently dropped in MPP SSE requests by
  converting to plain object before passing to mppx SDK
- Wrap MPP session close() in try/catch to prevent CLI crashes
- Include amount and channelId in MPP payment history records
- Bump to v0.7.0

Author: tenequm

packages/x402-proxy/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-03-20
+
+### Added
+- `--verbose` flag on `fetch` command - debug logging for protocol negotiation, headers, session lifecycle, and payment flow
+- OpenClaw plugin integration (`x402-proxy/openclaw`) - registers `x_balance` tool, `x_payment` tool, `/x_wallet` command, and HTTP route proxy for upstream x402 endpoints
+- `openclaw.plugin.json` manifest with config schema for providers, keypair path, RPC URL, and dashboard URL
+- `./openclaw` subpath export in package.json
+
+### Fixed
+- MPP SSE requests silently losing `Content-Type` and other headers when `Headers` instances are spread (workaround for mppx SDK bug, upstream fix: wevm/mppx#209)
+- MPP session `close()` errors no longer crash the CLI - wrapped in try/catch with verbose error reporting
+- MPP payment history now includes `amount` (converted from base units) and `channelId` in transaction records
+- MPP streaming history records now use `channelId` as fallback for `tx` field when no receipt reference is available
+
 ## [0.6.0] - 2026-03-19
 
 ### Added
@@ -172,7 +186,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `appendHistory` / `readHistory` / `calcSpend` - JSONL transaction history
 - Re-exports from `@x402/fetch`, `@x402/svm`, `@x402/evm`
 
-[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.5.2...v0.6.0
 [0.5.2]: https://github.com/cascade-protocol/x402-proxy/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.5.0...v0.5.1

packages/x402-proxy/README.md

@@ -49,6 +49,9 @@ $ npx x402-proxy --method POST \
 # Force a specific network
 $ npx x402-proxy --network base https://api.example.com/data
 
+# Debug protocol negotiation and payment flow
+$ npx x402-proxy --verbose https://api.example.com/data
+
 # Use MPP protocol for streaming payments
 $ npx x402-proxy --protocol mpp \
   --method POST \
@@ -118,6 +121,12 @@ import {
 
 See the [library API docs](https://github.com/cascade-protocol/x402-proxy/tree/main/packages/x402-proxy#library-api) for details.
 
+## OpenClaw Plugin
+
+x402-proxy ships as an [OpenClaw](https://openclaw.dev) plugin, giving your gateway automatic x402 payment capabilities. Registers `x_balance` and `x_payment` tools, `/x_wallet` command, and an HTTP route proxy for upstream x402 endpoints.
+
+Configure providers and models in OpenClaw plugin settings. Uses the standard wallet resolution (env vars or `wallet.json`).
+
 ## License
 
 Apache-2.0

packages/x402-proxy/openclaw.plugin.json

@@ -0,0 +1,28 @@
+{
+  "id": "x402-proxy",
+  "name": "x402 Proxy",
+  "description": "x402/MPP payments, Solana wallet, and inference proxying",
+  "version": "1.0.0",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "providers": {
+        "type": "object",
+        "description": "Provider catalog keyed by name, each with baseUrl and models array"
+      },
+      "keypairPath": {
+        "type": "string",
+        "description": "Optional path to Solana keypair JSON file (overrides x402-proxy wallet resolution)"
+      },
+      "rpcUrl": {
+        "type": "string",
+        "description": "Solana RPC URL"
+      },
+      "dashboardUrl": {
+        "type": "string",
+        "description": "URL to link from /x_wallet dashboard"
+      }
+    },
+    "required": []
+  }
+}

packages/x402-proxy/package.json

@@ -1,7 +1,7 @@
 {
   "name": "x402-proxy",
-  "version": "0.6.0",
-  "description": "curl for x402 paid APIs. Auto-pays any endpoint on Base, Solana, and Tempo.",
+  "version": "0.7.0",
+  "description": "curl for x402 paid APIs. Auto-pays any endpoint on Base, Solana, and Tempo. Also works as an OpenClaw plugin.",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -11,13 +11,22 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./openclaw": {
+      "types": "./dist/openclaw/plugin.d.ts",
+      "default": "./dist/openclaw/plugin.js"
+    },
     "./package.json": "./package.json"
   },
+  "openclaw": {
+    "extensions": [
+      "./dist/openclaw/plugin.js"
+    ]
+  },
   "bin": {
     "x402-proxy": "./dist/bin/cli.js"
   },
   "scripts": {
-    "build": "rm -rf dist && tsdown --publint",
+    "build": "rm -rf dist && tsdown --publint && cp openclaw.plugin.json dist/",
     "dev": "tsdown --watch",
     "type-check": "tsc --noEmit",
     "test": "vitest run",
@@ -33,6 +42,7 @@
     "@scure/bip32": "^2.0.1",
     "@scure/bip39": "^2.0.1",
     "@solana/kit": "^6.0.0",
+    "@sinclair/typebox": "^0.34.48",
     "@stricli/core": "^1.2.6",
     "@x402/evm": "^2.6.0",
     "@x402/fetch": "^2.6.0",
@@ -44,15 +54,25 @@
     "viem": "^2.0.0",
     "yaml": "^2.8.2"
   },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.8"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "openclaw": ">=2026.3.8",
     "publint": "^0.3.17",
     "tsdown": "^0.20.3",
     "typescript": "^5.9.0",
     "vitest": "^4.0.18"
   },
   "files": [
     "dist/**",
+    "openclaw.plugin.json",
     "README.md",
     "CHANGELOG.md",
     "skills/**",
@@ -71,7 +91,9 @@
     "tempo",
     "usdc",
     "coinbase",
-    "cli"
+    "cli",
+    "openclaw",
+    "openclaw-plugin"
   ],
   "license": "Apache-2.0",
   "engines": {

packages/x402-proxy/skills/SKILL.md

@@ -62,6 +62,7 @@ x402-proxy wallet export-key mnemonic   # bare mnemonic to stdout
 --body, -d <DATA>         Request body (string or @file)
 --network <NETWORK>       Force payment chain (base, solana, tempo)
 --protocol <PROTOCOL>    Payment protocol (x402, mpp)
+--verbose                Show debug details (protocol negotiation, headers, payment flow)
 ```
 
 ## MCP proxy for AI agents
@@ -122,7 +123,7 @@ Also supports JSONC and JSON config files. Wallet stored in `wallet.json` (mode
 
 ```bash
 # Smoke test an endpoint
-npx x402-proxy https://your-service.com/paid-route
+npx x402-proxy --verbose https://your-service.com/paid-route
 
 # Test both chains
 npx x402-proxy --network base https://your-service.com/route
@@ -142,6 +143,17 @@ npx x402-proxy status
 
 stdout = response body, stderr = payment info. Pipes, redirects, and `jq` all work cleanly.
 
+## OpenClaw Plugin
+
+x402-proxy ships as an [OpenClaw](https://openclaw.dev) plugin. Install it to give your OpenClaw gateway automatic x402 payment capabilities:
+
+- `x_balance` tool - check wallet SOL/USDC balances
+- `x_payment` tool - call any x402-enabled endpoint with automatic payment
+- `/x_wallet` command - wallet status, send USDC, transaction history
+- HTTP route proxy (`/x402/*`) - proxies requests to upstream x402 endpoints with payment
+
+Configure in your OpenClaw plugin settings with `providers` (upstream x402 endpoints and models) and optionally `keypairPath` or use the standard `X402_PROXY_WALLET_MNEMONIC` env var.
+
 ## Library API
 
 For programmatic use in Node.js apps, read `references/library.md`.

packages/x402-proxy/src/commands/fetch.ts

@@ -8,6 +8,7 @@ import {
   extractTxSignature,
   type MppPaymentInfo,
   type PaymentInfo,
+  TEMPO_NETWORK,
 } from "../handler.js";
 import { appendHistory, displayNetwork, type TxRecord } from "../history.js";
 import { getHistoryPath, isConfigured, loadConfig } from "../lib/config.js";
@@ -23,6 +24,7 @@ type FetchFlags = {
   network: string | undefined;
   protocol: string | undefined;
   json: boolean;
+  verbose: boolean;
 };
 
 export const fetchCommand = buildCommand<FetchFlags, [url?: string], CommandContext>({
@@ -85,6 +87,11 @@ Examples:
         brief: "Force JSON output",
         default: false,
       },
+      verbose: {
+        kind: "boolean",
+        brief: "Show debug details (protocol negotiation, headers, payment flow)",
+        default: false,
+      },
     },
     positional: {
       kind: "tuple",
@@ -98,6 +105,22 @@ Examples:
     },
   },
   async func(flags, url?: string) {
+    const verbose = (msg: string) => {
+      if (flags.verbose) dim(`  [verbose] ${msg}`);
+    };
+
+    const closeMppSession = async (handler: Awaited<ReturnType<typeof createMppProxyHandler>>) => {
+      verbose("closing MPP session...");
+      try {
+        await handler.close();
+        verbose("session closed successfully");
+      } catch (closeErr) {
+        verbose(
+          `session close failed: ${closeErr instanceof Error ? closeErr.message : String(closeErr)}`,
+        );
+      }
+    };
+
     // No URL: show status or onboarding
     if (!url) {
       if (isConfigured()) {
@@ -181,6 +204,8 @@ Examples:
     const config = loadConfig();
     const resolvedProtocol = flags.protocol ?? config?.preferredProtocol;
     const maxDeposit = config?.mppSessionBudget ?? "1";
+    verbose(`wallet source: ${wallet.source}`);
+    verbose(`protocol: ${resolvedProtocol ?? "auto-detect"}, maxDeposit: ${maxDeposit}`);
 
     // Auto-detect preferred network based on balance when not configured
     let preferredNetwork = config?.defaultNetwork;
@@ -206,7 +231,8 @@ Examples:
     }
 
     const method = flags.method || "GET";
-    const init: RequestInit = { method, headers };
+    // Convert Headers to plain object so mppx SSE spread doesn't lose them
+    const init: RequestInit = { method, headers: Object.fromEntries(headers.entries()) };
     if (flags.body) init.body = flags.body;
 
     if (isTTY()) {
@@ -234,23 +260,41 @@ Examples:
 
         // Detect SSE streaming requests - these need session.sse() for mid-stream voucher cycling
         const isStreamingRequest = flags.body != null && /"stream"\s*:\s*true/.test(flags.body);
+        verbose(`mpp handler created, streaming: ${isStreamingRequest}`);
 
         if (isStreamingRequest) {
           try {
+            verbose("opening SSE session...");
             const tokens = await mppHandler.sse(parsedUrl.toString(), init);
+            verbose("SSE stream opened, reading tokens...");
             for await (const token of tokens) {
               process.stdout.write(token);
             }
+            verbose("SSE stream complete");
           } finally {
-            await mppHandler.close();
+            await closeMppSession(mppHandler);
           }
 
-          mppPayment = mppHandler.shiftPayment();
+          // SSE open pushes an intent-only entry; close pushes the actual receipt
+          mppHandler.shiftPayment();
+          const closeReceipt = mppHandler.shiftPayment();
+          verbose(
+            closeReceipt
+              ? `close receipt: amount=${closeReceipt.amount ?? "none"}, channelId=${closeReceipt.channelId ?? "none"}, txHash=${closeReceipt.receipt?.txHash ?? "none"}`
+              : "no close receipt (session close may have failed)",
+          );
+          mppPayment = closeReceipt ?? {
+            protocol: "mpp",
+            network: TEMPO_NETWORK,
+            intent: "session",
+          };
           usedProtocol = "mpp";
 
           const elapsedMs = Date.now() - startMs;
+          const spentAmount = mppPayment.amount ? Number(mppPayment.amount) : undefined;
           if (mppPayment && isTTY()) {
-            info(`  MPP session (${displayNetwork(mppPayment.network)})`);
+            const spentStr = spentAmount != null ? `${spentAmount.toFixed(4)} USDC ` : "";
+            info(`  MPP session: ${spentStr}(${displayNetwork(mppPayment.network)})`);
           }
           if (isTTY()) {
             dim(`  Streamed (${elapsedMs}ms)`);
@@ -263,8 +307,8 @@ Examples:
               kind: "mpp_payment",
               net: mppPayment.network,
               from: wallet.evmAddress ?? "unknown",
-              tx: mppPayment.receipt?.reference,
-              amount: undefined,
+              tx: mppPayment.receipt?.reference ?? mppPayment.channelId,
+              amount: spentAmount,
               token: "USDC",
               ms: elapsedMs,
               label: parsedUrl.hostname,
@@ -277,10 +321,12 @@ Examples:
         }
 
         // Non-streaming MPP request
+        verbose("sending non-streaming MPP request...");
         try {
           response = await mppHandler.fetch(parsedUrl.toString(), init);
+          verbose(`response: ${response.status} ${response.statusText}`);
         } finally {
-          await mppHandler.close();
+          await closeMppSession(mppHandler);
         }
         mppPayment = mppHandler.shiftPayment();
         usedProtocol = "mpp";
@@ -312,15 +358,18 @@ Examples:
         // If x402 couldn't handle it and server advertises MPP, fall through
         if (response.status === 402 && wallet.evmKey) {
           const detected = detectProtocols(response);
+          verbose(`auto-detect: x402=${detected.x402}, mpp=${detected.mpp}`);
           if (detected.mpp) {
+            verbose("falling through to MPP...");
             const mppHandler = await createMppProxyHandler({
               evmKey: wallet.evmKey,
               maxDeposit,
             });
             try {
               response = await mppHandler.fetch(parsedUrl.toString(), init);
+              verbose(`MPP response: ${response.status} ${response.statusText}`);
             } finally {
-              await mppHandler.close();
+              await closeMppSession(mppHandler);
             }
             mppPayment = mppHandler.shiftPayment();
             x402Payment = undefined;
@@ -337,6 +386,11 @@ Examples:
     const payment = x402Payment ?? mppPayment;
     const txSig = extractTxSignature(response);
 
+    verbose(`protocol used: ${usedProtocol ?? "none"}`);
+    for (const [k, v] of response.headers) {
+      if (/payment|auth|www|x-pay/i.test(k)) verbose(`header ${k}: ${v.slice(0, 200)}`);
+    }
+
     // Payment failed - check balances and show appropriate message
     if (response.status === 402 && isTTY()) {
       const detected = detectProtocols(response);
@@ -505,6 +559,7 @@ Examples:
         net: mppPayment.network,
         from: wallet.evmAddress ?? "unknown",
         tx: mppPayment.receipt?.reference ?? txSig,
+        amount: mppPayment.amount ? Number(mppPayment.amount) : undefined,
         token: "USDC",
         ms: elapsedMs,
         label: parsedUrl.hostname,

packages/x402-proxy/src/handler.ts

@@ -190,10 +190,15 @@ export async function createMppProxyHandler(opts: {
       if (session?.opened) {
         const receipt = await session.close();
         if (receipt) {
+          // spent is in USDC base units (6 decimals)
+          const spentUsdc = receipt.spent
+            ? (Number(receipt.spent) / 1_000_000).toString()
+            : undefined;
           paymentQueue.push({
             protocol: "mpp",
             network: TEMPO_NETWORK,
             intent: "session",
+            amount: spentUsdc,
             channelId: session.channelId ?? undefined,
             receipt: {
               method: receipt.method,