agentic-x402 0.3.6 → 0.3.8

package/SKILL.md

@@ -4,7 +4,7 @@ description: Make x402 payments to access gated APIs and content. Fetch paid res
 license: MIT
 compatibility: Requires Node.js 20+, network access to x402 facilitators and EVM chains
 homepage: https://www.npmjs.com/package/agentic-x402
-metadata: {"author": "monemetrics", "version": "0.3.6", "openclaw": {"requires": {"bins": ["x402"], "env": ["EVM_PRIVATE_KEY"]}, "primaryEnv": "EVM_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "agentic-x402", "bins": ["x402"], "label": "Install agentic-x402 (npm)"}], "plugin": true}}
+metadata: {"author": "monemetrics", "version": "0.3.7", "openclaw": {"requires": {"bins": ["x402"], "env": ["EVM_PRIVATE_KEY"]}, "primaryEnv": "EVM_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "agentic-x402", "bins": ["x402"], "label": "Install agentic-x402 (npm)"}], "plugin": true}}
 allowed-tools: Bash(x402:*) Bash(npm:*) Read
 ---
 

package/openclaw.plugin.json

@@ -1,9 +1,8 @@
 {
   "id": "agentic-x402",
   "name": "x402 Payments",
-  "version": "0.3.6",
-  "description": "Agent skill for x402 payments — pay for and sell gated content with background payment watching",
-  "skills": ["./skills/x402"],
+  "version": "0.3.8",
+  "description": "Agent plugin for x402 payments — pay for and sell gated content with background payment watching",
   "configSchema": {
     "type": "object",
     "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-x402",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Agent skill for x402 payments - pay for and sell gated content",
   "type": "module",
   "bin": {
@@ -12,7 +12,6 @@
   "files": [
     "bin/",
     "scripts/",
-    "skills/",
     "config/example.env",
     "openclaw.plugin.json",
     "README.md",

package/scripts/plugin/tools.ts

@@ -4,20 +4,28 @@
 import type { PluginTool } from './types.js';
 import type { PaymentWatcher } from './watcher.js';
 
+/** Helper to wrap a result as OpenClaw tool response */
+function json(payload: unknown) {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }],
+    details: payload,
+  };
+}
+
 export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
   return [
     // 1. x402_balance
     {
       name: 'x402_balance',
       description: 'Check wallet USDC and ETH balances on Base',
-      inputSchema: { type: 'object', properties: {}, required: [] },
-      async execute() {
+      parameters: { type: 'object', properties: {} },
+      async execute(_toolCallId, _params) {
         const { getClient, getWalletAddress, getUsdcBalance, getEthBalance } = await import('../core/client.js');
         const client = getClient();
         const address = getWalletAddress();
         const [usdc, eth] = await Promise.all([getUsdcBalance(), getEthBalance()]);
 
-        return {
+        return json({
           address,
           network: client.config.network,
           chainId: client.config.chainId,
@@ -25,7 +33,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
             usdc: { raw: usdc.raw.toString(), formatted: usdc.formatted },
             eth: { raw: eth.raw.toString(), formatted: eth.formatted },
           },
-        };
+        });
       },
     },
 
@@ -33,7 +41,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
     {
       name: 'x402_pay',
       description: 'Pay for an x402-gated resource. Returns the response body after payment.',
-      inputSchema: {
+      parameters: {
         type: 'object',
         properties: {
           url: { type: 'string', description: 'URL of the x402-gated resource' },
@@ -44,7 +52,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         },
         required: ['url'],
       },
-      async execute(params) {
+      async execute(_toolCallId, params) {
         const url = params.url as string;
         const method = (params.method as string) || 'GET';
         const body = params.body as string | undefined;
@@ -65,7 +73,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
           const responseBody = contentType?.includes('json')
             ? await probe.json()
             : await probe.text();
-          return { paid: false, status: probe.status, response: responseBody };
+          return json({ paid: false, status: probe.status, response: responseBody });
         }
 
         // Parse payment info
@@ -84,18 +92,18 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         const effectiveMax = maxPaymentUsd ?? client.config.maxPaymentUsd;
 
         if (priceNum > effectiveMax) {
-          return { paid: false, error: `Price $${priceNum} exceeds max $${effectiveMax}`, paymentInfo };
+          return json({ paid: false, error: `Price $${priceNum} exceeds max $${effectiveMax}`, paymentInfo });
         }
 
         if (dryRun) {
-          return { paid: false, dryRun: true, price: priceNum, paymentInfo };
+          return json({ paid: false, dryRun: true, price: priceNum, paymentInfo });
         }
 
         // Execute payment
         const response = await client.fetchWithPayment(url, { method, body, headers });
 
         if (!response.ok) {
-          return { paid: false, error: `${response.status} ${response.statusText}` };
+          return json({ paid: false, error: `${response.status} ${response.statusText}` });
         }
 
         const contentType = response.headers.get('content-type');
@@ -112,7 +120,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
           } catch { /* */ }
         }
 
-        return { paid: true, price: priceNum, transactionHash: txHash, response: responseBody };
+        return json({ paid: true, price: priceNum, transactionHash: txHash, response: responseBody });
       },
     },
 
@@ -120,7 +128,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
     {
       name: 'x402_fetch',
       description: 'Fetch a URL with automatic x402 payment handling. Simpler than x402_pay — just returns the content.',
-      inputSchema: {
+      parameters: {
         type: 'object',
         properties: {
           url: { type: 'string', description: 'URL to fetch' },
@@ -129,7 +137,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         },
         required: ['url'],
       },
-      async execute(params) {
+      async execute(_toolCallId, params) {
         const url = params.url as string;
         const method = (params.method as string) || 'GET';
         const body = params.body as string | undefined;
@@ -143,7 +151,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         const response = await client.fetchWithPayment(url, { method, body, headers });
 
         if (!response.ok) {
-          return { success: false, status: response.status, error: response.statusText };
+          return json({ success: false, status: response.status, error: response.statusText });
         }
 
         const contentType = response.headers.get('content-type');
@@ -151,7 +159,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
           ? await response.json()
           : await response.text();
 
-        return { success: true, status: response.status, response: responseBody };
+        return json({ success: true, status: response.status, response: responseBody });
       },
     },
 
@@ -159,7 +167,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
     {
       name: 'x402_create_link',
       description: 'Create a payment link via 21.cash to sell gated content',
-      inputSchema: {
+      parameters: {
         type: 'object',
         properties: {
           name: { type: 'string', description: 'Name of the payment link' },
@@ -171,7 +179,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         },
         required: ['name', 'price'],
       },
-      async execute(params) {
+      async execute(_toolCallId, params) {
         const name = params.name as string;
         const price = params.price as string;
         const gatedUrl = params.url as string | undefined;
@@ -180,7 +188,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         const webhookUrl = params.webhookUrl as string | undefined;
 
         if (!gatedUrl && !gatedText) {
-          return { success: false, error: 'Either url or text is required' };
+          return json({ success: false, error: 'Either url or text is required' });
         }
 
         const { getClient, getWalletAddress } = await import('../core/client.js');
@@ -210,10 +218,10 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
 
         const data = await response.json();
         if (!response.ok || !(data as Record<string, unknown>).success) {
-          return { success: false, error: (data as Record<string, unknown>).error ?? 'Unknown error' };
+          return json({ success: false, error: (data as Record<string, unknown>).error ?? 'Unknown error' });
         }
 
-        return data;
+        return json(data);
       },
     },
 
@@ -221,14 +229,14 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
     {
       name: 'x402_link_info',
       description: 'Get details about a payment link by router address',
-      inputSchema: {
+      parameters: {
         type: 'object',
         properties: {
           routerAddress: { type: 'string', description: 'Router contract address or payment URL' },
         },
         required: ['routerAddress'],
       },
-      async execute(params) {
+      async execute(_toolCallId, params) {
         let routerAddress = params.routerAddress as string;
 
         // Extract address from URL if needed
@@ -239,7 +247,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         }
 
         if (!routerAddress.startsWith('0x') || routerAddress.length !== 42) {
-          return { success: false, error: 'Invalid router address' };
+          return json({ success: false, error: 'Invalid router address' });
         }
 
         const { getConfig } = await import('../core/config.js');
@@ -250,10 +258,10 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         const data = await response.json();
 
         if (!response.ok || !(data as Record<string, unknown>).success) {
-          return { success: false, error: (data as Record<string, unknown>).error ?? 'Link not found' };
+          return json({ success: false, error: (data as Record<string, unknown>).error ?? 'Link not found' });
         }
 
-        return data;
+        return json(data);
       },
     },
 
@@ -261,14 +269,13 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
     {
       name: 'x402_routers',
       description: 'List payment routers where your wallet is a beneficiary',
-      inputSchema: {
+      parameters: {
         type: 'object',
         properties: {
           withBalances: { type: 'boolean', description: 'Fetch on-chain USDC balance for each router' },
         },
-        required: [],
       },
-      async execute(params) {
+      async execute(_toolCallId, params) {
         const withBalances = params.withBalances as boolean | undefined;
 
         const { getWalletAddress } = await import('../core/client.js');
@@ -282,13 +289,13 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         const data = await response.json() as { success: boolean; links?: Array<Record<string, unknown>>; error?: string };
 
         if (!response.ok || !data.success) {
-          return { success: false, error: data.error ?? 'Failed to fetch routers' };
+          return json({ success: false, error: data.error ?? 'Failed to fetch routers' });
         }
 
         const links = data.links ?? [];
 
         if (!withBalances) {
-          return {
+          return json({
             success: true,
             address,
             routers: links.map((l) => ({
@@ -298,7 +305,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
               sharePercent: l.beneficiary_percentage,
               createdAt: l.created_at,
             })),
-          };
+          });
         }
 
         // Fetch balances
@@ -340,7 +347,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
           };
         }));
 
-        return { success: true, address, routers };
+        return json({ success: true, address, routers });
       },
     },
 
@@ -348,7 +355,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
     {
       name: 'x402_distribute',
       description: 'Distribute (withdraw) USDC from a PaymentRouter contract',
-      inputSchema: {
+      parameters: {
         type: 'object',
         properties: {
           routerAddress: { type: 'string', description: 'PaymentRouter contract address' },
@@ -356,12 +363,12 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         },
         required: ['routerAddress'],
       },
-      async execute(params) {
+      async execute(_toolCallId, params) {
         const routerAddress = params.routerAddress as string;
         const specifiedAmount = params.amount as string | undefined;
 
         if (!routerAddress.startsWith('0x') || routerAddress.length !== 42) {
-          return { success: false, error: 'Invalid router address' };
+          return json({ success: false, error: 'Invalid router address' });
         }
 
         const { getClient } = await import('../core/client.js');
@@ -400,17 +407,17 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
         });
 
         if (routerBalance === 0n) {
-          return { success: false, error: 'Router has no USDC balance to distribute' };
+          return json({ success: false, error: 'Router has no USDC balance to distribute' });
         }
 
         let distributeAmount: bigint;
         if (specifiedAmount) {
           distributeAmount = parseUnits(specifiedAmount, 6);
           if (distributeAmount > routerBalance) {
-            return {
+            return json({
               success: false,
               error: `Requested ${specifiedAmount} USDC exceeds balance ${formatUnits(routerBalance, 6)} USDC`,
-            };
+            });
           }
         } else {
           distributeAmount = routerBalance;
@@ -426,7 +433,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
 
         const receipt = await client.publicClient.waitForTransactionReceipt({ hash: txHash });
 
-        return {
+        return json({
           success: receipt.status === 'success',
           routerAddress,
           amount: formatUnits(distributeAmount, 6),
@@ -434,7 +441,7 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
           transactionHash: txHash,
           blockNumber: receipt.blockNumber.toString(),
           status: receipt.status,
-        };
+        });
       },
     },
 
@@ -442,12 +449,12 @@ export function createTools(watcher: PaymentWatcher | null): PluginTool[] {
     {
       name: 'x402_watcher_status',
       description: 'Get the status of the background payment watcher (tracked routers, payments detected)',
-      inputSchema: { type: 'object', properties: {}, required: [] },
+      parameters: { type: 'object', properties: {} },
       async execute() {
         if (!watcher) {
-          return { running: false, error: 'Watcher is not enabled' };
+          return json({ running: false, error: 'Watcher is not enabled' });
         }
-        return watcher.getStatus();
+        return json(watcher.getStatus());
       },
     },
   ];

package/scripts/plugin/types.ts

@@ -15,24 +15,33 @@ export interface PluginService {
   stop(): Promise<void>;
 }
 
-/** JSON Schema for tool input parameters */
-export interface ToolInputSchema {
+/** JSON Schema for tool parameters */
+export interface ToolParameters {
   type: 'object';
   properties: Record<string, {
     type: string;
-    description: string;
+    description?: string;
     enum?: string[];
     default?: unknown;
   }>;
   required?: string[];
 }
 
+/** Tool result content block */
+export interface ToolResultContent {
+  type: 'text';
+  text: string;
+}
+
 /** An agent tool registered by a plugin */
 export interface PluginTool {
   name: string;
   description: string;
-  inputSchema: ToolInputSchema;
-  execute(params: Record<string, unknown>): Promise<unknown>;
+  parameters: ToolParameters;
+  execute(toolCallId: string, params: Record<string, unknown>): Promise<{
+    content: ToolResultContent[];
+    details?: unknown;
+  }>;
 }
 
 /** Commander.js-style program for CLI registration */

package/skills/x402/SKILL.md

@@ -1,486 +0,0 @@
----
-name: x402
-description: Make x402 payments to access gated APIs and content. Fetch paid resources, check wallet balance, create payment links, monitor routers for incoming payments, and distribute funds. Use when encountering 402 Payment Required responses or when the user wants to pay for web resources with crypto. Also available as an OpenClaw plugin with background payment watching and 8 agent tools.
-license: MIT
-compatibility: Requires Node.js 20+, network access to x402 facilitators and EVM chains
-homepage: https://www.npmjs.com/package/agentic-x402
-metadata: {"author": "monemetrics", "version": "0.3.6", "openclaw": {"requires": {"bins": ["x402"], "env": ["EVM_PRIVATE_KEY"]}, "primaryEnv": "EVM_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "agentic-x402", "bins": ["x402"], "label": "Install agentic-x402 (npm)"}], "plugin": true}}
-allowed-tools: Bash(x402:*) Bash(npm:*) Read
----
-
-# x402 Agent Skill
-
-Pay for x402-gated APIs and content using USDC on Base. This skill enables agents to autonomously make crypto payments when accessing paid web resources.
-
-## Quick Reference
-
-| Command | Description |
-|---------|-------------|
-| `x402 setup` | Create or configure wallet |
-| `x402 balance` | Check USDC and ETH balances |
-| `x402 pay <url>` | Pay for a gated resource |
-| `x402 fetch <url>` | Fetch with auto-payment |
-| `x402 create-link` | Create payment link (seller) |
-| `x402 link-info <addr>` | Get payment link details |
-| `x402 routers` | List routers where your wallet is a beneficiary |
-| `x402 distribute <addr>` | Distribute USDC from a PaymentRouter |
-
-## OpenClaw Plugin
-
-When installed as an OpenClaw plugin, agentic-x402 provides **8 agent tools** and a **background payment watcher** — no CLI required.
-
-### Install as Plugin
-
-```bash
-openclaw plugins install agentic-x402
-```
-
-### Agent Tools
-
-When running inside OpenClaw, the agent can call these tools directly (no shell commands needed):
-
-| Tool | Description |
-|------|-------------|
-| `x402_balance` | Check wallet USDC + ETH balances |
-| `x402_pay` | Pay for x402-gated resource (supports dry-run) |
-| `x402_fetch` | Fetch URL with automatic payment |
-| `x402_create_link` | Create payment link via 21.cash |
-| `x402_link_info` | Get link details by router address |
-| `x402_routers` | List beneficiary routers (optional balances) |
-| `x402_distribute` | Distribute USDC from a router |
-| `x402_watcher_status` | Get watcher state (tracked routers, payments detected) |
-
-All tools return structured JSON. Parameters use camelCase (e.g., `routerAddress`, `maxPaymentUsd`, `withBalances`).
-
-### Background Payment Watcher
-
-The plugin includes a background service that monitors your payment routers for incoming USDC:
-
-- Fetches your routers from the 21.cash API
-- Polls USDC `balanceOf` for each router onchain (free view call, no gas)
-- Detects balance increases and triggers a hook at `/hooks/agent` with payment details
-- Configurable poll interval (default 30s)
-- First poll seeds state without triggering notifications (no false positives on restart)
-
-When a payment is detected, the watcher sends a hook with:
-```json
-{
-  "name": "x402-payment",
-  "wakeMode": "now",
-  "data": {
-    "routerAddress": "0x...",
-    "routerName": "My Link",
-    "previousBalance": "10.00",
-    "newBalance": "15.00",
-    "increase": "5.00",
-    "detectedAt": "2025-01-15T12:00:00.000Z"
-  }
-}
-```
-
-### Plugin Configuration
-
-All config is optional — zero-config if `~/.x402/.env` exists. Config priority:
-
-1. Environment variables (highest)
-2. Plugin config (from OpenClaw)
-3. `~/.x402/.env` (dotenv)
-4. Hardcoded defaults
-
-Plugin config keys (set in OpenClaw):
-
-| Key | Description | Default |
-|-----|-------------|---------|
-| `evmPrivateKey` | EVM private key (0x-prefixed) | from env |
-| `network` | `mainnet` or `testnet` | `mainnet` |
-| `maxPaymentUsd` | Max payment limit in USD | `10` |
-| `x402LinksApiUrl` | 21.cash API URL | `https://21.cash` |
-| `watcher.enabled` | Enable background payment watcher | `true` |
-| `watcher.pollIntervalMs` | Poll interval in ms | `30000` |
-| `watcher.notifyOnPayment` | Send hook on payment detection | `true` |
-
-### Plugin CLI Commands
-
-```bash
-openclaw x402 watch              # Start watcher in foreground (debugging)
-openclaw x402 watch --interval 10000   # Custom poll interval
-openclaw x402 status             # Show watcher state, tracked routers, payment count
-```
-
-## Installation
-
-```bash
-npm i -g agentic-x402
-```
-
-Once installed, the `x402` command is available globally:
-
-```bash
-x402 --help
-x402 --version
-```
-
-## Setup
-
-Run the interactive setup to create a new wallet:
-
-```bash
-x402 setup
-```
-
-This will:
-1. Generate a new wallet (recommended) or accept an existing key
-2. Save configuration to `~/.x402/.env`
-3. Display your wallet address for funding
-
-**Important:** Back up your private key immediately after setup!
-
-### Manual Configuration
-
-Alternatively, set the environment variable directly:
-
-```bash
-export EVM_PRIVATE_KEY=0x...your_private_key...
-```
-
-Or create a config file:
-
-```bash
-mkdir -p ~/.x402
-echo "EVM_PRIVATE_KEY=0x..." > ~/.x402/.env
-chmod 600 ~/.x402/.env
-```
-
-Verify setup:
-
-```bash
-x402 balance
-```
-
-## Paying for Resources
-
-### When you encounter HTTP 402 Payment Required
-
-Use `x402 pay` to make the payment and access the content:
-
-```bash
-x402 pay https://api.example.com/paid-endpoint
-```
-
-The command will:
-1. Check payment requirements
-2. Verify amount is within limits
-3. Process the payment
-4. Return the gated content
-
-### Automatic payment with fetch
-
-Use `x402 fetch` for seamless payment handling:
-
-```bash
-x402 fetch https://api.example.com/data --json
-```
-
-This wraps fetch with x402 payment handling - if the resource requires payment, it's handled automatically.
-
-### Payment limits
-
-By default, payments are limited to $10 USD. Override with `--max`:
-
-```bash
-x402 pay https://expensive-api.com/data --max 50
-```
-
-Or set globally:
-```bash
-export X402_MAX_PAYMENT_USD=25
-```
-
-### Dry run
-
-Preview payment without executing:
-
-```bash
-x402 pay https://api.example.com/data --dry-run
-```
-
-## Creating Payment Links (Seller)
-
-Create payment links to monetize your own content using x402-links-server:
-
-### Setup for link creation
-
-Add to `.env`:
-```bash
-X402_LINKS_API_URL=https://your-x402-links-server.com
-```
-
-### Create a link
-
-Gate a URL:
-```bash
-x402 create-link --name "Premium API" --price 1.00 --url https://api.example.com/premium
-```
-
-Gate text content:
-```bash
-x402 create-link --name "Secret" --price 0.50 --text "The secret message..."
-```
-
-With webhook notification:
-```bash
-x402 create-link --name "Guide" --price 5.00 --url https://mysite.com/guide --webhook https://mysite.com/payment-hook
-```
-
-### Get link info
-
-```bash
-x402 link-info 0x1234...5678
-x402 link-info https://21.cash/pay/0x1234...5678
-```
-
-## Managing Routers
-
-### List your routers
-
-See all payment routers where your wallet is a beneficiary:
-
-```bash
-x402 routers
-x402 routers --with-balance    # Include on-chain USDC balances
-x402 routers --json
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--with-balance` | Fetch on-chain USDC balance for each router | — |
-| `--json` | Output as JSON | — |
-| `-h, --help` | Show help | — |
-
-### Distribute funds
-
-Withdraw accumulated USDC from a PaymentRouter contract:
-
-```bash
-x402 distribute 0x1234...5678
-x402 distribute 0x1234...5678 --amount 5.00
-x402 distribute 0x1234...5678 --force --json
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `<router-address>` | PaymentRouter contract address (positional) | **required** |
-| `--amount` | Specific USDC amount to distribute (defaults to full balance) | full balance |
-| `--force` | Skip gas balance warning | — |
-| `--json` | Output as JSON | — |
-| `-h, --help` | Show help | — |
-
-## Command Reference
-
-### x402 balance
-
-Check wallet balances.
-
-```bash
-x402 balance [--json] [--full]
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--json` | Output as JSON (address, network, chainId, balances) | — |
-| `--full` | Show full wallet address instead of truncated | — |
-| `-h, --help` | Show help | — |
-
-### x402 pay
-
-Pay for an x402-gated resource.
-
-```bash
-x402 pay <url> [options]
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `<url>` | The URL of the x402-gated resource (positional) | **required** |
-| `--method` | HTTP method | `GET` |
-| `--body` | Request body (for POST/PUT requests) | — |
-| `--header` | Add custom header (can be used multiple times) | — |
-| `--max` | Maximum payment in USD (overrides config) | from config |
-| `--dry-run` | Show payment details without paying | — |
-| `-h, --help` | Show help | — |
-
-### x402 fetch
-
-Fetch with automatic payment.
-
-```bash
-x402 fetch <url> [options]
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `<url>` | The URL to fetch (positional) | **required** |
-| `--method` | HTTP method | `GET` |
-| `--body` | Request body (for POST/PUT) | — |
-| `--header` | Add header as `"Key: Value"` | — |
-| `--json` | Output as JSON only (for piping to other tools) | — |
-| `--raw` | Output raw response body only (no headers or status) | — |
-| `-h, --help` | Show help | — |
-
-### x402 create-link
-
-Create a payment link.
-
-```bash
-x402 create-link --name <name> --price <usd> [options]
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--name` | Name of the payment link | **required** |
-| `--price` | Price in USD (e.g., `"5.00"` or `"0.10"`) | **required** |
-| `--url` | URL to gate behind payment | — |
-| `--text` | Text content to gate behind payment | — |
-| `--desc` | Description of the link | — |
-| `--webhook` | Webhook URL for payment notifications | — |
-| `--json` | Output as JSON | — |
-| `-h, --help` | Show help | — |
-
-> **Note:** Either `--url` or `--text` is required. The link is deployed as a smart contract on Base.
-
-### x402 link-info
-
-Get payment link details.
-
-```bash
-x402 link-info <router-address> [--json]
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `<address>` | Router contract address or full payment URL (positional) | **required** |
-| `--json` | Output as JSON | — |
-| `-h, --help` | Show help | — |
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `EVM_PRIVATE_KEY` | Wallet private key (0x-prefixed) | **required** |
-| `X402_NETWORK` | `mainnet` (Base, chain 8453) or `testnet` (Base Sepolia, chain 84532) | `mainnet` |
-| `X402_MAX_PAYMENT_USD` | Safety limit — payments exceeding this are rejected unless `--max` is used | `10` |
-| `X402_FACILITATOR_URL` | Custom facilitator URL | Coinbase (mainnet) / x402.org (testnet) |
-| `X402_SLIPPAGE_BPS` | Slippage tolerance in basis points (100 bps = 1%) | `50` |
-| `X402_VERBOSE` | Enable verbose logging (`1` = on, `0` = off) | `0` |
-| `X402_LINKS_API_URL` | Base URL of x402-links-server (e.g., `https://21.cash`) | — |
-
-## Supported Networks
-
-| Network | Chain ID | CAIP-2 ID |
-|---------|----------|-----------|
-| Base Mainnet | 8453 | eip155:8453 |
-| Base Sepolia | 84532 | eip155:84532 |
-
-## Payment Token
-
-All payments use **USDC** (USD Coin) on the selected network.
-
-- Base Mainnet: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
-- Base Sepolia: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
-
-## How x402 Works
-
-1. Client requests a resource
-2. Server responds with `402 Payment Required` + payment details
-3. Client signs a payment authorization (USDC transfer)
-4. Client retries request with payment signature
-5. Server verifies payment via facilitator
-6. Server settles payment on-chain
-7. Server returns the gated content
-
-The x402 protocol is gasless for buyers - the facilitator sponsors gas fees.
-
-## Troubleshooting
-
-### "Missing required environment variable: EVM_PRIVATE_KEY"
-
-Set your wallet private key:
-```bash
-export EVM_PRIVATE_KEY=0x...
-```
-
-Or create a `.env` file in your working directory, or install globally and use `~/.x402/.env`.
-
-### "Payment exceeds max limit"
-
-Increase the limit:
-```bash
-x402 pay https://... --max 50
-```
-
-### Low balance warnings
-
-Fund your wallet with:
-- **USDC** for payments
-- **ETH** for gas (small amount, ~0.001 ETH)
-
-### Network mismatch
-
-Ensure your wallet has funds on the correct network:
-- `X402_NETWORK=mainnet` → Base mainnet
-- `X402_NETWORK=testnet` → Base Sepolia
-
-## Backup Your Private Key
-
-Your private key is stored in `~/.x402/.env`. If lost, your funds cannot be recovered.
-
-### Recommended Backup Methods
-
-1. **Password Manager** (Recommended)
-   - Store in 1Password, Bitwarden, or similar
-   - Create a secure note with your private key
-   - Tag it for easy retrieval
-
-2. **Encrypted File**
-   ```bash
-   # Encrypt with GPG
-   gpg -c ~/.x402/.env
-   # Creates ~/.x402/.env.gpg - store this backup securely
-   ```
-
-3. **Paper Backup** (for larger amounts)
-   - Write down the private key
-   - Store in a safe or safety deposit box
-   - Never store digitally unencrypted
-
-### View Your Private Key
-
-```bash
-cat ~/.x402/.env | grep EVM_PRIVATE_KEY
-```
-
-### Recovery
-
-To restore from backup:
-```bash
-mkdir -p ~/.x402
-echo "EVM_PRIVATE_KEY=0x...your_backed_up_key..." > ~/.x402/.env
-chmod 600 ~/.x402/.env
-x402 balance  # verify
-```
-
-## Security Best Practices
-
-- **Use a dedicated wallet** — Never use your main wallet with automated agents
-- **Limit funds** — Only transfer what you need for payments
-- **Set payment limits** — Configure `X402_MAX_PAYMENT_USD` to cap exposure
-- **Test first** — Use `X402_NETWORK=testnet` with test tokens before mainnet
-- **Protect the config** — `~/.x402/.env` has 600 permissions; keep it that way
-- **Never share** — Your private key gives full access to your wallet
-
-## Links
-
-- [x402 Protocol Docs](https://docs.x402.org/)
-- [x402 GitHub](https://github.com/coinbase/x402)
-- [npm: agentic-x402](https://www.npmjs.com/package/agentic-x402)
-- [Base Network](https://base.org/)