agentic-x402 0.2.33 → 0.3.1

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,11 +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.
+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
-metadata:
-  author: monemetrics
-  version: "0.2.1"
+homepage: https://www.npmjs.com/package/agentic-x402
+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
 ---
 
@@ -23,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
 
@@ -156,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/bin/cli.ts

@@ -52,6 +52,16 @@ const commands: Record<string, Command> = {
     description: 'Get info about a payment link',
     category: 'links',
   },
+  routers: {
+    script: 'commands/routers.ts',
+    description: 'List routers where your wallet is a beneficiary',
+    category: 'links',
+  },
+  distribute: {
+    script: 'commands/distribute.ts',
+    description: 'Distribute USDC from a PaymentRouter',
+    category: 'links',
+  },
 };
 
 function showHelp() {
@@ -73,6 +83,8 @@ Payment Commands:
 Link Commands (21cash integration):
   create-link         Create a payment link to sell content
   link-info <addr>    Get info about a payment link
+  routers             List routers where your wallet is a beneficiary
+  distribute <addr>   Distribute USDC from a PaymentRouter
 
 Options:
   -h, --help          Show this help

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.33",
+  "version": "0.3.1",
   "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/commands/distribute.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env npx tsx
+// Distribute accumulated USDC from a PaymentRouter
+
+import { getClient, getWalletAddress, getEthBalance } from '../core/client.js';
+import { parseArgs, formatCrypto, truncateAddress, formatError } from '../core/utils.js';
+import { getConfig, getUsdcAddress } from '../core/config.js';
+import { formatUnits, parseUnits } from 'viem';
+
+const ERC20_BALANCE_ABI = [{
+  name: 'balanceOf',
+  type: 'function',
+  stateMutability: 'view',
+  inputs: [{ name: 'account', type: 'address' }],
+  outputs: [{ name: '', type: 'uint256' }],
+}] as const;
+
+const PAYMENT_ROUTER_ABI = [{
+  name: 'distribute',
+  type: 'function',
+  stateMutability: 'nonpayable',
+  inputs: [
+    { name: 'token', type: 'address' },
+    { name: 'amount', type: 'uint256' },
+  ],
+  outputs: [],
+}] as const;
+
+const MIN_ETH_FOR_GAS = 0.0001; // Minimum ETH required for gas
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+
+  if (positional.length === 0 || flags.help || flags.h) {
+    console.log(`
+x402 distribute - Distribute USDC from a PaymentRouter
+
+Usage: x402 distribute <router-address> [options]
+
+Arguments:
+  router-address   The PaymentRouter contract address
+
+Options:
+  --amount <amt>   Distribute a specific USDC amount (e.g., "10.00"). Defaults to full balance.
+  --force          Skip gas balance warning
+  --json           Output as JSON
+  -h, --help       Show this help
+
+Examples:
+  x402 distribute 0x1234...5678
+  x402 distribute 0x1234...5678 --amount 5.00
+  x402 distribute 0x1234...5678 --force --json
+`);
+    process.exit(0);
+  }
+
+  const config = getConfig();
+  const jsonOutput = flags.json === true;
+  const force = flags.force === true;
+  const specifiedAmount = flags.amount as string | undefined;
+
+  // Validate router address
+  const routerAddress = positional[0];
+  if (!routerAddress.startsWith('0x') || routerAddress.length !== 42) {
+    const msg = 'Invalid router address. Must be a 0x-prefixed 40-character hex string.';
+    if (jsonOutput) {
+      console.log(JSON.stringify({ success: false, error: msg }));
+    } else {
+      console.error(`Error: ${msg}`);
+    }
+    process.exit(1);
+  }
+
+  try {
+    const client = getClient();
+    const walletAddress = getWalletAddress();
+    const usdcAddress = getUsdcAddress(config.chainId);
+    const routerAddr = routerAddress as `0x${string}`;
+
+    // Read router's USDC balance
+    const routerBalance = await client.publicClient.readContract({
+      address: usdcAddress,
+      abi: ERC20_BALANCE_ABI,
+      functionName: 'balanceOf',
+      args: [routerAddr],
+    });
+
+    const routerBalanceFormatted = formatUnits(routerBalance, 6);
+
+    if (routerBalance === 0n) {
+      if (jsonOutput) {
+        console.log(JSON.stringify({ success: false, error: 'Router has no USDC balance to distribute' }));
+      } else {
+        console.log('Router has no USDC balance to distribute.');
+      }
+      return;
+    }
+
+    // Determine amount to distribute
+    let distributeAmount: bigint;
+    if (specifiedAmount) {
+      distributeAmount = parseUnits(specifiedAmount, 6);
+      if (distributeAmount > routerBalance) {
+        const msg = `Requested amount (${specifiedAmount} USDC) exceeds router balance (${routerBalanceFormatted} USDC)`;
+        if (jsonOutput) {
+          console.log(JSON.stringify({ success: false, error: msg }));
+        } else {
+          console.error(`Error: ${msg}`);
+        }
+        process.exit(1);
+      }
+    } else {
+      distributeAmount = routerBalance;
+    }
+
+    // Check ETH for gas
+    if (!force) {
+      const eth = await getEthBalance();
+      const ethNum = parseFloat(eth.formatted);
+      if (ethNum < MIN_ETH_FOR_GAS) {
+        const msg = `Low ETH balance (${formatCrypto(eth.formatted, 'ETH', 6)}). Need at least ${MIN_ETH_FOR_GAS} ETH for gas. Use --force to skip this check.`;
+        if (jsonOutput) {
+          console.log(JSON.stringify({ success: false, error: msg }));
+        } else {
+          console.error(`Warning: ${msg}`);
+        }
+        process.exit(1);
+      }
+    }
+
+    const distributeFormatted = formatUnits(distributeAmount, 6);
+
+    if (!jsonOutput) {
+      console.log('Distributing USDC from PaymentRouter');
+      console.log('====================================');
+      console.log('');
+      console.log(`Router:  ${routerAddress}`);
+      console.log(`Balance: ${formatCrypto(routerBalanceFormatted, 'USDC', 2)}`);
+      console.log(`Amount:  ${formatCrypto(distributeFormatted, 'USDC', 2)}`);
+      console.log(`Caller:  ${truncateAddress(walletAddress)}`);
+      console.log('');
+      console.log('Submitting transaction...');
+    }
+
+    // Call distribute(token, amount)
+    const txHash = await client.walletClient.writeContract({
+      address: routerAddr,
+      abi: PAYMENT_ROUTER_ABI,
+      functionName: 'distribute',
+      args: [usdcAddress, distributeAmount],
+    });
+
+    if (!jsonOutput) {
+      console.log(`TX submitted: ${txHash}`);
+      console.log('Waiting for confirmation...');
+    }
+
+    // Wait for receipt
+    const receipt = await client.publicClient.waitForTransactionReceipt({ hash: txHash });
+
+    const success = receipt.status === 'success';
+
+    if (jsonOutput) {
+      console.log(JSON.stringify({
+        success,
+        routerAddress,
+        amount: distributeFormatted,
+        amountRaw: distributeAmount.toString(),
+        transactionHash: txHash,
+        blockNumber: receipt.blockNumber.toString(),
+        status: receipt.status,
+      }));
+      return;
+    }
+
+    if (success) {
+      console.log('');
+      console.log('Distribution successful!');
+      console.log(`TX: ${txHash}`);
+      console.log(`Block: ${receipt.blockNumber}`);
+      console.log(`Distributed: ${formatCrypto(distributeFormatted, 'USDC', 2)}`);
+    } else {
+      console.error('');
+      console.error('Transaction reverted.');
+      console.error(`TX: ${txHash}`);
+      process.exit(1);
+    }
+
+  } catch (error) {
+    if (jsonOutput) {
+      console.log(JSON.stringify({ success: false, error: formatError(error) }));
+    } else {
+      console.error('Error:', formatError(error));
+    }
+    process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/scripts/commands/fetch-paid.ts

@@ -54,7 +54,9 @@ Examples:
   }
 
   try {
-    const headers: Record<string, string> = {};
+    const headers: Record<string, string> = {
+      'Accept': 'application/json',
+    };
 
     if (body) {
       headers['Content-Type'] = 'application/json';

package/scripts/commands/pay.ts

@@ -59,7 +59,10 @@ Examples:
     const initialResponse = await fetch(url, {
       method,
       body: body ? body : undefined,
-      headers: body ? { 'Content-Type': 'application/json' } : undefined,
+      headers: {
+        'Accept': 'application/json',
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+      },
     });
 
     if (initialResponse.status !== 402) {
@@ -143,7 +146,10 @@ Examples:
     const response = await client.fetchWithPayment(url, {
       method,
       body: body ? body : undefined,
-      headers: body ? { 'Content-Type': 'application/json' } : undefined,
+      headers: {
+        'Accept': 'application/json',
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+      },
     });
 
     if (!response.ok) {