feat(openclaw): add wallet setup via providerAuthChoices and /x_wallet setup

tenequm · tenequm · commit 69992e694678 · 2026-04-02T18:24:05.000+01:00
- Interactive wallet generate/import flow via OpenClaw gateway prompter
- /x_wallet setup subcommand for Telegram/slash-command wallet creation
- BIP-39 mnemonic validation on import
- createWalletFile() helper, static imports in handler.ts
- Updated example URLs and OpenClaw compat to 2026.4.1
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.11.0] - 2026-04-02
+
+### Added
+
+- OpenClaw `providerAuthChoices` wallet setup flow - interactive generate/import via gateway prompter
+- `/x_wallet setup` subcommand for Telegram/slash-command wallet creation (generate or import mnemonic)
+- BIP-39 mnemonic validation on import (both interactive and slash-command paths)
+- `createWalletFile()` helper in config module
+
+### Changed
+
+- Converted dynamic imports in `handler.ts` to static imports (mppx, viem/accounts)
+- Updated example URLs from POST `{"ref":"CoinbaseDev"}` to simpler GET `/twitter/user/openclaw`
+- Usage examples now show `npx x402-proxy` prefix consistently
+- OpenClaw compat bumped to `2026.4.1`
+- Wallet-not-found error messages now suggest `/x_wallet setup` instead of CLI-only instructions
+
+### Removed
+
+- Default model display from `/x_wallet` info output
+
+## [0.10.12] - 2026-04-02
+
+### Fixed
+
+- Restore explicit SetComputeUnitLimit instruction for Solana transactions
+- Strip `outputSchema` from proxied MCP tool definitions
+- Downgrade @modelcontextprotocol/sdk to 1.27.1 for compatibility
+
+[0.11.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.10.12...v0.11.0
+[0.10.12]: https://github.com/cascade-protocol/x402-proxy/releases/tag/v0.10.12
diff --git a/packages/x402-proxy/README.md b/packages/x402-proxy/README.md
@@ -5,7 +5,7 @@
 ## Quick Start
 
 ```bash
-npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user
+npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/openclaw
 ```
 
 That's it. The endpoint returns 402, x402-proxy pays and streams the response.
@@ -52,8 +52,8 @@ 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
-# POST request
-$ npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user
+# GET request
+$ npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/openclaw
 
 # POST with body and headers (curl-style short flags: -X, -H, -d)
 $ npx x402-proxy -X POST \
diff --git a/packages/x402-proxy/openclaw.plugin.json b/packages/x402-proxy/openclaw.plugin.json
@@ -2,9 +2,20 @@
   "id": "x402-proxy",
   "name": "mpp/x402 Payments Proxy",
   "description": "x402 and MPP payments, wallet tools, and paid inference proxying",
-  "version": "0.10.8",
   "providers": ["surf"],
   "autoEnableWhenConfiguredProviders": ["surf"],
+  "providerAuthChoices": [
+    {
+      "provider": "surf",
+      "method": "wallet-setup",
+      "choiceId": "x402-wallet-setup",
+      "choiceLabel": "x402-proxy wallet",
+      "choiceHint": "Generate or import a crypto wallet for paid inference",
+      "groupId": "x402-proxy",
+      "groupLabel": "x402-proxy",
+      "groupHint": "Crypto wallet for x402/MPP payments"
+    }
+  ],
   "skills": ["skills"],
   "contracts": {
     "tools": ["x_wallet", "x_balance", "x_request", "x_payment"]
diff --git a/packages/x402-proxy/package.json b/packages/x402-proxy/package.json
@@ -1,7 +1,7 @@
 {
   "name": "x402-proxy",
   "private": true,
-  "version": "0.10.12",
+  "version": "0.11.0",
   "description": "curl for x402 paid APIs. Auto-pays any endpoint on Base, Solana, and Tempo.",
   "type": "module",
   "sideEffects": false,
@@ -26,12 +26,12 @@
       "surf"
     ],
     "compat": {
-      "pluginApi": ">=2026.3.24",
-      "minGatewayVersion": "2026.3.24"
+      "pluginApi": ">=2026.4.1",
+      "minGatewayVersion": "2026.4.1"
     },
     "build": {
-      "openclawVersion": "2026.3.24",
-      "pluginSdkVersion": "2026.3.24"
+      "openclawVersion": "2026.4.1",
+      "pluginSdkVersion": "2026.4.1"
     }
   },
   "bin": {
@@ -71,7 +71,7 @@
     "yaml": "^2.8.3"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.3.8"
+    "openclaw": ">=2026.3.24"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -80,7 +80,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "openclaw": "^2026.3.24",
+    "openclaw": "^2026.4.1",
     "publint": "^0.3.18",
     "tsdown": "^0.21.5",
     "typescript": "^5.9.3",
diff --git a/packages/x402-proxy/skills/SKILL.md b/packages/x402-proxy/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 -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user
+npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/openclaw
 ```
 
 First run auto-creates a wallet. No setup needed.
diff --git a/packages/x402-proxy/src/commands/claude.ts b/packages/x402-proxy/src/commands/claude.ts
@@ -38,10 +38,10 @@ ANTHROPIC_BASE_URL pointed at it. All inference requests go through
 the proxy, which handles payments automatically via MPP.
 
 Usage:
-  $ x402-proxy claude                           Start with default model
-  $ x402-proxy claude --model z-ai/glm-5        Use a specific model
-  $ x402-proxy claude -- --print "explain this" Pass args to Claude Code
-  $ x402-proxy claude -- -p "summarize *.ts"    Print mode (non-interactive)
+  $ npx x402-proxy claude                           Start with default model
+  $ npx x402-proxy claude --model z-ai/glm-5        Use a specific model
+  $ npx x402-proxy claude -- --print "explain this" Pass args to Claude Code
+  $ npx x402-proxy claude -- -p "summarize *.ts"    Print mode (non-interactive)
 
 Available models (via surf.cascade.fyi):
 ${modelList}
diff --git a/packages/x402-proxy/src/commands/fetch.ts b/packages/x402-proxy/src/commands/fetch.ts
@@ -43,9 +43,9 @@ export const fetchCommand = buildCommand<FetchFlags, [url?: string], CommandCont
     fullDescription: `Make a paid HTTP request. Payment is automatic when the server returns 402.
 
 Examples:
-  $ 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'`,
+  $ npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/openclaw
+  $ npx x402-proxy -X POST -d '{"url":"https://x402.org"}' https://surf.cascade.fyi/api/v1/web/crawl
+  $ npx x402-proxy https://api.example.com/data | jq '.results'`,
   },
   parameters: {
     flags: {
@@ -157,9 +157,7 @@ Examples:
         console.log();
         console.log(
           pc.dim("  try: ") +
-            pc.cyan(
-              `$ npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user`,
-            ),
+            pc.cyan(`$ npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/openclaw`),
         );
         console.log();
         console.log(pc.dim("  https://github.com/cascade-protocol/x402-proxy"));
diff --git a/packages/x402-proxy/src/commands/mcp-add.ts b/packages/x402-proxy/src/commands/mcp-add.ts
@@ -251,7 +251,7 @@ export const mcpAddCommand = buildCommand<McpAddFlags, [name: string, url: strin
 
       prompts.log.step("Try your first request:");
       prompts.log.message(
-        `  ${pc.cyan(`$ npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user`)}`,
+        `  ${pc.cyan(`$ npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/openclaw`)}`,
       );
       prompts.log.message(
         `  ${pc.dim("Run")} ${pc.cyan("npx x402-proxy")} ${pc.dim("to see your wallet and balance")}`,
diff --git a/packages/x402-proxy/src/commands/serve.ts b/packages/x402-proxy/src/commands/serve.ts
@@ -224,9 +224,9 @@ export const serveCommand = buildCommand<ServeFlags, [upstreamUrl?: string], Com
     fullDescription: `Start a local HTTP proxy that forwards inference requests upstream and auto-pays x402 or MPP 402 challenges.
 
 Examples:
-  $ x402-proxy serve
-  $ x402-proxy serve --port 8402
-  $ x402-proxy serve https://surf.cascade.fyi/api/v1/inference --protocol mpp`,
+  $ npx x402-proxy serve
+  $ npx x402-proxy serve --port 8402
+  $ npx x402-proxy serve https://surf.cascade.fyi/api/v1/inference --protocol mpp`,
   },
   parameters: {
     flags: {
diff --git a/packages/x402-proxy/src/commands/setup.ts b/packages/x402-proxy/src/commands/setup.ts
@@ -2,16 +2,16 @@ import * as prompts from "@clack/prompts";
 import { buildCommand, type CommandContext } from "@stricli/core";
 import pc from "picocolors";
 import {
+  createWalletFile,
   getConfigDirShort,
   getWalletPath,
   isConfigured,
   loadWalletFile,
   type ProxyConfig,
   saveConfig,
   saveWalletFile,
-  type WalletFile,
 } from "../lib/config.js";
-import { deriveEvmKeypair, deriveSolanaKeypair, generateMnemonic } from "../lib/derive.js";
+import { generateMnemonic } from "../lib/derive.js";
 
 export async function runSetup(opts?: {
   force?: boolean;
@@ -53,19 +53,12 @@ export async function runSetup(opts?: {
       mnemonic = generateMnemonic();
     }
 
-    const evm = deriveEvmKeypair(mnemonic);
-    const sol = deriveSolanaKeypair(mnemonic);
-
-    const wallet: WalletFile = {
-      version: 1,
-      mnemonic,
-      addresses: { evm: evm.address, solana: sol.address },
-    };
+    const wallet = createWalletFile(mnemonic);
     saveWalletFile(wallet);
     saveConfig({ preferredProtocol: "x402" });
 
     process.stdout.write(
-      `${JSON.stringify({ base: evm.address, tempo: evm.address, solana: sol.address })}\n`,
+      `${JSON.stringify({ base: wallet.addresses.evm, tempo: wallet.addresses.evm, solana: wallet.addresses.solana })}\n`,
     );
     return;
   }
@@ -109,18 +102,11 @@ export async function runSetup(opts?: {
     mnemonic = (input as string).trim();
   }
 
-  const evm = deriveEvmKeypair(mnemonic);
-  const sol = deriveSolanaKeypair(mnemonic);
-
-  prompts.log.success(`Base address:   ${pc.green(evm.address)}`);
-  prompts.log.success(`Tempo address:  ${pc.green(evm.address)}`);
-  prompts.log.success(`Solana address: ${pc.green(sol.address)}`);
+  const wallet = createWalletFile(mnemonic);
 
-  const wallet: WalletFile = {
-    version: 1,
-    mnemonic,
-    addresses: { evm: evm.address, solana: sol.address },
-  };
+  prompts.log.success(`Base address:   ${pc.green(wallet.addresses.evm)}`);
+  prompts.log.success(`Tempo address:  ${pc.green(wallet.addresses.evm)}`);
+  prompts.log.success(`Solana address: ${pc.green(wallet.addresses.solana)}`);
 
   saveWalletFile(wallet);
 
@@ -167,12 +153,12 @@ export async function runSetup(opts?: {
   prompts.log.info(`Config directory: ${pc.dim(getConfigDirShort())}`);
 
   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(`  Base (USDC):   Send USDC to ${pc.cyan(evm.address)}`);
+  prompts.log.message(`  Solana (USDC): Send USDC to ${pc.cyan(wallet.addresses.solana)}`);
+  prompts.log.message(`  Base (USDC):   Send USDC to ${pc.cyan(wallet.addresses.evm)}`);
 
   prompts.log.step("Try your first request:");
   prompts.log.message(
-    `  ${pc.cyan(`$ npx x402-proxy -X POST -d '{"ref":"CoinbaseDev"}' https://surf.cascade.fyi/api/v1/twitter/user`)}`,
+    `  ${pc.cyan(`$ npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/openclaw`)}`,
   );
 
   prompts.outro(pc.green("Setup complete!"));
diff --git a/packages/x402-proxy/src/handler.ts b/packages/x402-proxy/src/handler.ts
@@ -1,6 +1,10 @@
 import type { x402Client } from "@x402/fetch";
 import { decodePaymentResponseHeader, wrapFetchWithPayment } from "@x402/fetch";
+import { Mppx, tempo } from "mppx/client";
+import { Session } from "mppx/tempo";
 import { parseUnits } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { clearSession, saveSession } from "./lib/config.js";
 import { getMppVoucherHeadroomUsdc, isDebugEnabled } from "./lib/env.js";
 
 export type PaymentInfo = {
@@ -157,17 +161,11 @@ function parseVoucherHeadroom(value: string | undefined): bigint {
 
 /**
  * Create an MPP proxy handler using mppx client.
- * Dynamically imports mppx/client to keep startup fast.
  */
 export async function createMppProxyHandler(opts: {
   evmKey: string;
   maxDeposit?: string;
 }): Promise<MppProxyHandler> {
-  const { Mppx, tempo } = await import("mppx/client");
-  const { Session } = await import("mppx/tempo");
-  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 voucherHeadroomRaw = parseVoucherHeadroom(getMppVoucherHeadroomUsdc());
diff --git a/packages/x402-proxy/src/lib/config.ts b/packages/x402-proxy/src/lib/config.ts
@@ -2,6 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { deriveEvmKeypair, deriveSolanaKeypair } from "./derive.js";
 
 export type ProxyConfig = {
   defaultNetwork?: string;
@@ -62,6 +63,12 @@ export function loadWalletFile(): WalletFile | null {
   }
 }
 
+export function createWalletFile(mnemonic: string): WalletFile {
+  const evm = deriveEvmKeypair(mnemonic);
+  const sol = deriveSolanaKeypair(mnemonic);
+  return { version: 1, mnemonic, addresses: { evm: evm.address, solana: sol.address } };
+}
+
 export function saveWalletFile(wallet: WalletFile): void {
   ensureConfigDir();
   fs.writeFileSync(getWalletPath(), JSON.stringify(wallet, null, 2), {
diff --git a/packages/x402-proxy/src/lib/derive.ts b/packages/x402-proxy/src/lib/derive.ts
@@ -17,13 +17,21 @@ import { sha512 } from "@noble/hashes/sha2.js";
 import { keccak_256 } from "@noble/hashes/sha3.js";
 import { base58 } from "@scure/base";
 import { HDKey } from "@scure/bip32";
-import { generateMnemonic as bip39Generate, mnemonicToSeedSync } from "@scure/bip39";
+import {
+  generateMnemonic as bip39Generate,
+  mnemonicToSeedSync,
+  validateMnemonic,
+} from "@scure/bip39";
 import { wordlist } from "@scure/bip39/wordlists/english.js";
 
 export function generateMnemonic(): string {
   return bip39Generate(wordlist, 256); // 24 words
 }
 
+export function isValidMnemonic(mnemonic: string): boolean {
+  return validateMnemonic(mnemonic, wordlist);
+}
+
 /**
  * SLIP-10 Ed25519 derivation at m/44'/501'/0'/0' (Phantom/Backpack compatible).
  */
diff --git a/packages/x402-proxy/src/openclaw/commands.ts b/packages/x402-proxy/src/openclaw/commands.ts
diff --git a/packages/x402-proxy/src/openclaw/plugin.ts b/packages/x402-proxy/src/openclaw/plugin.ts
diff --git a/packages/x402-proxy/src/openclaw/tools.ts b/packages/x402-proxy/src/openclaw/tools.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
