x402-proxy 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,153 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-03-16
+
+### Changed
+- MCP proxy graduated from alpha to stable - removed alpha warning and label
+- MCP proxy uses low-level `Server` class instead of `McpServer` to proxy raw JSON schemas verbatim without Zod conversion
+- MCP proxy now forwards blob resource contents (previously only text was proxied)
+- MCP content type widened to pass through all MCP content types (image, audio, resource_link) not just text
+
+### Added
+- MCP proxy forwards `notifications/tools/list_changed` and `notifications/resources/list_changed` from remote servers so local clients stay in sync with dynamic tool/resource updates
+
+## [0.4.2] - 2026-03-16
+
+### Fixed
+- Twitter endpoint URLs updated from `/user/` to `/users/` to match spec change
+
+### Added
+- CHANGELOG.md included in npm package metadata
+- `skills/` directory with SKILL.md and library reference included in npm package
+
+## [0.4.1] - 2026-03-13
+
+### Changed
+- Extracted `createNetworkFilter`, `createNetworkPreference`, `networkToCaipPrefix` as exported functions for testability
+- Publish workflow auto-creates GitHub releases from CHANGELOG.md (no more manual `gh release create`)
+- Release docs updated in CLAUDE.md with `act` dry-run instructions for CI workflows
+
+### Added
+- Tests for network filter, network preference selector, Solana address derivation, and wallet resolution (14 new tests)
+
+## [0.4.0] - 2026-03-13
+
+### Added
+- `--network` flag for `fetch` and `mcp` commands - hard filter that requires a specific network (base, solana, or CAIP-2 ID), fails with clear error if unavailable
+- Human-readable network names in payment output ("Base", "Solana" instead of "eip155:8453")
+- `displayNetwork()` exported from library for mapping CAIP-2 IDs to display names
+
+### Fixed
+- Wildcard scheme registration (`eip155:*`, `solana:*`) via SDK helpers - payment signing now works for any EVM chain a server requests, not just Base
+- Solana address derivation for `--solana-key` flag and `X402_PROXY_WALLET_SOLANA_KEY` env var - balance detection, wallet display, and history recording were broken without it
+- MCP command now auto-detects preferred network based on USDC balance (same fix previously applied to `fetch`)
+- MCP payment history records now include `amount`, `to`, and correct `network` (removed fragile type cast)
+- Removed debug prefix stripping from payment amounts in handler
+- USDC balance display now shows 4 decimal places (was 2)
+
+## [0.3.2] - 2026-03-13
+
+### Added
+- Auto-setup: running `npx x402-proxy <url>` without a wallet launches the setup wizard, then continues with the request
+- 402 error handling parses the endpoint's `PAYMENT-REQUIRED` header to show actual accepted networks and costs
+- CI pipeline (GitHub Actions: check, build, test on push/PR)
+- Automated npm publishing with OIDC provenance on tag push
+- Tests for wallet derivation and transaction history (25 tests)
+- Funding hint in `wallet` when USDC balance is zero
+
+### Changed
+- Version injected at build time from package.json (no more stale hardcoded strings)
+- `wallet fund` command removed (addresses and hint shown in `wallet` directly)
+- All command references use `$ npx x402-proxy` format
+
+## [0.3.1] - 2026-03-12
+
+### Added
+- `wallet export-key mnemonic` - export BIP-39 mnemonic to stdout (pipe-safe, with confirmation prompt)
+
+## [0.3.0] - 2026-03-12
+
+### Added
+- Live wallet balances in `status` and `wallet` commands (USDC + ETH/SOL via RPC)
+- Recent transactions shown in `status` (last 5) and `wallet` (last 10)
+- Network preference (`defaultNetwork` config) - prefers configured chain when endpoint accepts multiple
+- Spend limits (`spendLimitDaily`, `spendLimitPerTx` config) enforced via x402Client policy
+- `--verbose` flag on `wallet` command to show transaction IDs
+- Confirmation prompt on `wallet export-key` when stdout is a terminal
+- Help text with usage examples for `fetch --help` and `mcp --help`
+- Full command reference, "try:" suggestion, and repo link in no-args output
+- Network indicator on transaction lines (base/sol)
+- Setup outro with "try your first request" using real endpoint
+
+### Changed
+- "EVM" label replaced with "Base" throughout (wallet, status, setup)
+- Config directory displayed as `~/.config/...` instead of absolute path
+- Error messages prefixed with `✗`, success with `✓` for accessibility
+- No-args output redesigned: identity header, wallet summary, commands, try suggestion
+- Example URLs use path-based format (`/user/cascade_fyi`) to avoid zsh glob issues
+- `@solana/kit`, `ethers`, `viem` moved from peerDependencies to dependencies (fixes npx ERESOLVE warnings)
+- Wallet subcommand hints shown at bottom of `wallet` output
+
+### Fixed
+- RPC balance failures show "(network error)" instead of silent omission
+
+## [0.2.1] - 2026-03-12
+
+### Changed
+- Package description and keywords aligned with "curl for x402 paid APIs" positioning
+- README rewritten: real endpoint in Quick Start, MCP Proxy elevated above HTTP Requests
+- Stricli commands use explicit generic types (fixes TS 5.9 type inference)
+- `displayStatus()` extracted as callable function from status command
+- `PaymentRequirements.amount` used instead of removed `maxAmountRequired`
+
+### Fixed
+- All `tsc --noEmit` type errors resolved (previously passing only at build time)
+- Biome schema version bumped to match CLI 2.4.6
+
+## [0.2.0] - 2026-03-12
+
+### Added
+- CLI binary accessible via `npx x402-proxy`
+- `fetch` command (default) - curl-like HTTP client with automatic x402 payment
+- `mcp` command - MCP stdio proxy with auto-payment for AI agents
+- `setup` command - interactive onboarding wizard with @clack/prompts
+- `status` command - config, wallet, and spend summary
+- `wallet` subcommand with `info`, `history`, `fund`, `export-key`
+- BIP-39 mnemonic wallet derivation (Solana SLIP-10 + EVM BIP-32 from single seed)
+- XDG-compliant config storage (`~/.config/x402-proxy/`)
+- Wallet resolution cascade: flags > env vars > mnemonic env > wallet.json
+- JSONL payment history with auto-truncation
+- Env var overrides with `X402_PROXY_WALLET_*` prefix
+
+### Changed
+- Package now ships both CLI binary and library
+- Dual tsdown build entries (bin/cli with shebang + index with dts)
+
+## [0.1.0] - 2026-03-10
+
+### Added
+- Initial release (library only)
+- `createX402ProxyHandler` - wraps fetch with automatic x402 payment
+- `extractTxSignature` - extracts TX signature from payment response headers
+- `loadSvmWallet` / `loadEvmWallet` - wallet loading utilities
+- `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.5.0...HEAD
+[0.5.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.2...v0.5.0
+[0.4.2]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.3.2...v0.4.0
+[0.3.2]: https://github.com/cascade-protocol/x402-proxy/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/cascade-protocol/x402-proxy/releases/tag/v0.1.0

package/README.md

@@ -5,7 +5,7 @@
 ## Quick Start
 
 ```bash
-npx x402-proxy https://twitter.surf.cascade.fyi/user/cascade_fyi
+npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi
 ```
 
 That's it. The endpoint returns 402, x402-proxy pays and streams the response.
@@ -38,7 +38,7 @@ Works like curl. Response body streams to stdout, payment info goes to stderr.
 
 ```bash
 # GET request
-$ npx x402-proxy https://twitter.surf.cascade.fyi/user/cascade_fyi
+$ npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi
 
 # POST with body and headers
 $ npx x402-proxy --method POST \

package/dist/bin/cli.js

@@ -330,7 +330,7 @@ Examples:
 //#region src/commands/mcp.ts
 const mcpCommand = buildCommand({
 	docs: {
-		brief: "Start MCP stdio proxy with x402 payment (alpha)",
+		brief: "Start MCP stdio proxy with x402 payment",
 		fullDescription: `Start an MCP stdio proxy with automatic x402 payment for AI agents.
 
 Add to your MCP client config (Claude, Cursor, etc.):
@@ -376,7 +376,6 @@ Add to your MCP client config (Claude, Cursor, etc.):
 			error("No wallet configured.\nRun:\n  $ npx x402-proxy setup\n\nOr set X402_PROXY_WALLET_MNEMONIC");
 			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}`);
@@ -399,13 +398,14 @@ Add to your MCP client config (Claude, Cursor, etc.):
 		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 { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
 		const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
 		const { x402MCPClient } = await import("@x402/mcp");
-		const x402Mcp = new x402MCPClient(new Client({
+		const remoteClient = new Client({
 			name: "x402-proxy",
-			version: "0.4.1"
-		}), x402PaymentClient, {
+			version: "0.5.0"
+		});
+		const x402Mcp = new x402MCPClient(remoteClient, x402PaymentClient, {
 			autoPayment: true,
 			onPaymentRequested: (ctx) => {
 				const accept = ctx.paymentRequired.accepts?.[0];
@@ -447,31 +447,58 @@ Add to your MCP client config (Claude, Cursor, etc.):
 			error(`Failed to connect to ${remoteUrl}: ${err instanceof Error ? err.message : String(err)}`);
 			process.exit(1);
 		}
-		const { tools } = await x402Mcp.listTools();
+		let { tools } = await x402Mcp.listTools();
 		dim(`  ${tools.length} tools available`);
-		const localServer = new McpServer({
+		let remoteResources = [];
+		try {
+			remoteResources = (await x402Mcp.listResources()).resources;
+			if (remoteResources.length > 0) dim(`  ${remoteResources.length} resources available`);
+		} catch {
+			dim("  Resources not available from remote");
+		}
+		const localServer = new Server({
 			name: "x402-proxy",
-			version: "0.4.1"
-		});
-		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);
+			version: "0.5.0"
+		}, { capabilities: {
+			tools: tools.length > 0 ? {} : void 0,
+			resources: remoteResources.length > 0 ? {} : void 0
+		} });
+		const { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ToolListChangedNotificationSchema, ResourceListChangedNotificationSchema } = await import("@modelcontextprotocol/sdk/types.js");
+		localServer.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: tools.map((t) => ({
+			name: t.name,
+			description: t.description,
+			inputSchema: t.inputSchema,
+			annotations: t.annotations
+		})) }));
+		localServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+			const { name, arguments: args } = request.params;
+			const result = await x402Mcp.callTool(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 {}
+		if (remoteResources.length > 0) {
+			localServer.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: remoteResources.map((r) => ({
+				name: r.name,
+				uri: r.uri,
+				description: r.description,
+				mimeType: r.mimeType
+			})) }));
+			localServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+				return { contents: (await x402Mcp.readResource({ uri: request.params.uri })).contents.map((c) => ({ ...c })) };
+			});
+		}
+		remoteClient.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+			tools = (await x402Mcp.listTools()).tools;
+			dim(`  Tools updated: ${tools.length} available`);
+			await localServer.notification({ method: "notifications/tools/list_changed" });
+		});
+		if (remoteResources.length > 0) remoteClient.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
+			remoteResources = (await x402Mcp.listResources()).resources;
+			dim(`  Resources updated: ${remoteResources.length} available`);
+			await localServer.notification({ method: "notifications/resources/list_changed" });
+		});
 		const stdioTransport = new StdioServerTransport();
 		await localServer.connect(stdioTransport);
 		dim("  MCP proxy running (stdio)");
@@ -608,7 +635,7 @@ const routes = buildRouteMap({
 });
 const app = buildApplication(routes, {
 	name: "x402-proxy",
-	versionInfo: { currentVersion: "0.4.1" },
+	versionInfo: { currentVersion: "0.5.0" },
 	scanner: { caseStyle: "allow-kebab-for-camel" }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-proxy",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "curl for x402 paid APIs. Auto-pays any endpoint on Base and Solana.",
   "type": "module",
   "sideEffects": false,
@@ -47,6 +47,8 @@
   "files": [
     "dist/**",
     "README.md",
+    "CHANGELOG.md",
+    "skills/**",
     "LICENSE"
   ],
   "keywords": [

package/skills/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: x402-proxy
+description: Use x402-proxy CLI for consuming and debugging x402 paid APIs. Use this skill when testing x402 endpoints, configuring MCP payment proxies for AI agents, managing x402 wallets, or scripting paid HTTP requests. Triggers on x402-proxy, npx x402-proxy, x402 endpoint testing, paid API debugging, MCP payment proxy, x402 wallet management, or any mention of auto-paying HTTP 402 responses.
+---
+
+# x402-proxy
+
+`curl` for x402 paid APIs. Auto-pays HTTP 402 responses with USDC on Base and Solana.
+
+## Quick start
+
+```bash
+npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi
+```
+
+First run auto-creates a wallet. No setup needed.
+
+## HTTP requests
+
+```bash
+# GET - body to stdout, payment info to stderr
+npx x402-proxy https://api.example.com/resource
+
+# POST with body and headers
+npx x402-proxy --method POST \
+  --header "Content-Type: application/json" \
+  --body '{"query":"example"}' \
+  https://api.example.com/search
+
+# Force a specific chain
+npx x402-proxy --network solana https://api.example.com/data
+
+# Pipe-safe - only response body on stdout
+npx x402-proxy https://api.example.com/data | jq '.results'
+
+# Save response to file
+npx x402-proxy https://api.example.com/data > response.json
+```
+
+## Commands
+
+```
+x402-proxy <url>                        # paid HTTP request (default)
+x402-proxy mcp <url>                    # MCP stdio proxy for AI agents
+x402-proxy setup                        # wallet onboarding wizard
+x402-proxy setup --force                # re-run setup (overwrite existing wallet)
+x402-proxy status                       # config + wallet + daily spend summary
+x402-proxy wallet                       # show addresses and USDC balances
+x402-proxy wallet history               # payment log
+x402-proxy wallet history --limit 5     # last 5 payments
+x402-proxy wallet history --json        # machine-readable output
+x402-proxy wallet export-key evm        # bare EVM private key to stdout
+x402-proxy wallet export-key solana     # bare Solana private key to stdout
+x402-proxy wallet export-key mnemonic   # bare mnemonic to stdout
+```
+
+## Fetch flags
+
+```
+--method, -X <METHOD>     HTTP method (default: GET)
+--header, -H <KEY:VALUE>  Add request header (repeatable)
+--body, -d <DATA>         Request body (string or @file)
+--network <base|solana>   Force payment on this chain
+```
+
+## MCP proxy for AI agents
+
+Drop into Claude, Cursor, or any MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "paid-service": {
+      "command": "npx",
+      "args": ["x402-proxy", "mcp", "https://mcp.example.com/sse"],
+      "env": {
+        "X402_PROXY_WALLET_MNEMONIC": "your 24 words here"
+      }
+    }
+  }
+}
+```
+
+The proxy intercepts 402 responses, pays automatically, forwards the result. Supports StreamableHTTP and SSE.
+
+## Wallet & env vars
+
+One BIP-39 mnemonic derives both Solana and EVM keypairs. Auto-detects which chain based on USDC balance.
+
+```
+X402_PROXY_WALLET_MNEMONIC       # BIP-39 mnemonic (derives both chains)
+X402_PROXY_WALLET_EVM_KEY        # EVM private key (hex, 0x optional)
+X402_PROXY_WALLET_SOLANA_KEY     # Solana private key (base58 or JSON array)
+```
+
+Resolution: flags > env vars > mnemonic env > `~/.config/x402-proxy/wallet.json`
+
+Pipe-safe export for scripting:
+
+```bash
+MY_KEY=$(npx x402-proxy wallet export-key evm)
+MY_MNEMONIC=$(npx x402-proxy wallet export-key mnemonic)
+```
+
+## Config
+
+Lives at `~/.config/x402-proxy/` (or `$XDG_CONFIG_HOME/x402-proxy/`):
+
+```yaml
+# config.yaml
+defaultNetwork: base    # or "solana"
+spendLimitDaily: 10     # USDC daily cap
+spendLimitPerTx: 1      # USDC per-request cap
+```
+
+Also supports JSONC and JSON config files. Wallet stored in `wallet.json` (mode 0600), payments logged to `history.jsonl`.
+
+## Testing & debugging x402 services
+
+```bash
+# Smoke test an endpoint
+npx x402-proxy https://your-service.com/paid-route
+
+# Test both chains
+npx x402-proxy --network base https://your-service.com/route
+npx x402-proxy --network solana https://your-service.com/route
+
+# Batch test
+for route in /users/test /tweets/search /v1/crawl; do
+  echo "--- $route ---"
+  npx x402-proxy "https://your-service.com$route" 2>/dev/null | head -c 200
+  echo
+done
+
+# Check what you spent
+npx x402-proxy wallet history --limit 5
+npx x402-proxy status
+```
+
+stdout = response body, stderr = payment info. Pipes, redirects, and `jq` all work cleanly.
+
+## Library API
+
+For programmatic use in Node.js apps, read `references/library.md`.

package/skills/references/library.md

@@ -0,0 +1,85 @@
+# x402-proxy Library API
+
+```bash
+npm install x402-proxy
+```
+
+## Exports
+
+```typescript
+// Core
+import { createX402ProxyHandler, extractTxSignature } from "x402-proxy";
+import { x402Client } from "x402-proxy";
+
+// Chain schemes
+import { ExactEvmScheme, toClientEvmSigner } from "x402-proxy";
+import { ExactSvmScheme } from "x402-proxy";
+
+// Wallet loaders
+import { loadEvmWallet, loadSvmWallet } from "x402-proxy";
+
+// History
+import { appendHistory, readHistory, calcSpend, explorerUrl, formatTxLine } from "x402-proxy";
+```
+
+## EVM (Base) setup
+
+```typescript
+import { createX402ProxyHandler, x402Client, ExactEvmScheme, toClientEvmSigner } from "x402-proxy";
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base } from "viem/chains";
+
+const account = privateKeyToAccount(process.env.EVM_KEY as `0x${string}`);
+const wallet = createWalletClient({ account, chain: base, transport: http() });
+
+const client = x402Client(fetch)
+  .register(new ExactEvmScheme(toClientEvmSigner(wallet)));
+
+const { x402Fetch, shiftPayment } = createX402ProxyHandler({ x402Client: client });
+
+const res = await x402Fetch("https://api.example.com/data");
+const body = await res.json();
+const payment = shiftPayment(); // { network, payTo, amount, asset }
+```
+
+## Solana setup
+
+```typescript
+import { createX402ProxyHandler, x402Client, ExactSvmScheme, loadSvmWallet } from "x402-proxy";
+
+const signer = loadSvmWallet(process.env.MNEMONIC!);
+const client = x402Client(fetch).register(new ExactSvmScheme(signer));
+const { x402Fetch } = createX402ProxyHandler({ x402Client: client });
+```
+
+## Payment history
+
+```typescript
+import { appendHistory, readHistory, calcSpend } from "x402-proxy";
+
+// Read and summarize
+const records = await readHistory("./history.jsonl");
+const { dailyUsd, totalUsd, txCount } = calcSpend(records);
+
+// Append a record
+await appendHistory("./history.jsonl", {
+  ts: Date.now(),
+  status: 200,
+  network: "eip155:8453",
+  payTo: "0x...",
+  amount: "0.001",
+  asset: "USDC",
+  txId: "0xabc...",
+  host: "api.example.com",
+});
+```
+
+## Types
+
+```typescript
+type PaymentInfo = { network: string; payTo: string; amount: string; asset: string };
+type X402ProxyOptions = { x402Client: ReturnType<typeof x402Client> };
+type X402ProxyHandler = { x402Fetch: typeof fetch; shiftPayment: () => PaymentInfo | undefined };
+type TxRecord = { ts: number; status: number; network: string; payTo: string; amount: string; asset: string; txId?: string; host: string };
+```