feat(mpp): reuse sessions across requests, persist channelId, settle on shutdown

- Cache MppProxyHandler at serve/plugin level instead of per-request
- Persist channelId to ~/.config/x402-proxy/session.json for tracking
- Send X-Payer-Address header on MPP requests for cross-restart session recovery
- Close MPP session on SIGTERM/stop (serve command + OpenClaw plugin)
- Add --debug global CLI flag (X402_PROXY_DEBUG=1)
- Upgrade mppx ^0.4.9 -> ^0.5.1

Author: tenequm

packages/x402-proxy/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.4] - 2026-04-01
+
+### Fixed
+- MPP sessions now reuse a single handler across requests instead of creating a new one per request - eliminates redundant escrow deposits and wasted USDC
+- MPP sessions properly settle on process shutdown (`serve` command and OpenClaw plugin both call `close()` on SIGTERM/stop)
+- MPP channelId persisted to `~/.config/x402-proxy/session.json` for tracking; cleared on session close
+
+### Added
+- `--debug` global CLI flag - sets `X402_PROXY_DEBUG=1` for verbose stderr logging of MPP SSE lifecycle, channelId, and proxy routing
+- Debug trace points in inference proxy: upstream routing, SSE start/end, usage stats, errors
+
+### Changed
+- Upgraded `mppx` from ^0.4.9 to ^0.5.1
+- MPP requests now send `X-Payer-Address` header so the server can include the payer's existing `channelId` in 402 challenges, enabling cross-restart session recovery
+- Inference proxy no longer accepts `getEvmKey` option - receives pre-built `getMppHandler` instead
+
 ## [0.10.3] - 2026-04-01
 
 ### Fixed
@@ -351,7 +367,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.10.2...HEAD
+[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.10.4...HEAD
+[0.10.4]: https://github.com/cascade-protocol/x402-proxy/compare/v0.10.3...v0.10.4
+[0.10.3]: https://github.com/cascade-protocol/x402-proxy/compare/v0.10.2...v0.10.3
 [0.10.2]: https://github.com/cascade-protocol/x402-proxy/compare/v0.10.1...v0.10.2
 [0.10.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.9.4...v0.10.0

packages/x402-proxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-proxy",
-  "version": "0.10.3",
+  "version": "0.10.4",
   "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,
@@ -63,7 +63,7 @@
     "@x402/mcp": "^2.8.0",
     "@x402/svm": "^2.8.0",
     "ethers": "^6.16.0",
-    "mppx": "^0.4.9",
+    "mppx": "^0.5.1",
     "picocolors": "^1.1.1",
     "viem": "^2.47.6",
     "yaml": "^2.8.3"

packages/x402-proxy/src/bin/cli.ts

@@ -20,6 +20,8 @@ for (let i = 0; i < rawArgs.length; i++) {
     const dir = resolve(a.slice("--config-dir=".length));
     process.env.XDG_CONFIG_HOME = dir;
     process.env.X402_PROXY_CONFIG_DIR_OVERRIDE = dir;
+  } else if (a === "--debug") {
+    process.env.X402_PROXY_DEBUG = "1";
   } else {
     args.push(a);
   }

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

@@ -1,7 +1,7 @@
 import { once } from "node:events";
 import http, { type IncomingMessage, type ServerResponse } from "node:http";
 import { buildCommand, type CommandContext } from "@stricli/core";
-import { createX402ProxyHandler } from "../handler.js";
+import { createMppProxyHandler, createX402ProxyHandler } from "../handler.js";
 import { getHistoryPath, loadConfig } from "../lib/config.js";
 import { dim, error, info, isTTY, success } from "../lib/output.js";
 import { buildX402Client, resolveWallet, type WalletResolution } from "../lib/resolve-wallet.js";
@@ -132,6 +132,9 @@ export async function startServeServer(
     spendLimitPerTx: config?.spendLimitPerTx,
   });
   const x402Proxy = createX402ProxyHandler({ client: x402Client });
+  const mppHandler = wallet.evmKey
+    ? await createMppProxyHandler({ evmKey: wallet.evmKey, maxDeposit: configuredMppBudget })
+    : null;
   const { providers, models } = resolveProviders({
     protocol: resolvedProtocol,
     mppSessionBudget: configuredMppBudget,
@@ -148,9 +151,9 @@ export async function startServeServer(
   const routeHandler = createInferenceProxyRouteHandler({
     providers,
     getX402Proxy: () => x402Proxy,
+    getMppHandler: () => mppHandler,
     getWalletAddress: () => wallet.solanaAddress ?? wallet.evmAddress ?? null,
     getWalletAddressForNetwork: (network) => walletAddressForNetwork(wallet, network),
-    getEvmKey: () => wallet.evmKey ?? null,
     historyPath: getHistoryPath(),
     allModels: models,
     logger: {
@@ -185,6 +188,13 @@ export async function startServeServer(
     server,
     port,
     close: async () => {
+      if (mppHandler) {
+        try {
+          await mppHandler.close();
+        } catch {
+          // best effort
+        }
+      }
       if (!server.listening) return;
       server.close();
       await once(server, "close");

packages/x402-proxy/src/handler.ts

@@ -139,12 +139,15 @@ export async function createMppProxyHandler(opts: {
 }): Promise<MppProxyHandler> {
   const { Mppx, tempo } = await import("mppx/client");
   const { privateKeyToAccount } = await import("viem/accounts");
+  const { saveSession, clearSession } = await import("./lib/config.js");
 
   const account = privateKeyToAccount(opts.evmKey as `0x${string}`);
   const maxDeposit = opts.maxDeposit ?? "1";
   const paymentQueue: MppPaymentInfo[] = [];
   let lastChallengeAmount: string | undefined;
 
+  const debug = process.env.X402_PROXY_DEBUG === "1";
+
   const mppx = Mppx.create({
     methods: [tempo({ account, maxDeposit })],
     polyfill: false,
@@ -157,12 +160,26 @@ export async function createMppProxyHandler(opts: {
     },
   });
 
+  const payerAddress = account.address;
+
+  function injectPayerHeader(init?: RequestInit): RequestInit {
+    const headers = new Headers(init?.headers);
+    headers.set("X-Payer-Address", payerAddress);
+    return { ...init, headers };
+  }
+
   // Lazy session creation - only needed for SSE streaming
   let session: ReturnType<typeof tempo.session> | undefined;
+  let persistedChannelId: string | undefined;
 
   return {
+    // Non-streaming uses stateless one-shot charges (not sessions) - intentional.
+    // Each fetch() handles its own 402 challenge/response cycle independently.
     async fetch(input: string | URL, init?: RequestInit): Promise<Response> {
-      const response = await mppx.fetch(typeof input === "string" ? input : input.toString(), init);
+      const response = await mppx.fetch(
+        typeof input === "string" ? input : input.toString(),
+        injectPayerHeader(init),
+      );
 
       // Extract payment info from Payment-Receipt header
       const receiptHeader = response.headers.get("Payment-Receipt");
@@ -193,7 +210,24 @@ export async function createMppProxyHandler(opts: {
     async sse(input: string | URL, init?: RequestInit): Promise<AsyncIterable<string>> {
       session ??= tempo.session({ account, maxDeposit });
       const url = typeof input === "string" ? input : input.toString();
-      const iterable = await session.sse(url, init as Parameters<typeof session.sse>[1]);
+      const iterable = await session.sse(
+        url,
+        injectPayerHeader(init) as Parameters<typeof session.sse>[1],
+      );
+
+      // Persist channelId for tracking. The server includes channelId in 402
+      // challenges for returning payers, so mppx auto-recovers on restart
+      // via tryRecoverChannel() without any client-side injection.
+      if (session.channelId && session.channelId !== persistedChannelId) {
+        persistedChannelId = session.channelId;
+        if (debug) process.stderr.write(`[x402-proxy] channelId: ${persistedChannelId}\n`);
+        try {
+          saveSession({ channelId: session.channelId, createdAt: new Date().toISOString() });
+        } catch {
+          // Non-critical
+        }
+      }
+
       paymentQueue.push({ protocol: "mpp", network: TEMPO_NETWORK, intent: "session" });
       return iterable;
     },
@@ -203,6 +237,11 @@ export async function createMppProxyHandler(opts: {
     async close(): Promise<void> {
       if (session?.opened) {
         const receipt = await session.close();
+        try {
+          clearSession();
+        } catch {
+          // Non-critical
+        }
         if (receipt) {
           // spent is in USDC base units (6 decimals)
           const spentUsdc = receipt.spent

packages/x402-proxy/src/lib/config.ts

@@ -95,6 +95,42 @@ export function saveConfig(config: ProxyConfig): void {
   fs.writeFileSync(p, stringifyYaml(config), "utf-8");
 }
 
+// --- MPP session persistence ---
+
+export type StoredSession = {
+  channelId: string;
+  createdAt: string;
+};
+
+export function getSessionPath(): string {
+  return path.join(getConfigDir(), "session.json");
+}
+
+export function loadStoredSession(): StoredSession | null {
+  const p = getSessionPath();
+  if (!fs.existsSync(p)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(p, "utf-8"));
+    if (typeof data.channelId === "string") return data as StoredSession;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveSession(session: StoredSession): void {
+  ensureConfigDir();
+  fs.writeFileSync(getSessionPath(), JSON.stringify(session, null, 2), "utf-8");
+}
+
+export function clearSession(): void {
+  try {
+    fs.unlinkSync(getSessionPath());
+  } catch {
+    // file may not exist
+  }
+}
+
 export function isConfigured(): boolean {
   if (process.env.X402_PROXY_WALLET_MNEMONIC) return true;
   if (process.env.X402_PROXY_WALLET_EVM_KEY) return true;

packages/x402-proxy/src/openclaw/plugin.ts

@@ -3,7 +3,12 @@ import { join } from "node:path";
 import { createKeyPairSignerFromBytes, type KeyPairSigner } from "@solana/kit";
 import { x402Client } from "@x402/fetch";
 import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import { createX402ProxyHandler, type X402ProxyHandler } from "../handler.js";
+import {
+  createMppProxyHandler,
+  createX402ProxyHandler,
+  type MppProxyHandler,
+  type X402ProxyHandler,
+} from "../handler.js";
 import { getHistoryPath } from "../lib/config.js";
 import { OptimizedSvmScheme } from "../lib/optimized-svm-scheme.js";
 import { resolveWallet } from "../lib/resolve-wallet.js";
@@ -50,6 +55,7 @@ export function register(api: OpenClawPluginApi): void {
   let evmWalletAddress: string | null = null;
   let signerRef: KeyPairSigner | null = null;
   let proxyRef: X402ProxyHandler | null = null;
+  let mppHandlerRef: MppProxyHandler | null = null;
   let evmKeyRef: string | null = null;
   let walletLoadPromise: Promise<void> | null = null;
 
@@ -61,10 +67,10 @@ export function register(api: OpenClawPluginApi): void {
   const handler = createInferenceProxyRouteHandler({
     providers,
     getX402Proxy: () => proxyRef,
+    getMppHandler: () => mppHandlerRef,
     getWalletAddress: () => solanaWalletAddress ?? evmWalletAddress,
     getWalletAddressForNetwork: (network) =>
       addressForNetwork(evmWalletAddress, solanaWalletAddress, network),
-    getEvmKey: () => evmKeyRef,
     historyPath,
     allModels,
     logger: api.logger,
@@ -122,6 +128,18 @@ export function register(api: OpenClawPluginApi): void {
           proxyRef = null;
         }
 
+        if (evmKeyRef) {
+          const maxBudget = Math.max(
+            ...providers.map((p) => Number(p.mppSessionBudget) || 0.5),
+          ).toString();
+          mppHandlerRef = await createMppProxyHandler({
+            evmKey: evmKeyRef,
+            maxDeposit: maxBudget,
+          });
+        } else {
+          mppHandlerRef = null;
+        }
+
         api.logger.info(
           `wallets: solana=${solanaWalletAddress ?? "missing"} evm=${evmWalletAddress ?? "missing"}`,
         );
@@ -139,7 +157,15 @@ export function register(api: OpenClawPluginApi): void {
     async start() {
       await ensureWalletLoaded();
     },
-    async stop() {},
+    async stop() {
+      if (mppHandlerRef) {
+        try {
+          await mppHandlerRef.close();
+        } catch {
+          // best effort
+        }
+      }
+    },
   });
 
   const toolCtx = {