x402-proxy 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-03-20
+
+### Fixed
+- Non-402 server errors (500, 503, etc.) now indicate whether payment was attempted, helping users distinguish "server down" from "payment failed"
+
+## [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 +191,9 @@ 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.1...HEAD
+[0.7.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.7.0...v0.7.1
+[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

package/README.md

@@ -1,6 +1,6 @@
 # x402-proxy
 
-`curl` for [x402](https://www.x402.org/) paid APIs. Auto-pays HTTP 402 responses with USDC on Base, Solana, and Tempo - zero crypto code on the buyer side. Supports both [x402](https://www.x402.org/) and [MPP](https://mpp.dev/) payment protocols.
+`curl` for [x402](https://www.x402.org/) and [MPP](https://mpp.dev/) paid APIs. Auto-pays HTTP 402 responses with USDC on Base, Solana, and [Tempo](https://tempo.xyz/) - zero crypto code on the buyer side. Supports one-time payments (x402, MPP charge) and pay-per-token streaming (MPP sessions).
 
 ## Quick Start
 
@@ -30,7 +30,7 @@ Let your AI agent consume any paid MCP server. Configure in Claude, Cursor, or a
 }
 ```
 
-The proxy sits between your agent and the remote server, intercepting 402 responses, paying automatically, and forwarding the result. Your agent never touches crypto.
+The proxy sits between your agent and the remote server, intercepting 402 responses, paying automatically, and forwarding the result. Supports both x402 and MPP protocols. Your agent never touches crypto.
 
 ## HTTP Requests
 
@@ -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

package/dist/bin/cli.js

@@ -115,20 +115,24 @@ async function createMppProxyHandler(opts) {
 		async close() {
 			if (session?.opened) {
 				const receipt = await session.close();
-				if (receipt) paymentQueue.push({
-					protocol: "mpp",
-					network: TEMPO_NETWORK,
-					intent: "session",
-					channelId: session.channelId ?? void 0,
-					receipt: {
-						method: receipt.method,
-						reference: receipt.reference,
-						status: receipt.status,
-						timestamp: receipt.timestamp,
-						acceptedCumulative: receipt.acceptedCumulative,
-						txHash: receipt.txHash
-					}
-				});
+				if (receipt) {
+					const spentUsdc = receipt.spent ? (Number(receipt.spent) / 1e6).toString() : void 0;
+					paymentQueue.push({
+						protocol: "mpp",
+						network: TEMPO_NETWORK,
+						intent: "session",
+						amount: spentUsdc,
+						channelId: session.channelId ?? void 0,
+						receipt: {
+							method: receipt.method,
+							reference: receipt.reference,
+							status: receipt.status,
+							timestamp: receipt.timestamp,
+							acceptedCumulative: receipt.acceptedCumulative,
+							txHash: receipt.txHash
+						}
+					});
+				}
 			}
 		}
 	};
@@ -195,6 +199,11 @@ Examples:
 				kind: "boolean",
 				brief: "Force JSON output",
 				default: false
+			},
+			verbose: {
+				kind: "boolean",
+				brief: "Show debug details (protocol negotiation, headers, payment flow)",
+				default: false
 			}
 		},
 		positional: {
@@ -207,6 +216,18 @@ Examples:
 		}
 	},
 	async func(flags, url) {
+		const verbose = (msg) => {
+			if (flags.verbose) dim(`  [verbose] ${msg}`);
+		};
+		const closeMppSession = async (handler) => {
+			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)}`);
+			}
+		};
 		if (!url) {
 			if (isConfigured()) {
 				const { displayStatus } = await import("../status-w5y-fhhe.js");
@@ -270,6 +291,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}`);
 		let preferredNetwork = config?.defaultNetwork;
 		if (!preferredNetwork && wallet.evmAddress && wallet.solanaAddress) {
 			const { fetchAllBalances } = await import("../wallet-DjixXCHy.js");
@@ -287,7 +310,7 @@ Examples:
 		const method = flags.method || "GET";
 		const init = {
 			method,
-			headers
+			headers: Object.fromEntries(headers.entries())
 		};
 		if (flags.body) init.body = flags.body;
 		if (isTTY()) dim(`  ${method} ${parsedUrl.toString()}`);
@@ -306,17 +329,30 @@ Examples:
 					evmKey: wallet.evmKey,
 					maxDeposit
 				});
-				if (flags.body != null && /"stream"\s*:\s*true/.test(flags.body)) {
+				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();
+					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;
-					if (mppPayment && isTTY()) info(`  MPP session (${displayNetwork(mppPayment.network)})`);
+					const spentAmount = mppPayment.amount ? Number(mppPayment.amount) : void 0;
+					if (mppPayment && isTTY()) info(`  MPP session: ${spentAmount != null ? `${spentAmount.toFixed(4)} USDC ` : ""}(${displayNetwork(mppPayment.network)})`);
 					if (isTTY()) dim(`  Streamed (${elapsedMs}ms)`);
 					if (mppPayment) {
 						const record = {
@@ -325,8 +361,8 @@ Examples:
 							kind: "mpp_payment",
 							net: mppPayment.network,
 							from: wallet.evmAddress ?? "unknown",
-							tx: mppPayment.receipt?.reference,
-							amount: void 0,
+							tx: mppPayment.receipt?.reference ?? mppPayment.channelId,
+							amount: spentAmount,
 							token: "USDC",
 							ms: elapsedMs,
 							label: parsedUrl.hostname
@@ -336,10 +372,12 @@ Examples:
 					if (isTTY()) process.stdout.write("\n");
 					return;
 				}
+				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";
@@ -364,15 +402,19 @@ Examples:
 				x402Payment = handler.shiftPayment();
 				usedProtocol = "x402";
 				if (response.status === 402 && wallet.evmKey) {
-					if (detectProtocols(response).mpp) {
+					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 = void 0;
@@ -387,6 +429,10 @@ Examples:
 		const elapsedMs = Date.now() - startMs;
 		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)}`);
+		if (!response.ok && response.status !== 402 && isTTY()) if (!payment) dim("  Server returned error before payment was attempted.");
+		else dim("  Payment was processed but server returned an error.");
 		if (response.status === 402 && isTTY()) {
 			const detected = detectProtocols(response);
 			const prHeader = response.headers.get("PAYMENT-REQUIRED") ?? response.headers.get("X-PAYMENT-REQUIRED");
@@ -491,6 +537,7 @@ Examples:
 				net: mppPayment.network,
 				from: wallet.evmAddress ?? "unknown",
 				tx: mppPayment.receipt?.reference ?? txSig,
+				amount: mppPayment.amount ? Number(mppPayment.amount) : void 0,
 				token: "USDC",
 				ms: elapsedMs,
 				label: parsedUrl.hostname
@@ -617,7 +664,7 @@ Add to your MCP client config (Claude, Cursor, etc.):
 			const { x402MCPClient } = await import("@x402/mcp");
 			const remoteClient = new Client({
 				name: "x402-proxy",
-				version: "0.6.0"
+				version: "0.7.1"
 			});
 			const x402Mcp = new x402MCPClient(remoteClient, x402PaymentClient, {
 				autoPayment: true,
@@ -656,7 +703,7 @@ Add to your MCP client config (Claude, Cursor, etc.):
 			}
 			const localServer = new Server({
 				name: "x402-proxy",
-				version: "0.6.0"
+				version: "0.7.1"
 			}, { capabilities: {
 				tools: tools.length > 0 ? {} : void 0,
 				resources: remoteResources.length > 0 ? {} : void 0
@@ -722,7 +769,7 @@ Add to your MCP client config (Claude, Cursor, etc.):
 			const maxDeposit = config?.mppSessionBudget ?? "1";
 			const remoteClient = new Client({
 				name: "x402-proxy",
-				version: "0.6.0"
+				version: "0.7.1"
 			});
 			await connectTransport(remoteClient);
 			const mppClient = McpClient.wrap(remoteClient, { methods: [tempo({
@@ -740,7 +787,7 @@ Add to your MCP client config (Claude, Cursor, etc.):
 			}
 			const localServer = new Server({
 				name: "x402-proxy",
-				version: "0.6.0"
+				version: "0.7.1"
 			}, { capabilities: {
 				tools: tools.length > 0 ? {} : void 0,
 				resources: remoteResources.length > 0 ? {} : void 0
@@ -940,7 +987,7 @@ const routes = buildRouteMap({
 });
 const app = buildApplication(routes, {
 	name: "x402-proxy",
-	versionInfo: { currentVersion: "0.6.0" },
+	versionInfo: { currentVersion: "0.7.1" },
 	scanner: { caseStyle: "allow-kebab-for-camel" }
 });
 

package/dist/index.js

@@ -112,20 +112,24 @@ async function createMppProxyHandler(opts) {
 		async close() {
 			if (session?.opened) {
 				const receipt = await session.close();
-				if (receipt) paymentQueue.push({
-					protocol: "mpp",
-					network: TEMPO_NETWORK,
-					intent: "session",
-					channelId: session.channelId ?? void 0,
-					receipt: {
-						method: receipt.method,
-						reference: receipt.reference,
-						status: receipt.status,
-						timestamp: receipt.timestamp,
-						acceptedCumulative: receipt.acceptedCumulative,
-						txHash: receipt.txHash
-					}
-				});
+				if (receipt) {
+					const spentUsdc = receipt.spent ? (Number(receipt.spent) / 1e6).toString() : void 0;
+					paymentQueue.push({
+						protocol: "mpp",
+						network: TEMPO_NETWORK,
+						intent: "session",
+						amount: spentUsdc,
+						channelId: session.channelId ?? void 0,
+						receipt: {
+							method: receipt.method,
+							reference: receipt.reference,
+							status: receipt.status,
+							timestamp: receipt.timestamp,
+							acceptedCumulative: receipt.acceptedCumulative,
+							txHash: receipt.txHash
+						}
+					});
+				}
 			}
 		}
 	};

package/dist/openclaw/plugin.d.ts

@@ -0,0 +1,55 @@
+import { x402Client } from "@x402/fetch";
+//#region src/openclaw/tools.d.ts
+type ModelEntry = {
+  provider: string;
+  id: string;
+  name: string;
+  maxTokens: number;
+  reasoning: boolean;
+  input: string[];
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+  };
+  contextWindow: number;
+};
+//#endregion
+//#region src/openclaw/plugin.d.ts
+type OpenClawPluginApi = {
+  pluginConfig?: Record<string, unknown>;
+  logger: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+  registerProvider: (provider: {
+    id: string;
+    label: string;
+    auth: unknown[];
+    models: {
+      baseUrl: string;
+      api: string;
+      authHeader: boolean;
+      models: Array<Omit<ModelEntry, "provider"> & {
+        input: Array<"text" | "image">;
+      }>;
+    };
+  }) => void;
+  registerTool: (tool: unknown) => void;
+  registerCommand: (command: unknown) => void;
+  registerService: (service: {
+    id: string;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+  }) => void;
+  registerHttpRoute: (params: {
+    path: string;
+    match: string;
+    auth: string;
+    handler: (req: unknown, res: unknown) => Promise<void>;
+  }) => void;
+};
+declare function register(api: OpenClawPluginApi): void;
+//#endregion
+export { register };