agentic-x402 0.2.33 → 0.3.1

package/scripts/commands/routers.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env npx tsx
+// List routers where the agent's wallet is a beneficiary
+
+import { getClient, getWalletAddress } from '../core/client.js';
+import { parseArgs, formatCrypto, formatUsd, truncateAddress, formatError } from '../core/utils.js';
+import { getConfig, getUsdcAddress } from '../core/config.js';
+import { formatUnits } from 'viem';
+
+const ERC20_BALANCE_ABI = [{
+  name: 'balanceOf',
+  type: 'function',
+  stateMutability: 'view',
+  inputs: [{ name: 'account', type: 'address' }],
+  outputs: [{ name: '', type: 'uint256' }],
+}] as const;
+
+interface BeneficiaryLink {
+  id: string;
+  router_address: string;
+  metadata: {
+    name: string;
+    description?: string;
+    chainId?: number;
+    chainName?: string;
+  };
+  amount: string;
+  chain_id: number;
+  token_address: string;
+  beneficiary_percentage: number;
+  created_at: string;
+}
+
+async function main() {
+  const { flags } = parseArgs(process.argv.slice(2));
+
+  if (flags.help || flags.h) {
+    console.log(`
+x402 routers - List routers where your wallet is a beneficiary
+
+Usage: x402 routers [options]
+
+Options:
+  --with-balance   Fetch on-chain USDC balance for each router
+  --json           Output as JSON
+  -h, --help       Show this help
+
+Shows:
+  - Router address and link name
+  - Your beneficiary share percentage
+  - On-chain USDC balance (with --with-balance)
+  - Estimated withdrawal amount based on your share
+`);
+    process.exit(0);
+  }
+
+  const config = getConfig();
+  const jsonOutput = flags.json === true;
+  const withBalance = flags['with-balance'] === true;
+
+  try {
+    const address = getWalletAddress();
+    const apiUrl = `${config.x402LinksApiUrl}/api/links/beneficiary/${address}`;
+
+    const response = await fetch(apiUrl);
+    const data = await response.json();
+
+    if (!response.ok || !data.success) {
+      if (jsonOutput) {
+        console.log(JSON.stringify({ success: false, error: data.error || 'Failed to fetch routers' }));
+      } else {
+        console.error('Error:', data.error || 'Failed to fetch routers');
+      }
+      process.exit(1);
+    }
+
+    const links: BeneficiaryLink[] = data.links;
+
+    if (links.length === 0) {
+      if (jsonOutput) {
+        console.log(JSON.stringify({ success: true, routers: [] }));
+      } else {
+        console.log('No routers found where your wallet is a beneficiary.');
+      }
+      return;
+    }
+
+    // Optionally fetch on-chain balances
+    let balances: Map<string, { raw: bigint; formatted: string }> | null = null;
+
+    if (withBalance) {
+      const client = getClient();
+      const usdcAddress = getUsdcAddress(config.chainId);
+      balances = new Map();
+
+      const balancePromises = links.map(async (link) => {
+        const routerAddr = link.router_address as `0x${string}`;
+        try {
+          const balance = await client.publicClient.readContract({
+            address: usdcAddress,
+            abi: ERC20_BALANCE_ABI,
+            functionName: 'balanceOf',
+            args: [routerAddr],
+          });
+          return { router: routerAddr, raw: balance, formatted: formatUnits(balance, 6) };
+        } catch {
+          return { router: routerAddr, raw: 0n, formatted: '0' };
+        }
+      });
+
+      const results = await Promise.all(balancePromises);
+      for (const r of results) {
+        balances.set(r.router.toLowerCase(), { raw: r.raw, formatted: r.formatted });
+      }
+    }
+
+    if (jsonOutput) {
+      const routers = links.map((link) => {
+        const bal = balances?.get(link.router_address.toLowerCase());
+        const share = link.beneficiary_percentage / 100;
+        return {
+          routerAddress: link.router_address,
+          name: link.metadata?.name || 'Unnamed',
+          chainId: link.chain_id,
+          sharePercent: link.beneficiary_percentage,
+          ...(bal ? {
+            balance: bal.formatted,
+            balanceRaw: bal.raw.toString(),
+            estimatedWithdrawal: (parseFloat(bal.formatted) * share).toFixed(6),
+          } : {}),
+          createdAt: link.created_at,
+        };
+      });
+      console.log(JSON.stringify({ success: true, address, routers }));
+      return;
+    }
+
+    // Human-readable output
+    console.log('Your Payment Routers');
+    console.log('====================');
+    console.log('');
+    console.log(`Wallet: ${address}`);
+    console.log(`Found: ${links.length} router(s)`);
+    console.log('');
+
+    for (const link of links) {
+      const name = link.metadata?.name || 'Unnamed';
+      const share = link.beneficiary_percentage;
+
+      console.log(`  ${name}`);
+      console.log(`    Router:  ${link.router_address}`);
+      console.log(`    Share:   ${share}%`);
+
+      if (balances) {
+        const bal = balances.get(link.router_address.toLowerCase());
+        if (bal) {
+          const balNum = parseFloat(bal.formatted);
+          const est = balNum * (share / 100);
+          console.log(`    Balance: ${formatCrypto(bal.formatted, 'USDC', 2)}`);
+          console.log(`    Est. withdrawal: ${formatCrypto(est.toFixed(2), 'USDC', 2)}`);
+        }
+      }
+      console.log('');
+    }
+
+    if (!withBalance) {
+      console.log('Tip: Use --with-balance to see on-chain USDC balances');
+    }
+    console.log('Use "x402 distribute <router-address>" to withdraw funds');
+
+  } 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/plugin/cli.ts

@@ -0,0 +1,94 @@
+// CLI commands for the OpenClaw plugin
+// Registered via api.registerCli with Commander.js-style program
+
+import { getWalletAddress } from '../core/client.js';
+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();
+        const address = getWalletAddress();
+
+        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'}`);
+        console.log(`Wallet address:    ${address}`);
+
+        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
+    applyConfigBridge(config);
+    logger.debug('x402 config bridge applied');
+
+    // 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.debug('x402 payment watcher registered');
+    } else {
+      logger.debug('x402 payment watcher disabled by config');
+    }
+
+    // 3. Register agent tools
+    const tools = createTools(watcher);
+    for (const tool of tools) {
+      api.registerTool(tool);
+    }
+    logger.debug(`Registered ${tools.length} x402 agent tools`);
+
+    // 4. Register CLI commands
+    registerCliCommands(api, watcher, logger);
+    logger.debug('x402 CLI commands registered');
+  },
+};