x402-proxy 0.1.2 → 0.2.1

package/README.md

@@ -1,87 +1,117 @@
 # x402-proxy
 
-Generic [x402](https://www.x402.org/) payment proxy library for Solana and EVM USDC. Wraps `fetch` with automatic x402 payment handling, tracks transaction history, and provides wallet loading utilities.
+`curl` for [x402](https://www.x402.org/) paid APIs. Auto-pays HTTP 402 responses with USDC on Base and Solana - zero crypto code on the buyer side.
 
-## Install
+## Quick Start
 
 ```bash
-npm install x402-proxy
+npx x402-proxy https://twitter.surf.cascade.fyi/search?q=cascade_fyi
 ```
 
-Peer dependencies: `@solana/kit`, `ethers`, `viem`
+That's it. The endpoint returns 402, x402-proxy pays and streams the response.
 
-## Usage
+First time? Set up a wallet:
 
-```ts
-import {
-  x402Client,
-  ExactSvmScheme,
-  ExactEvmScheme,
-  createX402ProxyHandler,
-  extractTxSignature,
-  loadSvmWallet,
-  loadEvmWallet,
-} from "x402-proxy";
+```bash
+npx x402-proxy setup          # generate wallet from BIP-39 mnemonic
+npx x402-proxy wallet fund    # see where to send USDC
+```
+
+One mnemonic derives both EVM (Base) and Solana keypairs. Fund either chain and go.
 
-// 1. Configure the x402 client with payment schemes
-const svmWallet = await loadSvmWallet("/path/to/keypair.json");
-const client = x402Client([ExactSvmScheme(svmWallet)]);
+## MCP Proxy
 
-// 2. Create the proxy handler
-const { x402Fetch, shiftPayment } = createX402ProxyHandler({ client });
+Let your AI agent consume any paid MCP server. Configure in Claude, Cursor, or any MCP client:
 
-// 3. Make requests - payments are handled automatically
-const response = await x402Fetch("https://api.example.com/paid-endpoint");
-const payment = shiftPayment(); // { network, payTo, amount, asset }
-const txSig = extractTxSignature(response);
+```json
+{
+  "mcpServers": {
+    "paid-service": {
+      "command": "npx",
+      "args": ["x402-proxy", "mcp", "https://mcp.example.com/sse"],
+      "env": {
+        "X402_PROXY_WALLET_MNEMONIC": "your 24 words here"
+      }
+    }
+  }
+}
 ```
 
-### Transaction history
+The proxy sits between your agent and the remote server, intercepting 402 responses, paying automatically, and forwarding the result. Your agent never touches crypto.
 
-```ts
-import { appendHistory, readHistory, calcSpend, formatTxLine } from "x402-proxy";
-
-// Append a transaction record
-appendHistory("/path/to/history.jsonl", {
-  t: Date.now(),
-  ok: true,
-  kind: "x402_inference",
-  net: "solana:mainnet",
-  from: "J5UH...",
-  tx: "5abc...",
-  amount: 0.05,
-  token: "USDC",
-  model: "claude-sonnet-4-20250514",
-});
-
-// Read and aggregate
-const records = readHistory("/path/to/history.jsonl");
-const { today, total, count } = calcSpend(records);
+## HTTP Requests
+
+Works like curl. Response body streams to stdout, payment info goes to stderr.
+
+```bash
+# GET request
+x402-proxy https://twitter.surf.cascade.fyi/search?q=x402
+
+# POST with body and headers
+x402-proxy --method POST \
+  --header "Content-Type: application/json" \
+  --body '{"url":"https://x402.org"}' \
+  https://web.surf.cascade.fyi/v1/crawl
+
+# Pipe-safe
+x402-proxy https://api.example.com/data | jq '.results'
+```
+
+## Commands
+
+```bash
+x402-proxy <url>                    # paid HTTP request (default command)
+x402-proxy mcp <url>                # MCP stdio proxy for agents
+x402-proxy setup                    # onboarding wizard
+x402-proxy status                   # config + wallet + spend summary
+x402-proxy wallet                   # show addresses
+x402-proxy wallet history           # payment history
+x402-proxy wallet fund              # funding instructions
+x402-proxy wallet export-key <chain> # bare key to stdout (evm|solana)
 ```
 
-## API
+All commands support `--help` for details.
+
+## Wallet
+
+A single BIP-39 mnemonic derives both chains:
+- **Solana:** SLIP-10 Ed25519 at `m/44'/501'/0'/0'`
+- **EVM:** BIP-32 secp256k1 at `m/44'/60'/0'/0/0`
 
-### Payment proxy
+Config stored at `$XDG_CONFIG_HOME/x402-proxy/` (default `~/.config/x402-proxy/`).
+
+### Export keys for other tools
+
+```bash
+# Pipe-safe - outputs bare key to stdout
+MY_KEY=$(npx x402-proxy wallet export-key evm)
+```
 
-- `createX402ProxyHandler(opts)` - wraps fetch with automatic x402 payment. Returns `{ x402Fetch, shiftPayment }`
-- `extractTxSignature(response)` - extracts on-chain TX signature from payment response headers
+## Env Vars
 
-### Wallet loading
+Override wallet per-instance (useful for MCP configs):
 
-- `loadSvmWallet(path)` - load Solana keypair from solana-keygen JSON file
-- `loadEvmWallet(path)` - load EVM wallet from hex private key file
+```
+X402_PROXY_WALLET_MNEMONIC     # BIP-39 mnemonic (derives both chains)
+X402_PROXY_WALLET_EVM_KEY      # EVM private key (hex)
+X402_PROXY_WALLET_SOLANA_KEY   # Solana private key (base58)
+```
 
-### Transaction history
+Resolution order: flags > env vars > mnemonic env > `wallet.json` file.
 
-- `appendHistory(path, record)` - append a `TxRecord` to a JSONL file (auto-truncates at 1000 lines)
-- `readHistory(path)` - read all records from a JSONL history file
-- `calcSpend(records)` - aggregate USDC spend (today/total/count)
-- `explorerUrl(net, tx)` - generate block explorer URL (Solscan, Basescan, Etherscan)
-- `formatTxLine(record)` - format a record as a markdown line with explorer link
+## Library Usage
 
-### Re-exports
+```ts
+import {
+  createX402ProxyHandler,
+  extractTxSignature,
+  appendHistory,
+  readHistory,
+  calcSpend,
+} from "x402-proxy";
+```
 
-- `x402Client`, `ExactSvmScheme`, `ExactEvmScheme`, `toClientEvmSigner` - from `@x402/fetch`, `@x402/svm`, `@x402/evm`
+See the [library API docs](https://github.com/cascade-protocol/x402-proxy/tree/main/packages/x402-proxy#library-api) for details.
 
 ## License
 

package/dist/bin/cli.js

@@ -0,0 +1,596 @@
+#!/usr/bin/env node
+import { C as readHistory, S as formatTxLine, _ as isConfigured, a as deriveEvmKeypair, b as appendHistory, c as dim, d as isTTY, f as warn, g as getWalletPath, h as getHistoryPath, i as resolveWallet, l as error, m as getConfigDir, n as statusCommand, o as deriveSolanaKeypair, p as ensureConfigDir, r as buildX402Client, s as generateMnemonic, u as info, v as saveConfig, x as calcSpend, y as saveWalletFile } from "../status-J-RoszDZ.js";
+import { buildApplication, buildCommand, buildRouteMap, run } from "@stricli/core";
+import pc from "picocolors";
+import { decodePaymentResponseHeader, wrapFetchWithPayment } from "@x402/fetch";
+import { base58 } from "@scure/base";
+import * as prompts from "@clack/prompts";
+
+//#region src/handler.ts
+/**
+* Extract the on-chain transaction signature from an x402 payment response header.
+*/
+function extractTxSignature(response) {
+	const header = response.headers.get("PAYMENT-RESPONSE") ?? response.headers.get("X-PAYMENT-RESPONSE");
+	if (!header) return void 0;
+	try {
+		return decodePaymentResponseHeader(header).transaction ?? void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Create an x402 proxy handler that wraps fetch with automatic payment.
+*
+* Chain-agnostic: accepts a pre-configured x402Client with any registered
+* schemes (SVM, EVM, etc). The handler captures payment info via the
+* onAfterPaymentCreation hook. Callers use `x402Fetch` for requests that
+* may require x402 payment, and `shiftPayment` to retrieve captured
+* payment info after each call.
+*/
+function createX402ProxyHandler(opts) {
+	const { client } = opts;
+	const paymentQueue = [];
+	client.onAfterPaymentCreation(async (hookCtx) => {
+		const raw = hookCtx.selectedRequirements.amount;
+		paymentQueue.push({
+			network: hookCtx.selectedRequirements.network,
+			payTo: hookCtx.selectedRequirements.payTo,
+			amount: raw?.startsWith("debug.") ? raw.slice(6) : raw,
+			asset: hookCtx.selectedRequirements.asset
+		});
+	});
+	return {
+		x402Fetch: wrapFetchWithPayment(globalThis.fetch, client),
+		shiftPayment: () => paymentQueue.shift()
+	};
+}
+
+//#endregion
+//#region src/commands/fetch.ts
+const fetchCommand = buildCommand({
+	docs: { brief: "Make a paid HTTP request (default command)" },
+	parameters: {
+		flags: {
+			method: {
+				kind: "parsed",
+				brief: "HTTP method",
+				parse: String,
+				default: "GET"
+			},
+			body: {
+				kind: "parsed",
+				brief: "Request body",
+				parse: String,
+				optional: true
+			},
+			header: {
+				kind: "parsed",
+				brief: "HTTP header (Key: Value), repeatable",
+				parse: String,
+				variadic: true,
+				optional: true
+			},
+			evmKey: {
+				kind: "parsed",
+				brief: "EVM private key (hex)",
+				parse: String,
+				optional: true
+			},
+			solanaKey: {
+				kind: "parsed",
+				brief: "Solana private key (base58)",
+				parse: String,
+				optional: true
+			},
+			json: {
+				kind: "boolean",
+				brief: "Force JSON output",
+				default: false
+			}
+		},
+		positional: {
+			kind: "tuple",
+			parameters: [{
+				brief: "URL to request",
+				parse: String,
+				optional: true
+			}]
+		}
+	},
+	async func(flags, url) {
+		if (!url) {
+			if (isConfigured()) {
+				const { displayStatus } = await import("../status-DnxuVdOP.js");
+				displayStatus();
+			} else {
+				console.log();
+				console.log(pc.cyan("x402-proxy") + pc.dim(" - pay for any x402 resource"));
+				console.log();
+				console.log(pc.dim("  Get started:"));
+				console.log(`    ${pc.cyan("x402-proxy setup")}          Create a wallet`);
+				console.log(`    ${pc.cyan("x402-proxy <url>")}          Make a paid request`);
+				console.log(`    ${pc.cyan("x402-proxy mcp <url>")}      MCP proxy for agents`);
+				console.log(`    ${pc.cyan("x402-proxy wallet")}         Wallet info`);
+				console.log(`    ${pc.cyan("x402-proxy --help")}         All commands`);
+				console.log();
+			}
+			return;
+		}
+		let parsedUrl;
+		try {
+			parsedUrl = new URL(url);
+		} catch {
+			error(`Invalid URL: ${url}`);
+			process.exit(1);
+		}
+		const wallet = resolveWallet({
+			evmKey: flags.evmKey,
+			solanaKey: flags.solanaKey
+		});
+		if (wallet.source === "none") {
+			error("No wallet configured.");
+			console.error(pc.dim(`Run ${pc.cyan("x402-proxy setup")} or set X402_PROXY_WALLET_MNEMONIC`));
+			process.exit(1);
+		}
+		const { x402Fetch, shiftPayment } = createX402ProxyHandler({ client: await buildX402Client(wallet) });
+		const headers = new Headers();
+		if (flags.header) for (const h of flags.header) {
+			const idx = h.indexOf(":");
+			if (idx > 0) headers.set(h.slice(0, idx).trim(), h.slice(idx + 1).trim());
+		}
+		const method = flags.method || "GET";
+		const init = {
+			method,
+			headers
+		};
+		if (flags.body) init.body = flags.body;
+		if (isTTY()) dim(`  ${method} ${parsedUrl.toString()}`);
+		const startMs = Date.now();
+		let response;
+		try {
+			response = await x402Fetch(parsedUrl.toString(), init);
+		} catch (err) {
+			error(`Request failed: ${err instanceof Error ? err.message : String(err)}`);
+			process.exit(1);
+		}
+		const elapsedMs = Date.now() - startMs;
+		const payment = shiftPayment();
+		const txSig = extractTxSignature(response);
+		if (payment && isTTY()) {
+			info(`  Payment: ${payment.amount ?? "?"} (${payment.network ?? "unknown"})`);
+			if (txSig) dim(`  Tx: ${txSig}`);
+		}
+		if (isTTY()) dim(`  ${response.status} ${response.statusText} (${elapsedMs}ms)`);
+		if (payment) {
+			ensureConfigDir();
+			const record = {
+				t: Date.now(),
+				ok: response.ok,
+				kind: "x402_payment",
+				net: payment.network ?? "unknown",
+				from: wallet.evmAddress ?? wallet.solanaAddress ?? "unknown",
+				to: payment.payTo,
+				tx: txSig,
+				amount: payment.amount ? Number(payment.amount) / 1e6 : void 0,
+				token: "USDC",
+				ms: elapsedMs,
+				label: parsedUrl.hostname
+			};
+			appendHistory(getHistoryPath(), record);
+		}
+		if (response.body) {
+			const reader = response.body.getReader();
+			try {
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					process.stdout.write(value);
+				}
+			} finally {
+				reader.releaseLock();
+			}
+		}
+		if (isTTY() && response.body) process.stdout.write("\n");
+	}
+});
+
+//#endregion
+//#region src/commands/mcp.ts
+const mcpCommand = buildCommand({
+	docs: { brief: "Start MCP stdio proxy with x402 payment (alpha)" },
+	parameters: {
+		flags: {
+			evmKey: {
+				kind: "parsed",
+				brief: "EVM private key (hex)",
+				parse: String,
+				optional: true
+			},
+			solanaKey: {
+				kind: "parsed",
+				brief: "Solana private key (base58)",
+				parse: String,
+				optional: true
+			}
+		},
+		positional: {
+			kind: "tuple",
+			parameters: [{
+				brief: "Remote MCP server URL",
+				parse: String
+			}]
+		}
+	},
+	async func(flags, remoteUrl) {
+		const wallet = resolveWallet({
+			evmKey: flags.evmKey,
+			solanaKey: flags.solanaKey
+		});
+		if (wallet.source === "none") {
+			error("No wallet configured. Set X402_PROXY_WALLET_MNEMONIC or run x402-proxy setup.");
+			process.exit(1);
+		}
+		warn("Note: MCP proxy is alpha - please report issues.");
+		dim(`x402-proxy MCP proxy -> ${remoteUrl}`);
+		if (wallet.evmAddress) dim(`  EVM:    ${wallet.evmAddress}`);
+		if (wallet.solanaAddress) dim(`  Solana: ${wallet.solanaAddress}`);
+		const x402PaymentClient = await buildX402Client(wallet);
+		const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+		const { SSEClientTransport } = await import("@modelcontextprotocol/sdk/client/sse.js");
+		const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+		const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+		const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+		const { x402MCPClient } = await import("@x402/mcp");
+		const x402Mcp = new x402MCPClient(new Client({
+			name: "x402-proxy",
+			version: "0.2.0"
+		}), x402PaymentClient, {
+			autoPayment: true,
+			onPaymentRequested: (ctx) => {
+				const accept = ctx.paymentRequired.accepts?.[0];
+				if (accept) warn(`  Payment: ${accept.amount} on ${accept.network} for tool "${ctx.toolName}"`);
+				return true;
+			}
+		});
+		x402Mcp.onAfterPayment(async (ctx) => {
+			ensureConfigDir();
+			const tx = ctx.settleResponse?.transaction;
+			const accept = ctx.paymentPayload;
+			const record = {
+				t: Date.now(),
+				ok: true,
+				kind: "x402_payment",
+				net: accept.network ?? "unknown",
+				from: wallet.evmAddress ?? wallet.solanaAddress ?? "unknown",
+				tx: typeof tx === "string" ? tx : void 0,
+				token: "USDC",
+				label: `mcp:${ctx.toolName}`
+			};
+			appendHistory(getHistoryPath(), record);
+		});
+		let connected = false;
+		try {
+			const transport = new StreamableHTTPClientTransport(new URL(remoteUrl));
+			await x402Mcp.connect(transport);
+			connected = true;
+			dim("  Connected via StreamableHTTP");
+		} catch {}
+		if (!connected) try {
+			const transport = new SSEClientTransport(new URL(remoteUrl));
+			await x402Mcp.connect(transport);
+			connected = true;
+			dim("  Connected via SSE");
+		} catch (err) {
+			error(`Failed to connect to ${remoteUrl}: ${err instanceof Error ? err.message : String(err)}`);
+			process.exit(1);
+		}
+		const { tools } = await x402Mcp.listTools();
+		dim(`  ${tools.length} tools available`);
+		const localServer = new McpServer({
+			name: "x402-proxy",
+			version: "0.2.0"
+		});
+		for (const tool of tools) localServer.tool(tool.name, tool.description ?? "", tool.inputSchema?.properties ? Object.fromEntries(Object.entries(tool.inputSchema.properties).map(([k, v]) => [k, v])) : {}, async (args) => {
+			const result = await x402Mcp.callTool(tool.name, args);
+			return {
+				content: result.content,
+				isError: result.isError
+			};
+		});
+		try {
+			const { resources } = await x402Mcp.listResources();
+			if (resources.length > 0) {
+				dim(`  ${resources.length} resources available`);
+				for (const resource of resources) localServer.resource(resource.name, resource.uri, resource.description ? { description: resource.description } : {}, async (uri) => {
+					return { contents: (await x402Mcp.readResource({ uri: uri.href })).contents.map((c) => ({
+						uri: c.uri,
+						text: "text" in c ? c.text : ""
+					})) };
+				});
+			}
+		} catch {}
+		const stdioTransport = new StdioServerTransport();
+		await localServer.connect(stdioTransport);
+		dim("  MCP proxy running (stdio)");
+		process.stdin.on("end", async () => {
+			await x402Mcp.close();
+			process.exit(0);
+		});
+	}
+});
+
+//#endregion
+//#region src/commands/setup.ts
+const setupCommand = buildCommand({
+	docs: { brief: "Set up x402-proxy with a new wallet" },
+	parameters: {
+		flags: { force: {
+			kind: "boolean",
+			brief: "Overwrite existing configuration",
+			default: false
+		} },
+		positional: {
+			kind: "tuple",
+			parameters: []
+		}
+	},
+	async func(flags) {
+		if (isConfigured() && !flags.force) {
+			prompts.log.warn(`Already configured. Wallet at ${pc.dim(getWalletPath())}\nUse ${pc.cyan("x402-proxy setup --force")} to reconfigure.`);
+			return;
+		}
+		prompts.intro(pc.cyan("x402-proxy setup"));
+		prompts.log.info("This will generate a single BIP-39 mnemonic that derives wallets for both Solana and EVM chains.");
+		const action = await prompts.select({
+			message: "How would you like to set up your wallet?",
+			options: [{
+				value: "generate",
+				label: "Generate a new mnemonic"
+			}, {
+				value: "import",
+				label: "Import an existing mnemonic"
+			}]
+		});
+		if (prompts.isCancel(action)) {
+			prompts.cancel("Setup cancelled.");
+			process.exit(0);
+		}
+		let mnemonic;
+		if (action === "generate") {
+			mnemonic = generateMnemonic();
+			prompts.log.warn("Write down your mnemonic and store it safely. It will NOT be shown again.");
+			prompts.log.message(pc.bold(mnemonic));
+		} else {
+			const input = await prompts.text({
+				message: "Enter your 24-word mnemonic:",
+				validate: (v = "") => {
+					const words = v.trim().split(/\s+/);
+					if (words.length !== 12 && words.length !== 24) return "Mnemonic must be 12 or 24 words";
+				}
+			});
+			if (prompts.isCancel(input)) {
+				prompts.cancel("Setup cancelled.");
+				process.exit(0);
+			}
+			mnemonic = input.trim();
+		}
+		const evm = deriveEvmKeypair(mnemonic);
+		const sol = deriveSolanaKeypair(mnemonic);
+		prompts.log.success(`EVM address:    ${pc.green(evm.address)}`);
+		prompts.log.success(`Solana address: ${pc.green(sol.address)}`);
+		saveWalletFile({
+			version: 1,
+			mnemonic,
+			addresses: {
+				evm: evm.address,
+				solana: sol.address
+			}
+		});
+		saveConfig({});
+		prompts.log.info(`Config directory: ${pc.dim(getConfigDir())}`);
+		prompts.log.step("Fund your wallets to start using x402 resources:");
+		prompts.log.message(`  Solana (USDC): Send USDC to ${pc.cyan(sol.address)}`);
+		prompts.log.message(`  EVM (USDC):    Send USDC to ${pc.cyan(evm.address)} on Base`);
+		prompts.outro(pc.green("Setup complete!"));
+	}
+});
+
+//#endregion
+//#region src/commands/wallet.ts
+const walletInfoCommand = buildCommand({
+	docs: { brief: "Show wallet addresses" },
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: []
+		}
+	},
+	func() {
+		const wallet = resolveWallet();
+		if (wallet.source === "none") {
+			console.log(pc.yellow("No wallet configured."));
+			console.log(pc.dim(`Run ${pc.cyan("x402-proxy setup")} to create one.`));
+			console.log(pc.dim(`Or set ${pc.cyan("X402_PROXY_WALLET_MNEMONIC")} environment variable.`));
+			process.exit(1);
+		}
+		console.log();
+		info("Wallet");
+		console.log();
+		console.log(pc.dim(`  Source: ${wallet.source}`));
+		if (wallet.evmAddress) console.log(`  EVM:    ${pc.green(wallet.evmAddress)}`);
+		if (wallet.solanaAddress) console.log(`  Solana: ${pc.green(wallet.solanaAddress)}`);
+		console.log();
+	}
+});
+
+//#endregion
+//#region src/commands/wallet-export.ts
+const walletExportCommand = buildCommand({
+	docs: { brief: "Export private key to stdout (pipe-safe)" },
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [{
+				brief: "Chain to export: evm or solana",
+				parse: (input) => {
+					const v = input.toLowerCase();
+					if (v !== "evm" && v !== "solana") throw new Error("Must be 'evm' or 'solana'");
+					return v;
+				}
+			}]
+		}
+	},
+	func(flags, chain) {
+		const wallet = resolveWallet();
+		if (wallet.source === "none") {
+			error("No wallet configured.");
+			process.exit(1);
+		}
+		if (chain === "evm") {
+			if (!wallet.evmKey) {
+				error("No EVM key available.");
+				process.exit(1);
+			}
+			warn("Warning: private key will be printed to stdout.");
+			process.stdout.write(wallet.evmKey);
+		} else {
+			if (!wallet.solanaKey) {
+				error("No Solana key available.");
+				process.exit(1);
+			}
+			warn("Warning: private key will be printed to stdout.");
+			process.stdout.write(base58.encode(wallet.solanaKey.slice(0, 32)));
+		}
+	}
+});
+
+//#endregion
+//#region src/commands/wallet-fund.ts
+const walletFundCommand = buildCommand({
+	docs: { brief: "Show wallet funding instructions" },
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: []
+		}
+	},
+	func() {
+		const wallet = resolveWallet();
+		if (wallet.source === "none") {
+			console.log(pc.yellow("No wallet configured."));
+			console.log(pc.dim(`Run ${pc.cyan("x402-proxy setup")} to create one.`));
+			process.exit(1);
+		}
+		console.log();
+		info("Funding Instructions");
+		console.log();
+		if (wallet.solanaAddress) {
+			console.log(pc.bold("  Solana (USDC):"));
+			console.log(`  Send USDC to: ${pc.green(wallet.solanaAddress)}`);
+			console.log(pc.dim("  Network: Solana Mainnet"));
+			console.log();
+		}
+		if (wallet.evmAddress) {
+			console.log(pc.bold("  Base (USDC):"));
+			console.log(`  Send USDC to: ${pc.green(wallet.evmAddress)}`);
+			console.log(pc.dim("  Network: Base (Chain ID 8453)"));
+			console.log();
+		}
+		console.log(pc.dim("  Tip: Most x402 services accept USDC on Base or Solana."));
+		console.log();
+	}
+});
+
+//#endregion
+//#region src/commands/wallet-history.ts
+const walletHistoryCommand = buildCommand({
+	docs: { brief: "Show payment history" },
+	parameters: {
+		flags: {
+			limit: {
+				kind: "parsed",
+				brief: "Number of entries to show",
+				parse: Number,
+				default: "20"
+			},
+			json: {
+				kind: "boolean",
+				brief: "Output raw JSONL",
+				default: false
+			}
+		},
+		positional: {
+			kind: "tuple",
+			parameters: []
+		}
+	},
+	func(flags) {
+		const records = readHistory(getHistoryPath());
+		if (records.length === 0) {
+			console.log(pc.dim("No payment history yet."));
+			return;
+		}
+		if (flags.json) {
+			const slice = records.slice(-flags.limit);
+			for (const r of slice) process.stdout.write(`${JSON.stringify(r)}\n`);
+			return;
+		}
+		const spend = calcSpend(records);
+		const slice = records.slice(-flags.limit);
+		console.log();
+		info("Payment History");
+		console.log();
+		for (const r of slice) {
+			const line = formatTxLine(r).replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+			console.log(line);
+		}
+		console.log();
+		console.log(pc.dim(`  Today: ${spend.today.toFixed(4)} USDC | Total: ${spend.total.toFixed(4)} USDC | ${spend.count} transactions`));
+		console.log();
+	}
+});
+
+//#endregion
+//#region src/app.ts
+const routes = buildRouteMap({
+	routes: {
+		fetch: fetchCommand,
+		mcp: mcpCommand,
+		wallet: buildRouteMap({
+			routes: {
+				info: walletInfoCommand,
+				history: walletHistoryCommand,
+				fund: walletFundCommand,
+				"export-key": walletExportCommand
+			},
+			defaultCommand: "info",
+			docs: { brief: "Wallet management" }
+		}),
+		setup: setupCommand,
+		status: statusCommand
+	},
+	defaultCommand: "fetch",
+	docs: { brief: "curl for x402 paid APIs" }
+});
+const app = buildApplication(routes, {
+	name: "x402-proxy",
+	versionInfo: { currentVersion: "0.2.1" },
+	scanner: { caseStyle: "allow-kebab-for-camel" }
+});
+
+//#endregion
+//#region src/context.ts
+function buildContext(process) {
+	return { process };
+}
+
+//#endregion
+//#region src/bin/cli.ts
+await run(app, process.argv.slice(2), buildContext(process));
+
+//#endregion
+export {  };

package/dist/index.js

@@ -119,10 +119,7 @@ const KIND_LABELS = {
 };
 function explorerUrl(net, tx) {
 	if (net.startsWith("eip155:")) {
-		const chainId = net.split(":")[1];
-		if (chainId === "8453") return `https://basescan.org/tx/${tx}`;
-		if (chainId === "84532") return `https://sepolia.basescan.org/tx/${tx}`;
-		if (chainId === "1") return `https://etherscan.io/tx/${tx}`;
+		if (net.split(":")[1] === "8453") return `https://basescan.org/tx/${tx}`;
 		return `https://basescan.org/tx/${tx}`;
 	}
 	return `https://solscan.io/tx/${tx}`;

package/dist/status-DnxuVdOP.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { n as statusCommand, t as displayStatus } from "./status-J-RoszDZ.js";
+
+export { displayStatus };

package/dist/status-J-RoszDZ.js

@@ -0,0 +1,409 @@
+#!/usr/bin/env node
+import { buildCommand } from "@stricli/core";
+import pc from "picocolors";
+import { x402Client } from "@x402/fetch";
+import fs, { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { base58 } from "@scure/base";
+import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
+import { ExactSvmScheme } from "@x402/svm/exact/client";
+import { createPublicClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base } from "viem/chains";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { HDKey } from "@scure/bip32";
+import { generateMnemonic, mnemonicToSeedSync } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+
+//#region src/history.ts
+const HISTORY_MAX_LINES = 1e3;
+const HISTORY_KEEP_LINES = 500;
+function appendHistory(historyPath, record) {
+	try {
+		appendFileSync(historyPath, `${JSON.stringify(record)}\n`);
+		if (existsSync(historyPath)) {
+			if (statSync(historyPath).size > HISTORY_MAX_LINES * 200) {
+				const lines = readFileSync(historyPath, "utf-8").trimEnd().split("\n");
+				if (lines.length > HISTORY_MAX_LINES) writeFileSync(historyPath, `${lines.slice(-HISTORY_KEEP_LINES).join("\n")}\n`);
+			}
+		}
+	} catch {}
+}
+function readHistory(historyPath) {
+	try {
+		if (!existsSync(historyPath)) return [];
+		const content = readFileSync(historyPath, "utf-8").trimEnd();
+		if (!content) return [];
+		return content.split("\n").flatMap((line) => {
+			try {
+				const parsed = JSON.parse(line);
+				if (typeof parsed.t !== "number" || typeof parsed.kind !== "string") return [];
+				return [parsed];
+			} catch {
+				return [];
+			}
+		});
+	} catch {
+		return [];
+	}
+}
+function calcSpend(records) {
+	const todayStart = /* @__PURE__ */ new Date();
+	todayStart.setUTCHours(0, 0, 0, 0);
+	const todayMs = todayStart.getTime();
+	let today = 0;
+	let total = 0;
+	let count = 0;
+	for (const r of records) {
+		if (!r.ok || r.amount == null) continue;
+		if (r.token !== "USDC") continue;
+		total += r.amount;
+		count++;
+		if (r.t >= todayMs) today += r.amount;
+	}
+	return {
+		today,
+		total,
+		count
+	};
+}
+function formatAmount(amount, token) {
+	if (token === "USDC") {
+		if (amount >= .01) return `${amount.toFixed(2)} USDC`;
+		if (amount >= .001) return `${amount.toFixed(3)} USDC`;
+		if (amount >= 1e-4) return `${amount.toFixed(4)} USDC`;
+		return `${amount.toFixed(6)} USDC`;
+	}
+	if (token === "SOL") return `${amount} SOL`;
+	return `${amount} ${token}`;
+}
+const KIND_LABELS = {
+	x402_inference: "inference",
+	x402_payment: "payment",
+	transfer: "transfer",
+	buy: "buy",
+	sell: "sell",
+	mint: "mint",
+	swap: "swap"
+};
+function explorerUrl(net, tx) {
+	if (net.startsWith("eip155:")) {
+		if (net.split(":")[1] === "8453") return `https://basescan.org/tx/${tx}`;
+		return `https://basescan.org/tx/${tx}`;
+	}
+	return `https://solscan.io/tx/${tx}`;
+}
+/** Strip provider prefix and OpenRouter date suffixes from model IDs.
+*  e.g. "minimax/minimax-m2.5-20260211" -> "minimax-m2.5"
+*       "moonshotai/kimi-k2.5-0127" -> "kimi-k2.5" */
+function shortModel(model) {
+	const parts = model.split("/");
+	return parts[parts.length - 1].replace(/-\d{6,8}$/, "").replace(/-\d{4}$/, "");
+}
+function formatTxLine(r) {
+	const time = new Date(r.t).toLocaleTimeString("en-US", {
+		hour: "2-digit",
+		minute: "2-digit",
+		hour12: false,
+		timeZone: "UTC"
+	});
+	const timeStr = r.tx ? `[${time}](${explorerUrl(r.net, r.tx)})` : time;
+	const parts = [r.kind === "x402_inference" && r.model ? shortModel(r.model) : KIND_LABELS[r.kind] ?? r.kind];
+	if (r.label) parts.push(r.label);
+	if (r.ok && r.amount != null && r.token) parts.push(formatAmount(r.amount, r.token));
+	else if (r.ok && r.kind === "sell" && r.meta?.pct != null) parts.push(`${r.meta.pct}%`);
+	return `  ${timeStr} ${r.ok ? "" : "✗ "}${parts.join(" · ")}`;
+}
+
+//#endregion
+//#region src/lib/config.ts
+const APP_NAME = "x402-proxy";
+function getConfigDir() {
+	const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+	return path.join(xdg, APP_NAME);
+}
+function getWalletPath() {
+	return path.join(getConfigDir(), "wallet.json");
+}
+function getHistoryPath() {
+	return path.join(getConfigDir(), "history.jsonl");
+}
+function ensureConfigDir() {
+	fs.mkdirSync(getConfigDir(), { recursive: true });
+}
+function loadWalletFile() {
+	const p = getWalletPath();
+	if (!fs.existsSync(p)) return null;
+	try {
+		const data = JSON.parse(fs.readFileSync(p, "utf-8"));
+		if (data.version === 1 && typeof data.mnemonic === "string") return data;
+		return null;
+	} catch {
+		return null;
+	}
+}
+function saveWalletFile(wallet) {
+	ensureConfigDir();
+	fs.writeFileSync(getWalletPath(), JSON.stringify(wallet, null, 2), {
+		mode: 384,
+		encoding: "utf-8"
+	});
+}
+function loadConfig() {
+	const dir = getConfigDir();
+	for (const name of [
+		"config.yaml",
+		"config.yml",
+		"config.jsonc",
+		"config.json"
+	]) {
+		const p = path.join(dir, name);
+		if (!fs.existsSync(p)) continue;
+		try {
+			const raw = fs.readFileSync(p, "utf-8");
+			if (name.endsWith(".yaml") || name.endsWith(".yml")) return parse(raw);
+			if (name.endsWith(".jsonc")) {
+				const stripped = raw.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+				return JSON.parse(stripped);
+			}
+			return JSON.parse(raw);
+		} catch {}
+	}
+	return null;
+}
+function saveConfig(config) {
+	ensureConfigDir();
+	const p = path.join(getConfigDir(), "config.yaml");
+	fs.writeFileSync(p, stringify(config), "utf-8");
+}
+function isConfigured() {
+	if (process.env.X402_PROXY_WALLET_MNEMONIC) return true;
+	if (process.env.X402_PROXY_WALLET_EVM_KEY) return true;
+	if (process.env.X402_PROXY_WALLET_SOLANA_KEY) return true;
+	return loadWalletFile() !== null;
+}
+
+//#endregion
+//#region src/lib/output.ts
+function isTTY() {
+	return !!process.stderr.isTTY;
+}
+function info(msg) {
+	process.stderr.write(`${isTTY() ? pc.cyan(msg) : msg}\n`);
+}
+function warn(msg) {
+	process.stderr.write(`${isTTY() ? pc.yellow(msg) : msg}\n`);
+}
+function error(msg) {
+	process.stderr.write(`${isTTY() ? pc.red(msg) : msg}\n`);
+}
+function dim(msg) {
+	process.stderr.write(`${isTTY() ? pc.dim(msg) : msg}\n`);
+}
+
+//#endregion
+//#region src/lib/derive.ts
+/**
+* Wallet derivation from BIP-39 mnemonic.
+*
+* A single 24-word mnemonic is the root secret. Both Solana and EVM keypairs
+* are deterministically derived from it.
+*
+* Solana: SLIP-10 Ed25519 at m/44'/501'/0'/0'
+* EVM:    BIP-32 secp256k1  at m/44'/60'/0'/0/0
+*
+* Ported from agentbox/packages/openclaw-x402/src/wallet.ts
+*/
+function generateMnemonic$1() {
+	return generateMnemonic(wordlist, 256);
+}
+/**
+* SLIP-10 Ed25519 derivation at m/44'/501'/0'/0' (Phantom/Backpack compatible).
+*/
+const enc = new TextEncoder();
+function deriveSolanaKeypair(mnemonic) {
+	const seed = mnemonicToSeedSync(mnemonic);
+	let I = hmac(sha512, enc.encode("ed25519 seed"), seed);
+	let key = I.slice(0, 32);
+	let chainCode = I.slice(32);
+	for (const index of [
+		2147483692,
+		2147484149,
+		2147483648,
+		2147483648
+	]) {
+		const data = new Uint8Array(37);
+		data[0] = 0;
+		data.set(key, 1);
+		data[33] = index >>> 24 & 255;
+		data[34] = index >>> 16 & 255;
+		data[35] = index >>> 8 & 255;
+		data[36] = index & 255;
+		I = hmac(sha512, chainCode, data);
+		key = I.slice(0, 32);
+		chainCode = I.slice(32);
+	}
+	const secretKey = new Uint8Array(key);
+	const publicKey = ed25519.getPublicKey(secretKey);
+	return {
+		secretKey,
+		publicKey,
+		address: base58.encode(publicKey)
+	};
+}
+/**
+* BIP-32 secp256k1 derivation at m/44'/60'/0'/0/0.
+*/
+function deriveEvmKeypair(mnemonic) {
+	const seed = mnemonicToSeedSync(mnemonic);
+	const derived = HDKey.fromMasterSeed(seed).derive("m/44'/60'/0'/0/0");
+	if (!derived.privateKey) throw new Error("Failed to derive EVM private key");
+	const privateKey = `0x${Buffer.from(derived.privateKey).toString("hex")}`;
+	const hash = keccak_256(secp256k1.getPublicKey(derived.privateKey, false).slice(1));
+	return {
+		privateKey,
+		address: checksumAddress(Buffer.from(hash.slice(-20)).toString("hex"))
+	};
+}
+function checksumAddress(addr) {
+	const hash = Buffer.from(keccak_256(enc.encode(addr))).toString("hex");
+	let out = "0x";
+	for (let i = 0; i < 40; i++) out += Number.parseInt(hash[i], 16) >= 8 ? addr[i].toUpperCase() : addr[i];
+	return out;
+}
+
+//#endregion
+//#region src/lib/resolve-wallet.ts
+/**
+* Resolve wallet keys following the priority cascade:
+* 1. Flags (--evm-key / --solana-key as raw key strings)
+* 2. X402_PROXY_WALLET_EVM_KEY / X402_PROXY_WALLET_SOLANA_KEY env vars
+* 3. X402_PROXY_WALLET_MNEMONIC env var (derives both)
+* 4. ~/.config/x402-proxy/wallet.json (mnemonic file)
+*/
+function resolveWallet(opts) {
+	if (opts?.evmKey || opts?.solanaKey) {
+		const result = { source: "flag" };
+		if (opts.evmKey) {
+			const hex = opts.evmKey.startsWith("0x") ? opts.evmKey : `0x${opts.evmKey}`;
+			result.evmKey = hex;
+			result.evmAddress = privateKeyToAccount(hex).address;
+		}
+		if (opts.solanaKey) result.solanaKey = parsesolanaKey(opts.solanaKey);
+		return result;
+	}
+	const envEvm = process.env.X402_PROXY_WALLET_EVM_KEY;
+	const envSol = process.env.X402_PROXY_WALLET_SOLANA_KEY;
+	if (envEvm || envSol) {
+		const result = { source: "env" };
+		if (envEvm) {
+			const hex = envEvm.startsWith("0x") ? envEvm : `0x${envEvm}`;
+			result.evmKey = hex;
+			result.evmAddress = privateKeyToAccount(hex).address;
+		}
+		if (envSol) result.solanaKey = parsesolanaKey(envSol);
+		return result;
+	}
+	const envMnemonic = process.env.X402_PROXY_WALLET_MNEMONIC;
+	if (envMnemonic) return resolveFromMnemonic(envMnemonic, "mnemonic-env");
+	const walletFile = loadWalletFile();
+	if (walletFile) return resolveFromMnemonic(walletFile.mnemonic, "wallet-file");
+	return { source: "none" };
+}
+function resolveFromMnemonic(mnemonic, source) {
+	const evm = deriveEvmKeypair(mnemonic);
+	const sol = deriveSolanaKeypair(mnemonic);
+	const solanaKey = new Uint8Array(64);
+	solanaKey.set(sol.secretKey, 0);
+	solanaKey.set(sol.publicKey, 32);
+	return {
+		evmKey: evm.privateKey,
+		evmAddress: evm.address,
+		solanaKey,
+		solanaAddress: sol.address,
+		source
+	};
+}
+function parsesolanaKey(input) {
+	const trimmed = input.trim();
+	if (trimmed.startsWith("[")) {
+		const arr = JSON.parse(trimmed);
+		return new Uint8Array(arr);
+	}
+	return base58.decode(trimmed);
+}
+/**
+* Build a configured x402Client from resolved wallet keys.
+*/
+async function buildX402Client(wallet) {
+	const client = new x402Client();
+	if (wallet.evmKey) {
+		const hex = wallet.evmKey;
+		const signer = toClientEvmSigner(privateKeyToAccount(hex), createPublicClient({
+			chain: base,
+			transport: http()
+		}));
+		client.register("eip155:8453", new ExactEvmScheme(signer));
+	}
+	if (wallet.solanaKey) {
+		const { createKeyPairSignerFromBytes } = await import("@solana/kit");
+		const signer = await createKeyPairSignerFromBytes(wallet.solanaKey);
+		client.register("solana:mainnet", new ExactSvmScheme(signer));
+		client.register("solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", new ExactSvmScheme(signer));
+	}
+	return client;
+}
+
+//#endregion
+//#region src/commands/status.ts
+function displayStatus() {
+	const wallet = resolveWallet();
+	const config = loadConfig();
+	console.log();
+	info("x402-proxy status");
+	console.log();
+	dim(`  Config directory: ${getConfigDir()}`);
+	if (config) {
+		if (config.spendLimit) dim(`  Spend limit:      ${config.spendLimit} USDC`);
+		if (config.defaultNetwork) dim(`  Default network:  ${config.defaultNetwork}`);
+	}
+	console.log();
+	if (wallet.source === "none") {
+		console.log(pc.yellow("  No wallet configured."));
+		console.log(pc.dim(`  Run ${pc.cyan("x402-proxy setup")} to create one.`));
+	} else {
+		dim(`  Wallet source: ${wallet.source}`);
+		if (wallet.evmAddress) console.log(`  EVM:    ${pc.green(wallet.evmAddress)}`);
+		if (wallet.solanaAddress) console.log(`  Solana: ${pc.green(wallet.solanaAddress)}`);
+	}
+	console.log();
+	const spend = calcSpend(readHistory(getHistoryPath()));
+	if (spend.count > 0) {
+		dim(`  Transactions: ${spend.count}`);
+		dim(`  Today:        ${spend.today.toFixed(4)} USDC`);
+		dim(`  Total:        ${spend.total.toFixed(4)} USDC`);
+	} else dim("  No payment history yet.");
+	console.log();
+}
+const statusCommand = buildCommand({
+	docs: { brief: "Show configuration and wallet status" },
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: []
+		}
+	},
+	func() {
+		displayStatus();
+	}
+});
+
+//#endregion
+export { readHistory as C, formatTxLine as S, isConfigured as _, deriveEvmKeypair as a, appendHistory as b, dim as c, isTTY as d, warn as f, getWalletPath as g, getHistoryPath as h, resolveWallet as i, error as l, getConfigDir as m, statusCommand as n, deriveSolanaKeypair as o, ensureConfigDir as p, buildX402Client as r, generateMnemonic$1 as s, displayStatus as t, info as u, saveConfig as v, calcSpend as x, saveWalletFile as y };

package/package.json

@@ -1,18 +1,38 @@
 {
   "name": "x402-proxy",
-  "version": "0.1.2",
-  "description": "Generic x402 payment proxy library for Solana USDC",
+  "version": "0.2.1",
+  "description": "curl for x402 paid APIs. Auto-pays any endpoint on Base and Solana.",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "x402-proxy": "./dist/bin/cli.js"
+  },
   "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@noble/curves": "^2.0.1",
+    "@noble/hashes": "^2.0.1",
+    "@scure/base": "^2.0.0",
+    "@scure/bip32": "^2.0.1",
+    "@scure/bip39": "^2.0.1",
+    "@stricli/core": "^1.2.6",
     "@x402/evm": "^2.6.0",
     "@x402/fetch": "^2.6.0",
-    "@x402/svm": "^2.6.0"
+    "@x402/mcp": "^2.6.0",
+    "@x402/svm": "^2.6.0",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.8.2"
   },
   "peerDependencies": {
     "@solana/kit": "^6.0.0",
@@ -32,6 +52,19 @@
     "README.md",
     "LICENSE"
   ],
+  "keywords": [
+    "x402",
+    "http-402",
+    "mcp",
+    "mcp-proxy",
+    "ai-agent",
+    "agentic-commerce",
+    "base",
+    "solana",
+    "usdc",
+    "coinbase",
+    "cli"
+  ],
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22.0.0"