agentic-x402 0.2.2 → 0.2.4

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-x402",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Agent skill for x402 payments - pay for and sell gated content",
   "type": "module",
   "bin": {

package/scripts/commands/balance.ts

@@ -60,26 +60,22 @@ Shows:
     console.log('x402 Wallet Balance');
     console.log('===================');
     console.log('');
-    console.log(`Address: ${fullAddress ? address : truncateAddress(address)}`);
-    console.log(`Network: ${client.config.network} (chain ${client.config.chainId})`);
+    console.log(`Address: ${address}`);
+    const networkName = client.config.chainId === 8453 ? 'Base mainnet' : 'Base Sepolia';
+    console.log(`Network: ${networkName} (chain ${client.config.chainId})`);
     console.log('');
     console.log('Balances:');
     console.log(`  USDC: ${formatCrypto(usdc.formatted, 'USDC', 2)}`);
     console.log(`  ETH:  ${formatCrypto(eth.formatted, 'ETH', 6)}`);
 
     // Warnings
-    console.log('');
     const usdcNum = parseFloat(usdc.formatted);
-    const ethNum = parseFloat(eth.formatted);
 
     if (usdcNum < 1) {
+      console.log('');
       console.log('Warning: Low USDC balance. Fund your wallet to make payments.');
     }
 
-    if (ethNum < 0.0001) {
-      console.log('Warning: Low ETH balance. You may need ETH for gas fees.');
-    }
-
   } catch (error) {
     if (jsonOutput) {
       console.log(JSON.stringify({

package/scripts/commands/create-link.ts

@@ -56,7 +56,7 @@ Options:
   -h, --help   Show this help
 
 Environment:
-  X402_LINKS_API_URL   Base URL of x402-links-server (required)
+  X402_LINKS_API_URL   Base URL of x402-links-server (default: https://21.cash)
 
 Examples:
   x402 create-link --name "Premium Guide" --price 5.00 --url https://mysite.com/guide.pdf
@@ -68,12 +68,6 @@ Examples:
 
   const config = getConfig();
 
-  if (!config.x402LinksApiUrl) {
-    console.error('Error: X402_LINKS_API_URL environment variable is required');
-    console.error('Set it to the base URL of your x402-links-server instance');
-    process.exit(1);
-  }
-
   const name = flags.name as string;
   const price = flags.price as string;
   const gatedUrl = flags.url as string | undefined;
@@ -129,7 +123,7 @@ Examples:
       console.log(`  Name: ${name}`);
       console.log(`  Price: ${formatUsd(parseFloat(price))}`);
       console.log(`  Creator: ${truncateAddress(creatorAddress)}`);
-      console.log(`  Network: ${config.network} (chain ${config.chainId})`);
+      console.log(`  Network: ${config.chainId === 8453 ? 'Base mainnet' : 'Base Sepolia'} (chain ${config.chainId})`);
       console.log('');
     }
 

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/pay.ts

@@ -50,7 +50,8 @@ Examples:
   console.log(`Fetching: ${url}`);
   console.log(`Method: ${method}`);
   console.log(`Wallet: ${truncateAddress(client.account.address)}`);
-  console.log(`Network: ${client.config.network} (chain ${client.config.chainId})`);
+  const networkName = client.config.chainId === 8453 ? 'Base mainnet' : 'Base Sepolia';
+  console.log(`Network: ${networkName} (chain ${client.config.chainId})`);
   console.log('');
 
   try {

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/core/config.ts

@@ -71,7 +71,7 @@ export function getConfig(): X402Config {
     network,
     chainId,
     facilitatorUrl: getOptionalEnv('X402_FACILITATOR_URL', defaultFacilitator),
-    x402LinksApiUrl: process.env.X402_LINKS_API_URL,
+    x402LinksApiUrl: process.env.X402_LINKS_API_URL || 'https://21.cash',
     maxPaymentUsd: parseFloat(getOptionalEnv('X402_MAX_PAYMENT_USD', '10')),
     slippageBps: parseInt(getOptionalEnv('X402_SLIPPAGE_BPS', '50'), 10),
     verbose: getOptionalEnv('X402_VERBOSE', '0') === '1',