@paynodelabs/paynode-402-cli 2.5.0

package/README.md

@@ -0,0 +1,73 @@
+# ⚡ paynode-402-cli
+
+[![Base L2](https://img.shields.io/badge/Network-Base%20L2-0052FF?style=for-the-badge&logo=base)](https://base.org)
+[![HTTP 402](https://img.shields.io/badge/Protocol-x402-00ff88?style=for-the-badge)](https://paynode.dev)
+
+The official command-line interface for the [PayNode](https://github.com/PayNodeLabs) protocol. Designed specifically for the **Agentic Era**, allowing AI Agents to execute zero-install, stateless micro-payments via the HTTP 402 standard.
+
+---
+
+## 🛠️ Configuration & Credentials
+
+To enable automated blockchain signing, this tool requires a private key provided via environment variables.
+
+> [!IMPORTANT]
+> **Mandatory Variable**: `CLIENT_PRIVATE_KEY` (0x...)
+> All signature and payment operations rely on this key. Ensure it is set in your environment before execution.
+
+> [!CAUTION]
+> **BURNER WALLET ONLY**: NEVER use a primary or "cold storage" wallet. This tool is designed for autonomous agents; always use a dedicated burner wallet with minimal funds (< 10 USDC).
+
+### Setup Example (Unix)
+```bash
+export CLIENT_PRIVATE_KEY="0x..."
+bunx @paynodelabs/paynode-402-cli check
+```
+
+---
+
+## 🤖 For AI Agents (Zero-Install)
+
+Your agent can use this tool dynamically via `bunx` without any manual installation:
+
+### 1. Check Readiness (Gas & USDC)
+```bash
+bunx @paynodelabs/paynode-402-cli check --network testnet --json
+```
+
+### 2. Access a 402-Protected API
+The CLI automatically detects the 402 challenge, performs the handshake, signs the payment (on-chain or EIP-3009), and returns the final resource.
+```bash
+bunx @paynodelabs/paynode-402-cli request "https://api.example.com/data" --network testnet --json
+```
+
+### 3. Mint Test USDC (Base Sepolia)
+```bash
+bunx @paynodelabs/paynode-402-cli mint --amount 100 --network testnet
+```
+
+---
+
+## 📑 Command Summary
+
+| Command | Description |
+| :--- | :--- |
+| `check` | Check ETH/USDC balances and readiness on Base L2 |
+| `mint` | Mint Mock USDC on Base Sepolia for testing |
+| `request <URL>` | Access a protected resource by handling the 402 challenge |
+| `list-paid-apis` | Discover payable APIs from the PayNode Marketplace |
+| `get-api-detail <id>` | Inspect one marketplace API |
+| `invoke-paid-api <id>` | Invoke a marketplace API using the 402 flow |
+
+### Global Flags
+- `--network <name>`: `mainnet` or `testnet` (default: `testnet`).
+- `--json`: Format output as machine-readable JSON (preferred for Agents).
+- `--confirm-mainnet`: Explicit flag required for real USDC transactions on mainnet.
+- `--background`: Execute in background and return a `task_id` for long-running handshakes.
+
+---
+
+## 🔗 References
+- **Marketplace**: [https://mk.paynode.dev](https://mk.paynode.dev)
+- **Protocol SPEC**: [PayNode Docs](https://docs.paynode.dev)
+- **GitHub**: [PayNodeLabs/paynode-402-cli](https://github.com/PayNodeLabs/paynode-402-cli)

package/commands/check.ts

@@ -0,0 +1,126 @@
+import { ethers } from '@paynodelabs/sdk-js';
+import {
+    getPrivateKey,
+    resolveNetwork,
+    requireMainnetConfirmation,
+    reportError,
+    jsonEnvelope,
+    withRetry,
+    EXIT_CODES,
+    BaseCliOptions
+} from '../utils.ts';
+
+interface CheckOptions extends BaseCliOptions {
+}
+
+// Minimum gas threshold: 0.001 ETH (in wei)
+const MIN_GAS_WEI = ethers.parseEther('0.001');
+
+export async function checkAction(options: CheckOptions) {
+    const isJson = !!options.json;
+    const pk = getPrivateKey(isJson);
+
+    try {
+        const { provider, usdcAddress, chainId, networkName, isSandbox } = await resolveNetwork(
+            options.rpc,
+            options.network,
+            options.rpcTimeout
+        );
+
+        // Mainnet safety gate
+        requireMainnetConfirmation(isSandbox, !!options.confirmMainnet, isJson);
+
+        const wallet = new ethers.Wallet(pk, provider);
+        const address = wallet.address;
+
+        // Fetch balances with retry
+        const [ethBalance, usdcBalance] = await withRetry(
+            () => Promise.all([
+                provider.getBalance(address),
+                new ethers.Contract(
+                    usdcAddress,
+                    ['function balanceOf(address) view returns (uint256)'],
+                    provider
+                ).balanceOf(address)
+            ]),
+            'balanceCheck'
+        );
+
+        // BigInt comparisons are used for logic (no precision loss).
+        // parseFloat is only for human-readable display and non-critical JSON values.
+        const ethValue = parseFloat(ethers.formatEther(ethBalance));
+        const usdcValue = parseFloat(ethers.formatUnits(usdcBalance, 6));
+        const isGasReady = ethBalance >= MIN_GAS_WEI;
+        const isTokensReady = usdcBalance > 0n;
+
+        if (isJson) {
+            console.log(
+                jsonEnvelope({
+                    status: 'success',
+                    address,
+                    eth: ethValue,
+                    usdc: usdcValue,
+                    network: networkName,
+                    chainId,
+                    is_sandbox: isSandbox,
+                    checks: {
+                        gas_ready: isGasReady,
+                        tokens_ready: isTokensReady,
+                        can_pay: isGasReady && isTokensReady
+                    }
+                })
+            );
+        } else {
+            console.log(`\n💎 **PayNode Wallet Status**`);
+            console.log(`──────────────────────────────────────────────────`);
+            console.log(`👤 **Address**:   \`${address}\``);
+            console.log(`🌐 **Network**:   ${networkName}`);
+            console.log(`──────────────────────────────────────────────────`);
+            console.log(`⛽ **ETH (Gas)**:  ${ethValue.toFixed(6)} ETH  ${isGasReady ? '✅ Ready' : '⚠️ Low balance'}`);
+            console.log(`💵 **USDC**:       ${usdcValue.toFixed(2)} USDC  ${isTokensReady ? '✅ Ready' : '❌ Empty'}`);
+            console.log(`──────────────────────────────────────────────────`);
+
+            if (isGasReady && isTokensReady) {
+                console.log(`🚀 **Status**: Ready to handle x402 autonomous payments.`);
+            } else {
+                console.log(`❌ **Status**: Action required. See tips below.`);
+            }
+
+            // Safety Warning for Burner Wallets (Mainnet Only)
+            if (!isSandbox && usdcValue > 10) {
+                console.warn(
+                    `\n> [!CAUTION]\n> High balance detected ($${usdcValue.toFixed(2)} USDC). This is a burner wallet. \n> Consider sweeping excess funds to cold storage to minimize risk.`
+                );
+            }
+
+            if (!isGasReady) {
+                if (isSandbox) {
+                    console.warn(
+                        `\n> [!WARNING]\n> Gas balance is critically low (< 0.001 ETH). Please deposit ETH to \`${address}\` on ${networkName}.`
+                    );
+                    console.warn(
+                        `> **Faucet**: [console.optimism.io/faucet](https://console.optimism.io/faucet) (Recommended)`
+                    );
+                } else {
+                    console.warn(
+                        `\n> [!WARNING]\n> Gas balance is critically low (< 0.001 ETH). Please deposit ETH to \`${address}\` on ${networkName}.`
+                    );
+                }
+            }
+            if (!isTokensReady) {
+                if (isSandbox) {
+                    console.warn(
+                        `\n> [!TIP]\n> You're on Testnet! Run \`bun run paynode-402 mint --network testnet\` to get 1,000 free Test USDC.`
+                    );
+                } else {
+                    console.warn(
+                        `\n> [!NOTE]\n> Mainnet USDC balance is 0. This wallet is currently restricted to free trials.`
+                    );
+                }
+            }
+            console.log(``);
+        }
+    } catch (error: any) {
+        reportError(error, isJson, EXIT_CODES.NETWORK_ERROR);
+    }
+}

package/commands/get-api-detail.ts

@@ -0,0 +1,30 @@
+import { MarketplaceClient } from '../marketplace/client.ts';
+import { jsonEnvelope, reportError, EXIT_CODES, BaseCliOptions } from '../utils.ts';
+
+interface GetApiDetailOptions extends BaseCliOptions {
+}
+
+export async function getApiDetailAction(apiId: string, options: GetApiDetailOptions) {
+  const isJson = !!options.json;
+
+  try {
+    const client = new MarketplaceClient({
+      baseUrl: options.marketUrl,
+      json: isJson
+    });
+
+    const detail = await client.getApiDetail(apiId, options.network);
+
+    if (isJson) {
+      console.log(jsonEnvelope({
+        status: 'success',
+        api: detail
+      }));
+      return;
+    }
+
+    console.log(JSON.stringify(detail, null, 2));
+  } catch (error: any) {
+    reportError(error, isJson, EXIT_CODES.NETWORK_ERROR);
+  }
+}

package/commands/invoke-paid-api.ts

@@ -0,0 +1,91 @@
+import { requestAction } from './request.ts';
+import { MarketplaceClient } from '../marketplace/client.ts';
+import { reportError, EXIT_CODES, BaseCliOptions } from '../utils.ts';
+
+interface InvokePaidApiOptions extends BaseCliOptions {
+  method?: string;
+  data?: string;
+  header?: string | string[];
+  background?: boolean;
+  output?: string;
+  maxAge?: number;
+  taskDir?: string;
+  taskId?: string;
+}
+
+function mergeHeaders(
+  marketplaceHeaders: Record<string, string> | undefined,
+  cliHeader: string | string[] | undefined
+): string[] {
+  const merged: string[] = [];
+
+  for (const [key, value] of Object.entries(marketplaceHeaders || {})) {
+    merged.push(`${key}: ${value}`);
+  }
+
+  if (Array.isArray(cliHeader)) {
+    merged.push(...cliHeader);
+  } else if (cliHeader) {
+    merged.push(cliHeader);
+  }
+
+  return merged;
+}
+
+function parsePayload(data?: string): any {
+  if (!data) return undefined;
+
+  try {
+    return JSON.parse(data);
+  } catch (err: any) {
+    const isJsonLike = data.trim().startsWith('{') || data.trim().startsWith('[');
+    if (isJsonLike) {
+      console.warn(`⚠️ [Warning] Invocation data looks like JSON but failed to parse: ${err.message}`);
+      console.warn(`Sending as raw string instead. Please verify your JSON syntax.`);
+    } else {
+      console.warn(`⚠️ [Warning] Invocation data is not valid JSON. Sending as raw string.`);
+    }
+    return data;
+  }
+}
+
+export async function invokePaidApiAction(apiId: string, options: InvokePaidApiOptions) {
+    const isJson = !!options.json;
+
+  try {
+    const client = new MarketplaceClient({
+      baseUrl: options.marketUrl,
+      json: isJson
+    });
+
+    const invoke = await client.prepareInvoke(apiId, {
+      network: options.network,
+      payload: parsePayload(options.data)
+    });
+
+    const requestHeaders = mergeHeaders(invoke.headers, options.header);
+    const hasPreparedBody = !!(invoke.body && typeof invoke.body === 'object' && Object.keys(invoke.body).length > 0);
+    const requestBody = hasPreparedBody 
+      ? JSON.stringify(invoke.body) 
+      : (options.data || undefined); // Use undefined if no data to trigger smart promotion if needed
+
+    await requestAction(invoke.invoke_url, [], {
+      json: options.json,
+      network: options.network || invoke.network, // Delegate fallback to resolveNetwork
+      rpc: options.rpc,
+      rpcTimeout: options.rpcTimeout,
+      confirmMainnet: options.confirmMainnet,
+      method: options.method || invoke.method || 'POST',
+      data: requestBody,
+      header: requestHeaders,
+      background: options.background,
+      dryRun: options.dryRun,
+      output: options.output,
+      maxAge: options.maxAge,
+      taskDir: options.taskDir,
+      taskId: options.taskId
+    });
+  } catch (error: any) {
+    reportError(error, isJson, EXIT_CODES.NETWORK_ERROR);
+  }
+}

package/commands/list-paid-apis.ts

@@ -0,0 +1,58 @@
+import { MarketplaceClient } from '../marketplace/client.ts';
+import { jsonEnvelope, reportError, EXIT_CODES, BaseCliOptions } from '../utils.ts';
+
+interface ListPaidApisOptions extends BaseCliOptions {
+  limit?: string | number;
+  tag?: string | string[];
+  seller?: string;
+}
+
+export async function listPaidApisAction(options: ListPaidApisOptions) {
+  const isJson = !!options.json;
+
+  try {
+    const client = new MarketplaceClient({
+      baseUrl: options.marketUrl,
+      json: isJson
+    });
+
+    const tags = Array.isArray(options.tag)
+      ? options.tag
+      : options.tag
+        ? [options.tag]
+        : [];
+
+    const result = await client.listCatalog({
+      network: options.network,
+      limit: options.limit ? Number(options.limit) : undefined,
+      tag: tags,
+      seller: options.seller
+    });
+
+    if (isJson) {
+      console.log(jsonEnvelope({
+        status: 'success',
+        total: result.total || result.items.length,
+        items: result.items
+      }));
+      return;
+    }
+
+    if (result.items.length === 0) {
+      console.log('No paid APIs found.');
+      return;
+    }
+
+    for (const item of result.items) {
+      const price = item.price_per_call ? `${item.price_per_call} ${item.currency || 'USDC'}` : 'unpriced';
+      const network = item.network || 'unspecified';
+      const tagsLine = item.tags && item.tags.length > 0 ? ` [${item.tags.join(', ')}]` : '';
+      console.log(`- ${item.id}: ${item.name} | ${price} | ${network}${tagsLine}`);
+      if (item.description) {
+        console.log(`  ${item.description}`);
+      }
+    }
+  } catch (error: any) {
+    reportError(error, isJson, EXIT_CODES.NETWORK_ERROR);
+  }
+}

package/commands/mint.ts

@@ -0,0 +1,97 @@
+import { ethers } from '@paynodelabs/sdk-js';
+import {
+    getPrivateKey,
+    resolveNetwork,
+    reportError,
+    jsonEnvelope,
+    withRetry,
+    EXIT_CODES,
+    BaseCliOptions
+} from '../utils.ts';
+
+interface MintOptions extends BaseCliOptions {
+    amount?: string;
+}
+
+export async function mintAction(options: MintOptions) {
+    const isJson = !!options.json;
+    const pk = getPrivateKey(isJson);
+
+    try {
+        const { provider, usdcAddress, chainId, networkName, isSandbox } = await resolveNetwork(
+            options.rpc,
+            options.network || 'testnet',
+            options.rpcTimeout
+        );
+
+        if (!isSandbox) {
+            throw new Error(`Minting is only supported on Sepolia. Current ChainID: ${chainId}`);
+        }
+
+        const wallet = new ethers.Wallet(pk, provider);
+        const mintAmountStr = String(options.amount || '1000');
+
+        // Gas check
+        const balance = await provider.getBalance(wallet.address);
+        if (balance === 0n) {
+            reportError(
+                `Gas balance is 0 ETH on ${networkName}. Please fund \`${wallet.address}\` to continue.\n` +
+                `💡 **Faucet**: [console.optimism.io/faucet](https://console.optimism.io/faucet) — 0.01 ETH daily (Recommended)`,
+                isJson,
+                EXIT_CODES.INSUFFICIENT_FUNDS
+            );
+        }
+
+        // Progress messages are sent to stderr to avoid polluting stdout 
+        // when valid JSON output is expected by the caller (e.g. via --json)
+        if (!isJson) {
+            console.error(`💰 Connecting to ${networkName}...`);
+            console.error(`🔗 Minting ${mintAmountStr} USDC for address: ${wallet.address}`);
+        }
+
+        const abi = ['function mint(address to, uint256 amount) external'];
+        const usdc = new ethers.Contract(usdcAddress, abi, wallet);
+
+        const amount = ethers.parseUnits(mintAmountStr, 6);
+
+        if (!isJson) console.error('⏳ Sending mint transaction...');
+        const tx = await withRetry(
+            () => usdc.mint(wallet.address, amount),
+            'mint'
+        );
+
+        if (!isJson) console.error('⏳ Waiting for confirmation...');
+        const receipt: any = await withRetry(
+            () => tx.wait(),
+            'mintConfirm'
+        );
+
+        if (!receipt || receipt.status !== 1) {
+            throw new Error('Transaction reverted or failed.');
+        }
+
+        if (isJson) {
+            console.log(
+                jsonEnvelope({
+                    status: 'success',
+                    txHash: tx.hash,
+                    address: wallet.address,
+                    amount: mintAmountStr,
+                    token: 'MockUSDC',
+                    network: networkName
+                })
+            );
+        } else {
+            console.log(`\n✅ **Success!**`);
+            console.log(`──────────────────────────────────────────────────`);
+            console.log(`💰 **Minted**:      ${mintAmountStr} Test USDC`);
+            console.log(`🌐 **Network**:     ${networkName}`);
+            console.log(`🔗 **Tx Hash**:     \`${tx.hash}\``);
+            console.log(`──────────────────────────────────────────────────`);
+            console.log(`🚀 **Your wallet (\`${wallet.address}\`) is now funded and ready for testing.**`);
+            console.log(``);
+        }
+    } catch (error: any) {
+        reportError(error, isJson, EXIT_CODES.NETWORK_ERROR);
+    }
+}