agentic-x402 0.2.6 → 0.3.0

package/README.md

@@ -11,6 +11,8 @@ This skill gives AI agents the ability to:
 - **Fetch** content with automatic payment handling
 - **Create** payment links to sell content (via 21.cash)
 - **Manage** wallet balances (USDC + ETH for gas)
+- **Monitor** payment routers for incoming payments (background watcher)
+- **Distribute** accumulated funds from routers
 
 ## Installation
 
@@ -78,6 +80,99 @@ x402 fetch https://api.example.com/data --json
 
 # 6. Create a payment link (requires x402-links-server)
 x402 create-link --name "My API" --price 1.00 --url https://api.example.com/premium
+
+# 7. List your routers and check balances
+x402 routers --with-balance
+
+# 8. Withdraw accumulated funds
+x402 distribute 0x1234...5678
+```
+
+## OpenClaw Plugin
+
+agentic-x402 works as an [OpenClaw](https://openclaw.dev) plugin, providing **8 agent tools** and a **background payment watcher** with zero CLI required.
+
+### Install as Plugin
+
+```bash
+openclaw plugins install agentic-x402
+```
+
+All configuration is optional — the plugin picks up your existing `~/.x402/.env` automatically.
+
+### Agent Tools
+
+When running inside OpenClaw, the agent can call these tools directly:
+
+| 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 false positives on restart
+
+When a payment is detected, the watcher POSTs to `http://127.0.0.1:<port>/hooks/agent`:
+
+```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"
+  }
+}
+```
+
+This eliminates the need to expose your gateway externally or use a tunnel for webhook delivery.
+
+### Plugin Configuration
+
+All config is optional. 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 and payment count
 ```
 
 ## Commands
@@ -200,13 +295,52 @@ x402 link-info https://21.cash/pay/0x1234...5678
 | `--json` | Output as JSON | — |
 | `-h, --help` | Show help | — |
 
+---
+
+### routers — List Your Payment Routers
+
+See all payment routers where your wallet is a beneficiary. Optionally fetch on-chain USDC balances.
+
+```bash
+x402 routers
+x402 routers --with-balance
+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 — Withdraw Funds from a Router
+
+Distribute accumulated USDC from a PaymentRouter contract. Calls the router's `distribute()` function on-chain.
+
+```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 | — |
+
 ## Configuration
 
 Config is loaded from these locations (in order of priority):
 
 1. Environment variables
-2. `.env` file in current directory
-3. `~/.x402/.env` (global config)
+2. Plugin config (when running as OpenClaw plugin)
+3. `.env` file in current directory
+4. `~/.x402/.env` (global config)
 
 ### Environment Variables
 
@@ -248,6 +382,8 @@ Config is loaded from these locations (in order of priority):
 | **Payments** | `fetch <url>` | Fetch with auto-payment (pipe-friendly `--json`/`--raw`) |
 | **Links** | `create-link` | Create a payment link to sell content (21.cash) |
 | **Links** | `link-info <addr>` | Get info about a payment link |
+| **Routers** | `routers` | List routers where your wallet is a beneficiary |
+| **Routers** | `distribute <addr>` | Distribute USDC from a PaymentRouter |
 
 ## For Agents
 
@@ -262,8 +398,13 @@ x402 fetch https://api.example.com/data --json
 
 # Raw output for further processing
 x402 fetch https://api.example.com/data --raw
+
+# Router balances as JSON
+x402 routers --with-balance --json
 ```
 
+When installed as an OpenClaw plugin, agents get native tool access (`x402_balance`, `x402_pay`, etc.) without needing shell commands at all.
+
 ## Backup Your Private Key
 
 Your private key is stored in `~/.x402/.env`. **If lost, your funds cannot be recovered.**

package/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: agentic-x402
-description: Make x402 payments to access gated APIs and content. Fetch paid resources, check wallet balance, and create payment links. Use when encountering 402 Payment Required responses or when the user wants to pay for web resources with crypto.
+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.2.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)"}]}}
+metadata: {"author": "monemetrics", "version": "0.3.0", "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
 ---
 
@@ -22,6 +22,90 @@ Pay for x402-gated APIs and content using USDC on Base. This skill enables agent
 | `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
 
@@ -155,6 +239,42 @@ 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

package/openclaw.plugin.json

@@ -0,0 +1,73 @@
+{
+  "id": "agentic-x402",
+  "name": "x402 Payments",
+  "version": "0.3.0",
+  "description": "Agent skill for x402 payments — pay for and sell gated content with background payment watching",
+  "skills": ["./skills/x402"],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "evmPrivateKey": {
+        "type": "string",
+        "description": "EVM private key (0x-prefixed). Falls back to EVM_PRIVATE_KEY env var or ~/.x402/.env"
+      },
+      "network": {
+        "type": "string",
+        "enum": ["mainnet", "testnet"],
+        "default": "mainnet",
+        "description": "Network to use: mainnet (Base 8453) or testnet (Base Sepolia 84532)"
+      },
+      "maxPaymentUsd": {
+        "type": "number",
+        "default": 10,
+        "description": "Maximum payment amount in USD before rejection"
+      },
+      "x402LinksApiUrl": {
+        "type": "string",
+        "default": "https://21.cash",
+        "description": "Base URL of the x402 links API (21.cash)"
+      },
+      "watcher": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable background payment watcher"
+          },
+          "pollIntervalMs": {
+            "type": "number",
+            "default": 30000,
+            "description": "Poll interval in milliseconds for checking router balances"
+          },
+          "notifyOnPayment": {
+            "type": "boolean",
+            "default": true,
+            "description": "Send hook notification when a payment is detected"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "additionalProperties": false
+  },
+  "uiHints": {
+    "evmPrivateKey": {
+      "label": "EVM Private Key",
+      "sensitive": true,
+      "placeholder": "0x..."
+    },
+    "network": {
+      "label": "Network",
+      "placeholder": "mainnet"
+    },
+    "maxPaymentUsd": {
+      "label": "Max Payment (USD)",
+      "placeholder": "10"
+    },
+    "x402LinksApiUrl": {
+      "label": "21.cash API URL",
+      "placeholder": "https://21.cash"
+    }
+  }
+}

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "agentic-x402",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Agent skill for x402 payments - pay for and sell gated content",
   "type": "module",
   "bin": {
     "x402": "./bin/x402.js"
   },
+  "openclaw": {
+    "extensions": ["./scripts/plugin/index.ts"]
+  },
   "files": [
     "bin/",
     "scripts/",
+    "skills/",
     "config/example.env",
+    "openclaw.plugin.json",
     "README.md",
     "SKILL.md"
   ],

package/scripts/plugin/cli.ts

@@ -0,0 +1,91 @@
+// CLI commands for the OpenClaw plugin
+// Registered via api.registerCli with Commander.js-style program
+
+import type { PluginLogger, OpenClawPluginApi } from './types.js';
+import type { PaymentWatcher } from './watcher.js';
+
+export function registerCliCommands(
+  api: OpenClawPluginApi,
+  watcher: PaymentWatcher | null,
+  logger: PluginLogger,
+): void {
+  api.registerCli(({ program }) => {
+    const x402 = program.command('x402').description('x402 payment tools');
+
+    x402
+      .command('watch')
+      .description('Start the payment watcher in foreground (for debugging)')
+      .option('--interval <ms>', 'Poll interval in milliseconds', '30000')
+      .action(async (opts: unknown) => {
+        const { interval: intervalStr } = opts as { interval: string };
+        if (watcher) {
+          console.log('Watcher is already running as a background service.');
+          const status = watcher.getStatus();
+          console.log(`Tracking ${status.trackedRouters.length} router(s)`);
+          console.log(`Payments detected: ${status.paymentsDetected}`);
+          return;
+        }
+
+        // Start a standalone watcher for debugging
+        const { PaymentWatcher: WatcherClass } = await import('./watcher.js');
+        const { applyConfigBridge } = await import('./config-bridge.js');
+
+        applyConfigBridge({});
+
+        const interval = parseInt(intervalStr, 10);
+
+        const debugWatcher = new WatcherClass({
+          logger,
+          gatewayPort: 0,
+          pollIntervalMs: interval,
+          notifyOnPayment: false,
+        });
+
+        console.log('Starting payment watcher in foreground...');
+        console.log('Press Ctrl+C to stop.\n');
+
+        process.on('SIGINT', async () => {
+          await debugWatcher.stop();
+          process.exit(0);
+        });
+
+        await debugWatcher.start();
+
+        // Keep alive
+        await new Promise(() => {});
+      });
+
+    x402
+      .command('status')
+      .description('Show payment watcher status, tracked routers, and payment count')
+      .action(() => {
+        if (!watcher) {
+          console.log('Payment watcher is not running.');
+          console.log('Enable it in your OpenClaw plugin config or start it with: openclaw x402 watch');
+          return;
+        }
+
+        const status = watcher.getStatus();
+
+        console.log('x402 Payment Watcher Status');
+        console.log('===========================\n');
+        console.log(`Running:           ${status.running ? 'Yes' : 'No'}`);
+        console.log(`Poll interval:     ${status.pollIntervalMs / 1000}s`);
+        console.log(`Payments detected: ${status.paymentsDetected}`);
+        console.log(`Last poll:         ${status.lastPollAt ?? 'Never'}`);
+
+        if (status.trackedRouters.length === 0) {
+          console.log('\nNo routers tracked yet.');
+        } else {
+          console.log(`\nTracked Routers (${status.trackedRouters.length}):`);
+          for (const r of status.trackedRouters) {
+            console.log(`  ${r.name}`);
+            console.log(`    Address: ${r.address}`);
+            console.log(`    Balance: ${r.balance} USDC`);
+            console.log(`    Checked: ${r.lastChecked}`);
+            console.log('');
+          }
+        }
+      });
+  }, { commands: ['x402'] });
+}

package/scripts/plugin/config-bridge.ts

@@ -0,0 +1,31 @@
+// Maps OpenClaw plugin config → process.env vars
+// Only sets vars that are not already defined (env vars take priority)
+
+import type { X402PluginConfig } from './types.js';
+
+const CONFIG_MAP: Record<keyof Omit<X402PluginConfig, 'watcher'>, string> = {
+  evmPrivateKey: 'EVM_PRIVATE_KEY',
+  network: 'X402_NETWORK',
+  maxPaymentUsd: 'X402_MAX_PAYMENT_USD',
+  x402LinksApiUrl: 'X402_LINKS_API_URL',
+};
+
+/**
+ * Inject plugin config values into process.env if not already set.
+ *
+ * Priority chain:
+ * 1. Real env vars (highest — already in process.env)
+ * 2. Plugin config (injected here)
+ * 3. ~/.x402/.env (loaded by core/config.ts with override: false)
+ * 4. Hardcoded defaults in core/config.ts
+ */
+export function applyConfigBridge(pluginConfig: Record<string, unknown>): void {
+  const config = pluginConfig as X402PluginConfig;
+
+  for (const [key, envVar] of Object.entries(CONFIG_MAP)) {
+    const value = config[key as keyof Omit<X402PluginConfig, 'watcher'>];
+    if (value !== undefined && value !== null && !process.env[envVar]) {
+      process.env[envVar] = String(value);
+    }
+  }
+}

package/scripts/plugin/index.ts

@@ -0,0 +1,49 @@
+// OpenClaw Plugin Entry Point for agentic-x402
+
+import type { OpenClawPluginApi, X402PluginConfig } from './types.js';
+import { applyConfigBridge } from './config-bridge.js';
+import { PaymentWatcher } from './watcher.js';
+import { createTools } from './tools.js';
+import { registerCliCommands } from './cli.js';
+
+export default {
+  id: 'agentic-x402',
+  name: 'x402 Payments',
+
+  register(api: OpenClawPluginApi): void {
+    const { logger, config, gatewayPort } = api;
+    const pluginConfig = config as X402PluginConfig;
+
+    // 1. Apply config bridge: inject plugin config → process.env
+    logger.info('Applying x402 config bridge');
+    applyConfigBridge(config);
+
+    // 2. Register background watcher service (unless disabled)
+    let watcher: PaymentWatcher | null = null;
+    const watcherEnabled = pluginConfig.watcher?.enabled !== false;
+
+    if (watcherEnabled) {
+      watcher = new PaymentWatcher({
+        logger,
+        gatewayPort,
+        pollIntervalMs: pluginConfig.watcher?.pollIntervalMs,
+        notifyOnPayment: pluginConfig.watcher?.notifyOnPayment,
+      });
+      api.registerService(watcher);
+      logger.info('Registered x402 payment watcher service');
+    } else {
+      logger.info('x402 payment watcher disabled by config');
+    }
+
+    // 3. Register agent tools
+    const tools = createTools(watcher);
+    for (const tool of tools) {
+      api.registerTool(tool);
+    }
+    logger.info(`Registered ${tools.length} x402 agent tools`);
+
+    // 4. Register CLI commands
+    registerCliCommands(api, watcher, logger);
+    logger.info('Registered x402 CLI commands');
+  },
+};