x402-proxy 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.4] - 2026-03-27
+
+### Fixed
+- All example URLs migrated from legacy individual service subdomains (`twitter.surf.cascade.fyi`, `web.surf.cascade.fyi`, `inference.surf.cascade.fyi`) to unified `surf.cascade.fyi/api/v1/` endpoints across CLI help text, README, SKILL.md, and OpenClaw plugin docs
+
 ## [0.9.3] - 2026-03-26
 
 ### Fixed
@@ -295,7 +300,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.9.3...HEAD
+[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.9.4...HEAD
+[0.9.4]: https://github.com/cascade-protocol/x402-proxy/compare/v0.9.3...v0.9.4
 [0.9.3]: https://github.com/cascade-protocol/x402-proxy/compare/v0.9.2...v0.9.3
 [0.9.2]: https://github.com/cascade-protocol/x402-proxy/compare/v0.9.1...v0.9.2
 [0.9.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.9.0...v0.9.1

package/README.md

@@ -5,7 +5,7 @@
 ## Quick Start
 
 ```bash
-npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi
+npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user
 ```
 
 That's it. The endpoint returns 402, x402-proxy pays and streams the response.
@@ -52,14 +52,14 @@ openclaw mcp set surf '{"command":"npx","args":["-y","x402-proxy","mcp","https:/
 Works like curl. Response body streams to stdout, payment info goes to stderr.
 
 ```bash
-# GET request
-$ npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi
+# POST request
+$ npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user
 
 # POST with body and headers (curl-style short flags: -X, -H, -d)
 $ npx x402-proxy -X POST \
   -H "Content-Type: application/json" \
   -d '{"url":"https://x402.org"}' \
-  https://web.surf.cascade.fyi/v1/crawl
+  https://surf.cascade.fyi/api/v1/web/crawl
 
 # Force a specific network
 $ npx x402-proxy --network base https://api.example.com/data
@@ -71,7 +71,7 @@ $ npx x402-proxy --verbose https://api.example.com/data
 $ npx x402-proxy --protocol mpp \
   -X POST -H "Content-Type: application/json" \
   -d '{"model":"minimax/minimax-m2.5","stream":true,"messages":[{"role":"user","content":"Hello"}]}' \
-  https://inference.surf.cascade.fyi/v1/chat/completions
+  https://surf.cascade.fyi/api/v1/inference/completions
 
 # Pipe-safe
 $ npx x402-proxy https://api.example.com/data | jq '.results'

package/dist/bin/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { a as getHistoryPath, c as loadConfig, i as getConfigDirShort, l as loadWalletFile, s as isConfigured, u as saveConfig } from "../derive-EDXzwKW2.js";
 import { _ as error, b as warn, c as resolveWallet, d as displayNetwork, f as formatAmount, g as dim, h as readHistory, l as appendHistory, m as formatUsdcValue, n as fetchAllBalances, o as walletInfoCommand, p as formatTxLine, s as buildX402Client, u as calcSpend, v as info, y as isTTY } from "../wallet-CqUc-ZFn.js";
-import { n as setupCommand, t as runSetup } from "../setup-QtTFsCFs.js";
+import { n as setupCommand, t as runSetup } from "../setup-Dp5fS7ob.js";
 import { n as statusCommand } from "../status-BZTToWE_.js";
 import { dirname, join, normalize, resolve } from "node:path";
 import { buildApplication, buildCommand, buildRouteMap, run } from "@stricli/core";
@@ -310,8 +310,8 @@ const fetchCommand = buildCommand({
 		fullDescription: `Make a paid HTTP request. Payment is automatic when the server returns 402.
 
 Examples:
-  $ x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi
-  $ x402-proxy -X POST -d '{"url":"https://x402.org"}' https://web.surf.cascade.fyi/v1/crawl
+  $ x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user
+  $ x402-proxy -X POST -d '{"url":"https://x402.org"}' https://surf.cascade.fyi/api/v1/web/crawl
   $ x402-proxy https://api.example.com/data | jq '.results'`
 	},
 	parameters: {
@@ -408,7 +408,7 @@ Examples:
 				console.log(`    ${pc.cyan("$ npx x402-proxy wallet")}             Addresses and balances`);
 				console.log(`    ${pc.cyan("$ npx x402-proxy wallet history")}     Full payment history`);
 				console.log();
-				console.log(pc.dim("  try: ") + pc.cyan("$ npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi"));
+				console.log(pc.dim("  try: ") + pc.cyan(`$ npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user`));
 				console.log();
 				console.log(pc.dim("  https://github.com/cascade-protocol/x402-proxy"));
 				console.log();
@@ -450,7 +450,7 @@ Examples:
 				process.exit(1);
 			}
 			dim("  No wallet found. Let's set one up first.\n");
-			const { runSetup } = await import("../setup-lCsiivm2.js");
+			const { runSetup } = await import("../setup-B6xRV8Ue.js");
 			await runSetup();
 			console.log();
 			wallet = resolveWallet();
@@ -806,7 +806,7 @@ Wallet is auto-generated on first run. No env vars needed.`
 		});
 		if (wallet.source === "none") {
 			dim("No wallet found. Auto-generating...");
-			const { runSetup } = await import("../setup-lCsiivm2.js");
+			const { runSetup } = await import("../setup-B6xRV8Ue.js");
 			await runSetup({ nonInteractive: true });
 			const fresh = resolveWallet({
 				evmKey: flags.evmKey,
@@ -870,7 +870,7 @@ Wallet is auto-generated on first run. No env vars needed.`
 			}
 			const remoteClient = new Client({
 				name: "x402-proxy",
-				version: "0.9.3"
+				version: "0.9.4"
 			});
 			const x402Mcp = new x402MCPClient(remoteClient, x402PaymentClient, {
 				autoPayment: true,
@@ -908,7 +908,7 @@ Wallet is auto-generated on first run. No env vars needed.`
 			}
 			const localServer = new Server({
 				name: "x402-proxy",
-				version: "0.9.3"
+				version: "0.9.4"
 			}, { capabilities: {
 				tools: tools.length > 0 ? {} : void 0,
 				resources: remoteResources.length > 0 ? {} : void 0
@@ -1003,7 +1003,7 @@ Wallet is auto-generated on first run. No env vars needed.`
 			}));
 			const remoteClient = new Client({
 				name: "x402-proxy",
-				version: "0.9.3"
+				version: "0.9.4"
 			});
 			await connectTransport(remoteClient);
 			const mppClient = McpClient.wrap(remoteClient, { methods: wrappedMethods });
@@ -1018,7 +1018,7 @@ Wallet is auto-generated on first run. No env vars needed.`
 			}
 			const localServer = new Server({
 				name: "x402-proxy",
-				version: "0.9.3"
+				version: "0.9.4"
 			}, { capabilities: {
 				tools: tools.length > 0 ? {} : void 0,
 				resources: remoteResources.length > 0 ? {} : void 0
@@ -1272,7 +1272,7 @@ const mcpAddCommand = buildCommand({
 			}
 		}
 		prompts.log.step("Try your first request:");
-		prompts.log.message(`  ${pc.cyan("$ npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi")}`);
+		prompts.log.message(`  ${pc.cyan(`$ npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user`)}`);
 		prompts.log.message(`  ${pc.dim("Run")} ${pc.cyan("npx x402-proxy")} ${pc.dim("to see your wallet and balance")}`);
 		prompts.outro(pc.green(`MCP server ${pc.bold(serverName)} is ready to use!`));
 	}
@@ -1415,7 +1415,7 @@ const app = buildApplication(buildRouteMap({
 	docs: { brief: "curl for x402 paid APIs" }
 }), {
 	name: "x402-proxy",
-	versionInfo: { currentVersion: "0.9.3" },
+	versionInfo: { currentVersion: "0.9.4" },
 	scanner: { caseStyle: "allow-kebab-for-camel" }
 });
 //#endregion

package/dist/openclaw/plugin.js

@@ -809,7 +809,7 @@ function createWalletCommand(ctx) {
 			try {
 				const snap = await getWalletSnapshot(ctx.rpcUrl, walletAddress, ctx.historyPath);
 				const solscanUrl = `https://solscan.io/account/${walletAddress}`;
-				const lines = [`x402-proxy v0.9.3`];
+				const lines = [`x402-proxy v0.9.4`];
 				const defaultModel = ctx.allModels[0];
 				if (defaultModel) lines.push("", `**Model** - ${defaultModel.name} (${defaultModel.provider})`);
 				lines.push("", `**[Wallet](${solscanUrl})**`, `\`${walletAddress}\``);

package/dist/setup-B6xRV8Ue.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { t as runSetup } from "./setup-Dp5fS7ob.js";
+export { runSetup };

package/dist/{setup-QtTFsCFs.js → setup-Dp5fS7ob.js}

@@ -143,7 +143,7 @@ async function runSetup(opts) {
 	prompts.log.message(`  Solana (USDC): Send USDC to ${pc.cyan(sol.address)}`);
 	prompts.log.message(`  Base (USDC):   Send USDC to ${pc.cyan(evm.address)}`);
 	prompts.log.step("Try your first request:");
-	prompts.log.message(`  ${pc.cyan("$ npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi")}`);
+	prompts.log.message(`  ${pc.cyan(`$ npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user`)}`);
 	prompts.outro(pc.green("Setup complete!"));
 }
 const setupCommand = buildCommand({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-proxy",
-  "version": "0.9.3",
+  "version": "0.9.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,

package/skills/SKILL.md

@@ -10,7 +10,7 @@ description: Use x402-proxy CLI for consuming and debugging x402 and MPP paid AP
 ## Quick start
 
 ```bash
-npx x402-proxy https://twitter.surf.cascade.fyi/users/cascade_fyi
+npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user
 ```
 
 First run auto-creates a wallet. No setup needed.
@@ -165,14 +165,16 @@ stdout = response body, stderr = payment info. Pipes, redirects, and `jq` all wo
 
 ## OpenClaw Plugin
 
-x402-proxy ships as an [OpenClaw](https://openclaw.dev) plugin. Install it to give your OpenClaw gateway automatic x402 payment capabilities:
+x402-proxy ships as an [OpenClaw](https://openclaw.dev) plugin for automatic x402 payments, wallet management, and pay-per-use inference proxying. For full installation, provider/model configuration, and troubleshooting, read `references/openclaw-plugin.md`.
 
-- `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
+Quick install:
 
-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.
+```bash
+openclaw plugins install x402-proxy
+npx x402-proxy setup   # creates wallet if needed
+```
+
+Registers: `x_balance` tool, `x_payment` tool, `/x_wallet` command, `/x402/*` HTTP route for inference proxying.
 
 ## Library API
 

package/skills/references/openclaw-plugin.md

@@ -0,0 +1,135 @@
+# OpenClaw Plugin Setup
+
+x402-proxy ships as an [OpenClaw](https://openclaw.dev) plugin. Gives your gateway automatic x402 payment, wallet management, and pay-per-use inference proxying via Solana USDC.
+
+## What it registers
+
+- **`x_balance` tool** - check wallet SOL/USDC balances, daily spend, available funds
+- **`x_payment` tool** - call any x402-enabled endpoint with automatic payment (params: `url`, `method`, `params`, `headers`)
+- **`/x_wallet` command** - wallet status dashboard, `send <amount|all> <address>`, `history [page]`
+- **HTTP route `/x402/*`** - proxies requests to upstream inference endpoints with payment, tracks token usage and cost
+
+## Step 1: Install the plugin
+
+```bash
+openclaw plugins install x402-proxy
+```
+
+This downloads from npm, validates `openclaw.plugin.json`, and installs to `~/.openclaw/extensions/x402-proxy/`.
+
+## Step 2: Configure wallet
+
+The plugin resolves a Solana wallet using the same cascade as the CLI:
+
+1. `keypairPath` in plugin config (solana-keygen JSON file)
+2. `X402_PROXY_WALLET_SOLANA_KEY` env var (base58 or JSON array)
+3. `X402_PROXY_WALLET_MNEMONIC` env var (BIP-39, derives both Solana and EVM)
+4. `~/.config/x402-proxy/wallet.json` (auto-created by `npx x402-proxy setup`)
+
+Easiest path - run setup first, then the plugin picks up the wallet automatically:
+
+```bash
+npx x402-proxy setup
+```
+
+Or set an explicit keypair in plugin config (step 3).
+
+## Step 3: Configure providers and models
+
+Add the plugin config to your `openclaw.json` (or via `openclaw config edit`):
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "x402-proxy": {
+        "config": {
+          "providers": {
+            "surf-inference": {
+              "baseUrl": "/x402/v1",
+              "upstreamUrl": "https://surf.cascade.fyi/api/v1/inference",
+              "models": [
+                { "id": "anthropic/claude-opus-4.6", "name": "Claude Opus 4.6", "maxTokens": 200000, "reasoning": true, "input": ["text", "image"], "cost": { "input": 0.015, "output": 0.075, "cacheRead": 0.0015, "cacheWrite": 0.01875 }, "contextWindow": 200000 },
+                { "id": "anthropic/claude-sonnet-4.6", "name": "Claude Sonnet 4.6", "maxTokens": 200000, "reasoning": true, "input": ["text", "image"], "cost": { "input": 0.003, "output": 0.015, "cacheRead": 0.0003, "cacheWrite": 0.00375 }, "contextWindow": 200000 },
+                { "id": "anthropic/claude-opus-4.5", "name": "Claude Opus 4.5", "maxTokens": 200000, "reasoning": true, "input": ["text", "image"], "cost": { "input": 0.015, "output": 0.075, "cacheRead": 0.0015, "cacheWrite": 0.01875 }, "contextWindow": 200000 },
+                { "id": "anthropic/claude-sonnet-4.5", "name": "Claude Sonnet 4.5", "maxTokens": 200000, "reasoning": true, "input": ["text", "image"], "cost": { "input": 0.003, "output": 0.015, "cacheRead": 0.0003, "cacheWrite": 0.00375 }, "contextWindow": 200000 },
+                { "id": "x-ai/grok-4.20-beta", "name": "Grok 4.20 Beta", "maxTokens": 131072, "reasoning": true, "input": ["text"], "cost": { "input": 0.003, "output": 0.015, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
+                { "id": "x-ai/grok-4.20-multi-agent-beta", "name": "Grok 4.20 Multi-Agent", "maxTokens": 131072, "reasoning": true, "input": ["text"], "cost": { "input": 0.003, "output": 0.015, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
+                { "id": "x-ai/grok-4.1-fast", "name": "Grok 4.1 Fast", "maxTokens": 131072, "reasoning": false, "input": ["text"], "cost": { "input": 0.001, "output": 0.005, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
+                { "id": "x-ai/grok-4.20-beta:online", "name": "Grok 4.20 Beta (Online)", "maxTokens": 131072, "reasoning": true, "input": ["text"], "cost": { "input": 0.005, "output": 0.025, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
+                { "id": "x-ai/grok-4.20-multi-agent-beta:online", "name": "Grok 4.20 Multi-Agent (Online)", "maxTokens": 131072, "reasoning": true, "input": ["text"], "cost": { "input": 0.005, "output": 0.025, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
+                { "id": "x-ai/grok-4.1-fast:online", "name": "Grok 4.1 Fast (Online)", "maxTokens": 131072, "reasoning": false, "input": ["text"], "cost": { "input": 0.003, "output": 0.015, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
+                { "id": "minimax/minimax-m2.7", "name": "MiniMax M2.7", "maxTokens": 1000000, "reasoning": false, "input": ["text"], "cost": { "input": 0.001, "output": 0.005, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 1000000 },
+                { "id": "minimax/minimax-m2.5", "name": "MiniMax M2.5", "maxTokens": 1000000, "reasoning": false, "input": ["text"], "cost": { "input": 0.001, "output": 0.005, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 1000000 },
+                { "id": "moonshotai/kimi-k2.5", "name": "Kimi K2.5", "maxTokens": 131072, "reasoning": true, "input": ["text"], "cost": { "input": 0.002, "output": 0.008, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
+                { "id": "z-ai/glm-5", "name": "GLM-5", "maxTokens": 128000, "reasoning": false, "input": ["text"], "cost": { "input": 0.001, "output": 0.005, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 128000 },
+                { "id": "qwen/qwen-2.5-7b-instruct", "name": "Qwen 2.5 7B Instruct", "maxTokens": 32768, "reasoning": false, "input": ["text"], "cost": { "input": 0.0003, "output": 0.001, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 32768 }
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Config fields
+
+| Field | Description |
+|-------|-------------|
+| `providers.<name>.baseUrl` | Route path registered in OpenClaw (e.g., `/x402/v1`) |
+| `providers.<name>.upstreamUrl` | Actual upstream endpoint (e.g., `https://surf.cascade.fyi/api/v1/inference`) |
+| `providers.<name>.models[]` | Model catalog array |
+| `keypairPath` | Optional path to solana-keygen JSON file (overrides wallet resolution) |
+| `rpcUrl` | Solana RPC URL (defaults to mainnet public endpoints with failover) |
+| `dashboardUrl` | URL linked from `/x_wallet` dashboard |
+
+### Model entry fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Model identifier (e.g., `anthropic/claude-opus-4.6`) |
+| `name` | string | Display name |
+| `maxTokens` | number | Max context length |
+| `reasoning` | boolean | Supports extended thinking |
+| `input` | string[] | Input modalities: `["text"]` or `["text", "image"]` |
+| `cost.input` | number | USDC per 1K input tokens |
+| `cost.output` | number | USDC per 1K output tokens |
+| `cost.cacheRead` | number | USDC per 1K cached read tokens |
+| `cost.cacheWrite` | number | USDC per 1K cache write tokens |
+| `contextWindow` | number | Full context window size |
+
+## Step 4: Restart gateway and verify
+
+```bash
+openclaw gateway restart
+openclaw models    # verify models appear
+```
+
+## How it works
+
+1. Plugin boots, loads wallet via the resolution cascade
+2. Registers each provider from config into OpenClaw's model catalog (API type: `openai-completions`, no auth required)
+3. HTTP route `/x402/*` intercepts inference requests, strips prefix, proxies to `upstreamUrl`
+4. On 402 response, auto-signs a Solana USDC payment and retries
+5. SSE streaming responses are parsed for token usage and logged to `~/.config/x402-proxy/history.jsonl`
+6. Tools and command are available to all agents on the gateway
+
+## Fetching latest models
+
+The model list on `surf.cascade.fyi` changes over time. Fetch the current catalog:
+
+```bash
+npx x402-proxy --protocol mpp --network solana \
+  https://surf.cascade.fyi/api/v1/inference/models
+```
+
+Then update the `models` array in your plugin config accordingly.
+
+## Troubleshooting
+
+- **Models don't appear in `openclaw models`** - the plugin uses a `catalog` hook (not `models` field). Make sure you're on x402-proxy >= 0.8.5.
+- **"no wallet found" in logs** - run `npx x402-proxy setup` or set `X402_PROXY_WALLET_MNEMONIC` env var before starting the gateway.
+- **402 errors on inference** - check wallet has USDC balance: use `x_balance` tool or `npx x402-proxy wallet`.
+- **Gateway cold start slow** - normal on small VMs (~72s). The `x402-wallet` service eagerly loads the wallet during boot.

package/dist/setup-lCsiivm2.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-import { t as runSetup } from "./setup-QtTFsCFs.js";
-export { runSetup };