x402-proxy-openclaw 0.10.9

package/skills/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: x402-proxy
+description: Use x402-proxy CLI for consuming and debugging x402 and MPP paid APIs. Use this skill when testing x402/MPP endpoints, configuring MCP payment proxies for AI agents, managing wallets, or scripting paid HTTP requests. Triggers on x402-proxy, npx x402-proxy, x402 endpoint testing, MPP streaming payments, paid API debugging, MCP payment proxy, wallet management, or any mention of auto-paying HTTP 402 responses.
+---
+
+# x402-proxy
+
+`curl` for x402 and MPP paid APIs. Auto-pays HTTP 402 responses with USDC on Base, Solana, and [Tempo](https://tempo.xyz/). Supports one-time payments (x402, MPP charge) and pay-per-token streaming (MPP sessions).
+
+## Quick start
+
+```bash
+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.
+
+## 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 serve                        # local paid inference proxy server
+x402-proxy claude                       # run Claude Code through paid local proxy
+x402-proxy mcp <url>                    # MCP stdio proxy for AI agents
+x402-proxy mcp add <name> <url>         # install MCP server into AI client
+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 config                       # show current configuration
+x402-proxy config set <key> <value>     # set a config value
+x402-proxy config unset <key>           # remove a config value
+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 <NETWORK>       Force payment chain (base, solana, tempo)
+--protocol <PROTOCOL>    Payment protocol (x402, mpp)
+--verbose                Show debug details (protocol negotiation, headers, payment flow)
+```
+
+## MCP proxy for AI agents
+
+Quick setup (auto-detects installed AI clients):
+
+```bash
+x402-proxy mcp add surf https://surf.cascade.fyi/mcp
+```
+
+Or drop into your client config manually:
+
+```json
+{
+  "mcpServers": {
+    "surf": {
+      "command": "npx",
+      "args": ["-y", "x402-proxy", "mcp", "https://surf.cascade.fyi/mcp"]
+    }
+  }
+}
+```
+
+For OpenClaw:
+
+```bash
+openclaw mcp set surf '{"command":"npx","args":["-y","x402-proxy","mcp","https://surf.cascade.fyi/mcp"]}'
+```
+
+The wallet is auto-generated on first run and stored at `~/.config/x402-proxy/wallet.json`. No env vars needed. The proxy intercepts 402 responses, pays automatically, forwards the result. Supports StreamableHTTP and SSE.
+
+For non-interactive setup (e.g. automated provisioning):
+
+```bash
+npx x402-proxy setup --non-interactive
+# outputs: {"evm":"0x...","solana":"..."}
+```
+
+## 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"
+preferredProtocol: x402       # or "mpp" for Tempo/MPP endpoints
+mppSessionBudget: "1"         # max USDC deposit for MPP streaming sessions
+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 --verbose 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.
+
+## OpenClaw Plugin
+
+x402-proxy also ships as a separate [OpenClaw](https://openclaw.dev) plugin package, `x402-proxy-openclaw`, 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`.
+
+Quick install:
+
+```bash
+openclaw plugins install x402-proxy-openclaw
+npx x402-proxy setup   # creates wallet if needed
+```
+
+Registers: `x_wallet` tool, `x_request` tool (aliased as `x_balance`/`x_payment`), `/x_wallet` and `/x_send` commands, `/x402-proxy/*` HTTP route for inference proxying.
+
+## 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 };
+```

package/skills/references/openclaw-plugin.md

@@ -0,0 +1,145 @@
+# OpenClaw Plugin Setup
+
+`x402-proxy-openclaw` is the published [OpenClaw](https://openclaw.dev) plugin package for x402-proxy. It gives your gateway automatic x402 and MPP payment, wallet management, and pay-per-use inference proxying via USDC on Solana, Base, and Tempo.
+
+## What it registers
+
+- **`x_wallet` tool** (alias: `x_balance`) - check wallet readiness, balances, and spend history for x402 and MPP payments
+- **`x_request` tool** (alias: `x_payment`) - call a paid HTTP endpoint with automatic x402 or MPP settlement (params: `url`, `method`, `params`, `headers`, `protocol`)
+- **`/x_wallet` command** - wallet status dashboard, `history [page]`
+- **`/x_send` command** - send USDC with confirmation step (`/x_send <amount|all> <address>`, then `/x_send confirm`)
+- **HTTP route `/x402-proxy/*`** - proxies requests to upstream inference endpoints with payment, tracks token usage and cost
+
+## Step 1: Install the plugin
+
+```bash
+openclaw plugins install x402-proxy-openclaw
+```
+
+This downloads `x402-proxy-openclaw` from npm, validates `openclaw.plugin.json`, and installs the plugin under `~/.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
+
+If you do nothing, the plugin now defaults to:
+
+- provider id: `surf`
+- gateway base URL: `/x402-proxy/v1`
+- upstream: `https://surf.cascade.fyi/api/v1/inference`
+- protocol: `mpp`
+
+You only need explicit config if you want to override the defaults or supply a custom model catalog.
+
+Add the plugin config to your `openclaw.json` (or via `openclaw config edit`):
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "x402-proxy": {
+        "config": {
+          "providers": {
+            "surf-inference": {
+              "baseUrl": "/x402-proxy/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-proxy/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-proxy/*` intercepts inference requests, strips prefix, proxies to `upstreamUrl`
+4. On 402 response, auto-pays via MPP (Tempo/Base) or x402 (Solana) depending on provider config
+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/v1/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_wallet` 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.