@vainplex/shieldapi-cli 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Albert Hild
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# 🛡️ ShieldAPI CLI
+
+**Security intelligence from your terminal. Pay-per-request with USDC.**
+
+The first x402-powered security CLI. Check passwords, emails, domains, IPs, and URLs against breach databases, blacklists, and threat intelligence — no API keys, no subscriptions, just crypto micropayments.
+
+## Install
+
+```bash
+npm install -g @vainplex/shieldapi-cli
+```
+
+Or use directly with npx:
+```bash
+npx @vainplex/shieldapi-cli password "test123" --demo
+```
+
+## Quick Start
+
+### Demo Mode (free, no wallet needed)
+
+```bash
+# Check if a password has been breached
+shieldapi password "hunter2" --demo
+
+# Check email for breaches
+shieldapi email "test@example.com" --demo
+
+# Check domain reputation
+shieldapi domain "example.com" --demo
+
+# Check IP reputation
+shieldapi ip "8.8.8.8" --demo
+
+# Check URL safety
+shieldapi url "https://suspicious-site.com" --demo
+
+# Full security scan
+shieldapi scan --email "test@example.com" --domain "example.com" --demo
+
+# Compute SHA-1 hash locally (offline, free)
+shieldapi hash "mypassword"
+```
+
+### Paid Mode (real data, USDC on Base)
+
+```bash
+# Set your wallet key
+export SHIELDAPI_WALLET_KEY="0x..."
+
+# Real breach check — costs $0.001 USDC
+shieldapi password "hunter2"
+
+# Or pass wallet inline
+shieldapi email "ceo@company.com" --wallet "0x..."
+```
+
+## Commands
+
+| Command | Description | Cost (USDC) |
+|---------|-------------|-------------|
+| `password <pw>` | Check password against 900M+ breach records | $0.001 |
+| `email <addr>` | Email breach lookup with risk scoring | $0.005 |
+| `domain <name>` | DNS, blacklists, SSL, SPF/DMARC analysis | $0.003 |
+| `ip <addr>` | Blacklists, Tor exit node, reverse DNS | $0.002 |
+| `url <url>` | Phishing, malware, brand impersonation | $0.003 |
+| `scan` | Full scan (combine any targets) | $0.01 |
+| `health` | API status and pricing | Free |
+| `hash <pw>` | SHA-1 hash (offline, no API call) | Free |
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--wallet <key>` | Private key for x402 payments |
+| `--demo` | Use demo mode (free, fake data) |
+| `--json` | Output raw JSON (for CI/CD and agents) |
+| `--yes, -y` | Skip payment confirmation prompts |
+| `--quiet, -q` | Suppress spinners and warnings |
+| `--no-color` | Disable ANSI colors |
+| `--version, -V` | Show version |
+| `--help, -h` | Show help |
+
+### Password-specific Options
+
+| Flag | Description |
+|------|-------------|
+| `--stdin` | Read password from stdin (avoids shell history) |
+| `--hash` | Treat input as pre-computed SHA-1 hash |
+
+## Exit Codes
+
+Designed for CI/CD pipelines and AI agents:
+
+| Code | Meaning |
+|------|---------|
+| `0` | Safe — no risk found |
+| `1` | Risk — breaches, threats, or high risk detected |
+| `2` | Usage error — invalid arguments |
+| `3` | Network error — API unreachable |
+| `4` | Payment error — insufficient USDC or wallet issue |
+
+```bash
+# Use in CI/CD
+shieldapi password "$DB_PASSWORD" --json --quiet --yes
+if [ $? -eq 1 ]; then
+  echo "COMPROMISED PASSWORD DETECTED"
+  exit 1
+fi
+```
+
+## Security
+
+- **Passwords are hashed locally** with SHA-1 before any network request. Plaintext never leaves your machine.
+- **Private keys are never persisted** to disk, logs, or displayed in output.
+- **No telemetry** — zero phone-home, zero analytics.
+- **Shell history warning** — the CLI warns when passwords are passed as arguments (use `--stdin` for sensitive passwords).
+
+```bash
+# Secure password checking (avoids shell history)
+echo "mysecretpassword" | shieldapi password dummy --stdin
+```
+
+## How x402 Works
+
+[x402](https://x402.org) is an open protocol for HTTP payments. Instead of API keys:
+
+1. You make a request → server returns `HTTP 402` with payment requirements
+2. Your wallet signs a USDC payment authorization
+3. Request is retried with payment proof in headers
+4. Server verifies payment and returns data
+
+All of this happens automatically. You just need a wallet with USDC on Base.
+
+## For AI Agents
+
+ShieldAPI CLI is designed for autonomous agent usage:
+
+```bash
+# JSON output for structured parsing
+shieldapi password "test" --demo --json
+
+# Quiet mode suppresses all stderr
+shieldapi domain "example.com" --demo --json --quiet
+
+# Exit codes for decision making
+shieldapi ip "1.2.3.4" --demo --quiet
+echo $?  # 0 = safe, 1 = risk
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SHIELDAPI_WALLET_KEY` | Private key (hex, with or without 0x prefix) |
+| `NO_COLOR` | Disable colors (standard) |
+
+## Links
+
+- **API**: https://shield.vainplex.dev
+- **x402 Protocol**: https://x402.org
+- **GitHub**: https://github.com/vainplex/shieldapi-cli
+
+## License
+
+MIT © Albert Hild

package/bin/shieldapi.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/index.js';
+
+run(process.argv);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@vainplex/shieldapi-cli",
+  "version": "1.1.0",
+  "description": "Security intelligence from your terminal. Pay-per-request with USDC.",
+  "type": "module",
+  "bin": {
+    "shieldapi": "./bin/shieldapi.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "security",
+    "breach",
+    "password",
+    "hibp",
+    "x402",
+    "usdc",
+    "crypto",
+    "cli"
+  ],
+  "author": "Albert Hild",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vainplex/shieldapi-cli.git"
+  },
+  "homepage": "https://shield.vainplex.dev",
+  "dependencies": {
+    "@x402/evm": "^2.5.0",
+    "@x402/fetch": "^2.5.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "ora": "^8.1.0",
+    "viem": "^2.21.0"
+  }
+}

package/src/commands/domain.js

@@ -0,0 +1,35 @@
+import ora from 'ora';
+import chalk from 'chalk';
+import { apiRequest } from '../lib/api.js';
+import { resolveWallet } from '../lib/wallet.js';
+import { formatDomain } from '../lib/formatter.js';
+import { exitCodeFromResult, exitCodeFromError } from '../lib/exit.js';
+
+/**
+ * Check domain reputation.
+ */
+export async function domainCommand(domain, opts) {
+  const spinner = opts.quiet ? null : ora({ text: `Checking domain: ${domain}`, stream: process.stderr }).start();
+
+  try {
+    const wallet = opts.demo ? null : resolveWallet(opts);
+
+    const data = await apiRequest('check-domain', { domain }, {
+      demo: opts.demo,
+      wallet,
+    });
+
+    spinner?.stop();
+
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      formatDomain(data);
+    }
+
+    process.exitCode = exitCodeFromResult(data);
+  } catch (err) {
+    spinner?.fail(err.message);
+    process.exitCode = exitCodeFromError(err);
+  }
+}

package/src/commands/email.js

@@ -0,0 +1,35 @@
+import ora from 'ora';
+import chalk from 'chalk';
+import { apiRequest } from '../lib/api.js';
+import { resolveWallet } from '../lib/wallet.js';
+import { formatEmail } from '../lib/formatter.js';
+import { exitCodeFromResult, exitCodeFromError } from '../lib/exit.js';
+
+/**
+ * Check an email address for breaches.
+ */
+export async function emailCommand(email, opts) {
+  const spinner = opts.quiet ? null : ora({ text: `Checking email: ${email}`, stream: process.stderr }).start();
+
+  try {
+    const wallet = opts.demo ? null : resolveWallet(opts);
+
+    const data = await apiRequest('check-email', { email }, {
+      demo: opts.demo,
+      wallet,
+    });
+
+    spinner?.stop();
+
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      formatEmail(data, email);
+    }
+
+    process.exitCode = exitCodeFromResult(data);
+  } catch (err) {
+    spinner?.fail(err.message);
+    process.exitCode = exitCodeFromError(err);
+  }
+}

package/src/commands/hash.js

@@ -0,0 +1,19 @@
+import { createHash } from 'node:crypto';
+import chalk from 'chalk';
+
+/**
+ * Compute SHA-1 hash locally (offline, no API call).
+ */
+export async function hashCommand(password, opts) {
+  const hash = createHash('sha1').update(password).digest('hex').toUpperCase();
+
+  if (opts.json) {
+    console.log(JSON.stringify({ password_length: password.length, sha1: hash, prefix: hash.slice(0, 5) }));
+  } else {
+    console.log();
+    console.log(`   SHA-1:  ${chalk.bold(hash)}`);
+    console.log(`   Prefix: ${chalk.cyan(hash.slice(0, 5))}`);
+    console.log(`   Length: ${password.length} characters`);
+    console.log();
+  }
+}

package/src/commands/health.js

@@ -0,0 +1,29 @@
+import ora from 'ora';
+import chalk from 'chalk';
+import { apiRequest } from '../lib/api.js';
+import { formatHealth } from '../lib/formatter.js';
+import { EXIT } from '../lib/exit.js';
+
+/**
+ * Check API health status.
+ */
+export async function healthCommand(opts) {
+  const spinner = opts.quiet ? null : ora({ text: 'Checking API health...', stream: process.stderr }).start();
+
+  try {
+    const data = await apiRequest('health', {}, { demo: opts.demo });
+
+    spinner?.stop();
+
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      formatHealth(data);
+    }
+
+    process.exitCode = EXIT.SAFE;
+  } catch (err) {
+    spinner?.fail(err.message);
+    process.exitCode = EXIT.NETWORK;
+  }
+}

package/src/commands/ip.js

@@ -0,0 +1,35 @@
+import ora from 'ora';
+import chalk from 'chalk';
+import { apiRequest } from '../lib/api.js';
+import { resolveWallet } from '../lib/wallet.js';
+import { formatIp } from '../lib/formatter.js';
+import { exitCodeFromResult, exitCodeFromError } from '../lib/exit.js';
+
+/**
+ * Check IP reputation.
+ */
+export async function ipCommand(ip, opts) {
+  const spinner = opts.quiet ? null : ora({ text: `Checking IP: ${ip}`, stream: process.stderr }).start();
+
+  try {
+    const wallet = opts.demo ? null : resolveWallet(opts);
+
+    const data = await apiRequest('check-ip', { ip }, {
+      demo: opts.demo,
+      wallet,
+    });
+
+    spinner?.stop();
+
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      formatIp(data);
+    }
+
+    process.exitCode = exitCodeFromResult(data);
+  } catch (err) {
+    spinner?.fail(err.message);
+    process.exitCode = exitCodeFromError(err);
+  }
+}

package/src/commands/password.js

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { createInterface } from 'node:readline';
+import ora from 'ora';
+import chalk from 'chalk';
+import { apiRequest } from '../lib/api.js';
+import { resolveWallet } from '../lib/wallet.js';
+import { formatPassword } from '../lib/formatter.js';
+import { exitCodeFromResult, exitCodeFromError, EXIT } from '../lib/exit.js';
+
+/**
+ * Read a line from stdin (for --stdin mode).
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    const rl = createInterface({ input: process.stdin });
+    rl.on('line', (line) => { data = line; rl.close(); });
+    rl.on('close', () => resolve(data.trim()));
+    rl.on('error', reject);
+    // Timeout after 10s
+    setTimeout(() => { rl.close(); reject(new Error('Stdin timeout — no input received')); }, 10000);
+  });
+}
+
+/**
+ * Check a password against breach databases.
+ * Hashes locally with SHA-1, sends hash to API.
+ */
+export async function passwordCommand(password, opts) {
+  try {
+    let hash;
+
+    // --stdin: read password from stdin
+    if (opts.stdin) {
+      if (!opts.quiet) {
+        process.stderr.write(chalk.gray('Reading password from stdin...\n'));
+      }
+      const stdinPassword = await readStdin();
+      if (!stdinPassword) {
+        process.stderr.write(chalk.red('Error: No password received from stdin.\n'));
+        process.exitCode = EXIT.USAGE;
+        return;
+      }
+      hash = createHash('sha1').update(stdinPassword).digest('hex').toUpperCase();
+    } else if (opts.hash) {
+      // --hash: treat input as pre-computed SHA-1
+      hash = password.toUpperCase();
+      if (!/^[A-F0-9]{40}$/.test(hash)) {
+        process.stderr.write(chalk.red('Error: Invalid SHA-1 hash. Must be 40 hex characters.\n'));
+        process.exitCode = EXIT.USAGE;
+        return;
+      }
+    } else {
+      // Normal mode: hash the password locally
+      hash = createHash('sha1').update(password).digest('hex').toUpperCase();
+
+      // Shell history warning (SR-5)
+      if (!opts.quiet && process.stdout.isTTY) {
+        process.stderr.write(
+          chalk.yellow('⚠  Password may appear in shell history. Use --stdin for sensitive passwords.\n')
+        );
+      }
+    }
+
+    const spinner = opts.quiet ? null : ora({ text: 'Checking password...', stream: process.stderr }).start();
+    const wallet = opts.demo ? null : resolveWallet(opts);
+
+    const data = await apiRequest('check-password', { hash }, {
+      demo: opts.demo,
+      wallet,
+    });
+
+    spinner?.stop();
+
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      formatPassword(data, hash);
+    }
+
+    process.exitCode = exitCodeFromResult(data);
+  } catch (err) {
+    if (!opts.quiet) process.stderr.write(chalk.red(`✖ ${err.message}\n`));
+    process.exitCode = exitCodeFromError(err);
+  }
+}

package/src/commands/scan.js

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto';
+import ora from 'ora';
+import chalk from 'chalk';
+import { apiRequest } from '../lib/api.js';
+import { resolveWallet } from '../lib/wallet.js';
+import { formatScan } from '../lib/formatter.js';
+import { exitCodeFromResult, exitCodeFromError, EXIT } from '../lib/exit.js';
+
+/**
+ * Run a full security scan with multiple targets.
+ */
+export async function scanCommand(opts) {
+  const params = {};
+
+  if (opts.password) {
+    params.password_hash = createHash('sha1').update(opts.password).digest('hex').toUpperCase();
+  }
+  if (opts.email) params.email = opts.email;
+  if (opts.domain) params.domain = opts.domain;
+  if (opts.ip) params.ip = opts.ip;
+  if (opts.url) params.url = opts.url;
+
+  if (Object.keys(params).length === 0) {
+    process.stderr.write(chalk.red('Error: At least one target required. Use --email, --password, --domain, --ip, or --url.\n'));
+    process.exitCode = EXIT.USAGE;
+    return;
+  }
+
+  const spinner = opts.quiet ? null : ora({ text: 'Running full security scan...', stream: process.stderr }).start();
+
+  try {
+    const wallet = opts.demo ? null : resolveWallet(opts);
+
+    const data = await apiRequest('full-scan', params, {
+      demo: opts.demo,
+      wallet,
+    });
+
+    spinner?.stop();
+
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      formatScan(data);
+    }
+
+    process.exitCode = exitCodeFromResult(data);
+  } catch (err) {
+    spinner?.fail(err.message);
+    process.exitCode = exitCodeFromError(err);
+  }
+}

package/src/commands/url.js

@@ -0,0 +1,35 @@
+import ora from 'ora';
+import chalk from 'chalk';
+import { apiRequest } from '../lib/api.js';
+import { resolveWallet } from '../lib/wallet.js';
+import { formatUrl } from '../lib/formatter.js';
+import { exitCodeFromResult, exitCodeFromError } from '../lib/exit.js';
+
+/**
+ * Check URL safety.
+ */
+export async function urlCommand(url, opts) {
+  const spinner = opts.quiet ? null : ora({ text: `Checking URL: ${url}`, stream: process.stderr }).start();
+
+  try {
+    const wallet = opts.demo ? null : resolveWallet(opts);
+
+    const data = await apiRequest('check-url', { url }, {
+      demo: opts.demo,
+      wallet,
+    });
+
+    spinner?.stop();
+
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      formatUrl(data);
+    }
+
+    process.exitCode = exitCodeFromResult(data);
+  } catch (err) {
+    spinner?.fail(err.message);
+    process.exitCode = exitCodeFromError(err);
+  }
+}

package/src/index.js

@@ -0,0 +1,109 @@
+import { Command } from 'commander';
+import { passwordCommand } from './commands/password.js';
+import { emailCommand } from './commands/email.js';
+import { domainCommand } from './commands/domain.js';
+import { ipCommand } from './commands/ip.js';
+import { urlCommand } from './commands/url.js';
+import { scanCommand } from './commands/scan.js';
+import { healthCommand } from './commands/health.js';
+import { hashCommand } from './commands/hash.js';
+
+export function run(argv) {
+  const program = new Command();
+
+  program
+    .name('shieldapi')
+    .description('🛡️  ShieldAPI CLI — Security intelligence from your terminal. Pay-per-request with USDC.')
+    .version('1.1.0')
+    .option('--wallet <key>', 'Private key for x402 payments (or set SHIELDAPI_WALLET_KEY)')
+    .option('--json', 'Output raw JSON instead of formatted output')
+    .option('--no-color', 'Disable colors')
+    .option('-y, --yes', 'Skip payment confirmation prompts')
+    .option('-q, --quiet', 'Suppress non-essential output (spinners, warnings)');
+
+  program
+    .command('password')
+    .description('Check a password against breach databases')
+    .argument('<password>', 'Password to check (hashed locally with SHA-1)')
+    .option('--demo', 'Use demo mode (free, no wallet needed)')
+    .option('--stdin', 'Read password from stdin (avoids shell history)')
+    .option('--hash', 'Treat input as pre-computed SHA-1 hash')
+    .action((password, cmdOpts, cmd) => {
+      const globalOpts = cmd.parent.opts();
+      passwordCommand(password, { ...globalOpts, ...cmdOpts });
+    });
+
+  program
+    .command('email')
+    .description('Check an email address for known breaches')
+    .argument('<email>', 'Email address to check')
+    .option('--demo', 'Use demo mode (free, no wallet needed)')
+    .action((email, cmdOpts, cmd) => {
+      const globalOpts = cmd.parent.opts();
+      emailCommand(email, { ...globalOpts, ...cmdOpts });
+    });
+
+  program
+    .command('domain')
+    .description('Check domain reputation (DNS, blacklists, SSL, SPF/DMARC)')
+    .argument('<domain>', 'Domain to check')
+    .option('--demo', 'Use demo mode (free, no wallet needed)')
+    .action((domain, cmdOpts, cmd) => {
+      const globalOpts = cmd.parent.opts();
+      domainCommand(domain, { ...globalOpts, ...cmdOpts });
+    });
+
+  program
+    .command('ip')
+    .description('Check IP reputation (blacklists, Tor, rDNS)')
+    .argument('<ip>', 'IPv4 address to check')
+    .option('--demo', 'Use demo mode (free, no wallet needed)')
+    .action((ip, cmdOpts, cmd) => {
+      const globalOpts = cmd.parent.opts();
+      ipCommand(ip, { ...globalOpts, ...cmdOpts });
+    });
+
+  program
+    .command('url')
+    .description('Check URL safety (phishing, malware, brand impersonation)')
+    .argument('<url>', 'URL to check')
+    .option('--demo', 'Use demo mode (free, no wallet needed)')
+    .action((url, cmdOpts, cmd) => {
+      const globalOpts = cmd.parent.opts();
+      urlCommand(url, { ...globalOpts, ...cmdOpts });
+    });
+
+  program
+    .command('scan')
+    .description('Run a full security scan with multiple targets')
+    .option('--email <email>', 'Email address to include')
+    .option('--password <password>', 'Password to include (hashed locally)')
+    .option('--domain <domain>', 'Domain to include')
+    .option('--ip <ip>', 'IP address to include')
+    .option('--url <url>', 'URL to include')
+    .option('--demo', 'Use demo mode (free, no wallet needed)')
+    .action((cmdOpts, cmd) => {
+      const globalOpts = cmd.parent.opts();
+      scanCommand({ ...globalOpts, ...cmdOpts });
+    });
+
+  program
+    .command('health')
+    .description('Check ShieldAPI health and available endpoints')
+    .option('--demo', 'Use demo mode')
+    .action((cmdOpts, cmd) => {
+      const globalOpts = cmd.parent.opts();
+      healthCommand({ ...globalOpts, ...cmdOpts });
+    });
+
+  program
+    .command('hash')
+    .description('Compute SHA-1 hash locally (offline, no API call)')
+    .argument('<password>', 'Password to hash')
+    .action((password, cmdOpts, cmd) => {
+      const globalOpts = cmd.parent.opts();
+      hashCommand(password, { ...globalOpts, ...cmdOpts });
+    });
+
+  program.parse(argv);
+}

package/src/lib/api.js

@@ -0,0 +1,66 @@
+const BASE_URL = 'https://shield.vainplex.dev/api';
+
+/**
+ * Make an API request. Uses @x402/fetch for paid requests, plain fetch for demo.
+ * 
+ * @param {string} endpoint - API endpoint path (e.g. 'check-password')
+ * @param {Record<string, string>} params - Query parameters
+ * @param {object} options
+ * @param {boolean} options.demo - Use demo mode
+ * @param {{ signer: object }|null} options.wallet - Wallet with x402 signer
+ * @returns {Promise<object>} Parsed JSON response
+ */
+export async function apiRequest(endpoint, params = {}, { demo = false, wallet = null } = {}) {
+  if (demo) {
+    params.demo = 'true';
+  }
+
+  const query = new URLSearchParams(params).toString();
+  const url = `${BASE_URL}/${endpoint}${query ? '?' + query : ''}`;
+
+  if (demo || endpoint === 'health') {
+    // Free endpoints — plain fetch
+    const res = await fetch(url);
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      throw new ApiError(res.status, body || res.statusText);
+    }
+    return res.json();
+  }
+
+  // Paid endpoint — need wallet with signer
+  if (!wallet?.signer) {
+    throw new Error(
+      'No wallet configured. Use --wallet <key> or set SHIELDAPI_WALLET_KEY environment variable.'
+    );
+  }
+
+  // Dynamic import to keep startup fast when not needed
+  const { wrapFetchWithPayment } = await import('@x402/fetch');
+  const paidFetch = wrapFetchWithPayment(fetch, wallet.signer);
+
+  const res = await paidFetch(url);
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new ApiError(res.status, body || res.statusText);
+  }
+
+  return res.json();
+}
+
+export class ApiError extends Error {
+  constructor(status, body) {
+    let message = `API returned ${status}`;
+    try {
+      const parsed = JSON.parse(body);
+      if (parsed.error) message += `: ${parsed.error}`;
+      if (parsed.details) message += ` (${parsed.details})`;
+    } catch {
+      if (body) message += `: ${body}`;
+    }
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+  }
+}

package/src/lib/exit.js

@@ -0,0 +1,61 @@
+/**
+ * Exit code constants per RFC-001.
+ * 
+ * 0 = safe / low risk
+ * 1 = risk found (medium/high/critical)
+ * 2 = usage error (invalid args)
+ * 3 = network / API error
+ * 4 = payment error (insufficient balance, x402 failure)
+ */
+export const EXIT = {
+  SAFE: 0,
+  RISK: 1,
+  USAGE: 2,
+  NETWORK: 3,
+  PAYMENT: 4,
+};
+
+/**
+ * Determine exit code from API response data.
+ * Checks risk_level, found (password), breaches (email), threats (url).
+ */
+export function exitCodeFromResult(data) {
+  // Password check
+  if (data.found === true) return EXIT.RISK;
+  if (data.found === false) return EXIT.SAFE;
+
+  // Risk level based
+  const level = (data.risk_level || data.overall_risk_level || '').toLowerCase();
+  if (['critical', 'high', 'medium'].includes(level)) return EXIT.RISK;
+  if (['low', 'safe', 'none'].includes(level)) return EXIT.SAFE;
+
+  // Threats array
+  if (data.threats?.length > 0) return EXIT.RISK;
+
+  // Email breaches
+  if (data.breaches?.length > 0) return EXIT.RISK;
+
+  // Full scan — check nested
+  const checks = data.checks || {};
+  for (const val of Object.values(checks)) {
+    if (val?.found === true) return EXIT.RISK;
+    const rl = (val?.risk_level || '').toLowerCase();
+    if (['critical', 'high', 'medium'].includes(rl)) return EXIT.RISK;
+  }
+  if (data.password?.found) return EXIT.RISK;
+
+  return EXIT.SAFE;
+}
+
+/**
+ * Determine exit code from an error.
+ */
+export function exitCodeFromError(err) {
+  if (err?.status === 402 || err?.message?.includes('payment') || err?.message?.includes('x402') || err?.message?.includes('wallet')) {
+    return EXIT.PAYMENT;
+  }
+  if (err?.status >= 400 && err?.status < 500) {
+    return EXIT.USAGE;
+  }
+  return EXIT.NETWORK;
+}

package/src/lib/formatter.js

@@ -0,0 +1,345 @@
+import chalk from 'chalk';
+
+/**
+ * Format a risk level badge with color.
+ */
+export function riskBadge(level, score) {
+  const displayScore = score != null ? (score > 10 ? `${score}/100` : `${score}/10`) : '?';
+  const label = `${level?.toUpperCase() || 'UNKNOWN'} (${displayScore})`;
+  switch (level?.toLowerCase()) {
+    case 'critical':
+      return chalk.bgRed.white.bold(` ${label} `);
+    case 'high':
+      return chalk.red.bold(label);
+    case 'medium':
+      return chalk.yellow.bold(label);
+    case 'low':
+      return chalk.green.bold(label);
+    case 'safe':
+    case 'none':
+      return chalk.green(label);
+    default:
+      return chalk.gray(label);
+  }
+}
+
+/**
+ * Format a number with commas.
+ */
+export function formatNumber(n) {
+  return Number(n).toLocaleString('en-US');
+}
+
+/**
+ * Print a section header.
+ */
+export function sectionHeader(title) {
+  console.log();
+  console.log(chalk.bold.underline(title));
+}
+
+/**
+ * Print key-value pair with indentation.
+ */
+export function kvLine(key, value, indent = 3) {
+  const pad = ' '.repeat(indent);
+  console.log(`${pad}${chalk.gray(key + ':')} ${value}`);
+}
+
+/**
+ * Format password check result.
+ */
+export function formatPassword(data, hash) {
+  console.log();
+  if (data.found) {
+    console.log(chalk.red.bold('⚠️  PASSWORD COMPROMISED'));
+    console.log(`   Found in ${chalk.red.bold(formatNumber(data.count))} breaches`);
+    console.log(`   SHA-1: ${chalk.gray(hash)}`);
+    console.log();
+    console.log(chalk.red('   🚨 Change this password immediately!'));
+  } else {
+    console.log(chalk.green.bold('✅ Password NOT found in breach databases'));
+    console.log(`   SHA-1: ${chalk.gray(hash)}`);
+  }
+  console.log();
+}
+
+/**
+ * Format email breach result.
+ */
+export function formatEmail(data, email) {
+  console.log();
+  const breaches = data.breaches || [];
+
+  if (breaches.length > 0) {
+    console.log(
+      chalk.red.bold(`⚠️  ${breaches.length} breach${breaches.length > 1 ? 'es' : ''} found`) +
+      ` | Risk: ${riskBadge(data.risk_level, data.risk_score)}`
+    );
+    console.log();
+
+    for (const breach of breaches) {
+      const name = breach.name || breach.title || 'Unknown';
+      const date = breach.date || breach.breach_date || '';
+      const count = breach.records || breach.pwn_count;
+      const exposed = breach.exposed_data || breach.data_classes;
+
+      let line = `   📋 ${chalk.bold(name)}`;
+      if (date) line += ` (${date})`;
+      if (count) line += ` — ${formatNumber(count)} accounts`;
+      console.log(line);
+
+      if (exposed) {
+        const items = Array.isArray(exposed) ? exposed.join(', ') : exposed;
+        console.log(`      Exposed: ${chalk.gray(items)}`);
+      }
+    }
+
+    if (data.recommendations?.length) {
+      console.log();
+      console.log('   💡 Recommendations:');
+      for (const rec of data.recommendations) {
+        console.log(`      • ${rec}`);
+      }
+    }
+  } else {
+    console.log(chalk.green.bold('✅ No breaches found') + ` for ${chalk.bold(email)}`);
+  }
+  console.log();
+}
+
+/**
+ * Format domain reputation result.
+ */
+export function formatDomain(data) {
+  console.log();
+  console.log(
+    `🌐 Domain: ${chalk.bold(data.domain)} | Risk: ${riskBadge(data.risk_level, data.risk_score)}`
+  );
+  console.log();
+
+  if (data.dns) {
+    sectionHeader('DNS');
+    if (data.dns.a?.length) kvLine('A Records', data.dns.a.join(', '));
+    if (data.dns.mx?.length) kvLine('MX Records', data.dns.mx.join(', '));
+    if (data.dns.ns?.length) kvLine('NS Records', data.dns.ns.join(', '));
+    const hasSPF = data.dns.spf ?? data.dns.has_spf;
+    const hasDMARC = data.dns.dmarc ?? data.dns.has_dmarc;
+    if (hasSPF !== undefined) kvLine('SPF', hasSPF ? chalk.green('✓') : chalk.red('✗'));
+    if (hasDMARC !== undefined) kvLine('DMARC', hasDMARC ? chalk.green('✓') : chalk.red('✗'));
+  }
+
+  if (data.ssl) {
+    sectionHeader('SSL/TLS');
+    kvLine('Valid', data.ssl.valid ? chalk.green('✓') : chalk.red('✗'));
+    if (data.ssl.error) kvLine('Error', chalk.red(data.ssl.error));
+    if (data.ssl.issuer) kvLine('Issuer', data.ssl.issuer);
+    if (data.ssl.expires) kvLine('Expires', data.ssl.expires);
+  }
+
+  if (data.blacklists) {
+    sectionHeader('Blacklists');
+    if (Array.isArray(data.blacklists)) {
+      const listed = data.blacklists.filter(b => b.listed);
+      if (listed.length > 0) {
+        kvLine('Listed on', chalk.red(listed.map(b => b.list).join(', ')));
+      } else {
+        kvLine('Status', chalk.green('Not blacklisted'));
+      }
+    } else {
+      const listed = data.blacklists.listed_on || [];
+      if (listed.length > 0) {
+        kvLine('Listed on', chalk.red(listed.join(', ')));
+      } else {
+        kvLine('Status', chalk.green('Not blacklisted'));
+      }
+    }
+  }
+  console.log();
+}
+
+/**
+ * Format IP reputation result.
+ */
+export function formatIp(data) {
+  console.log();
+  console.log(
+    `🖥  IP: ${chalk.bold(data.ip)} | Risk: ${riskBadge(data.risk_level, data.risk_score)}`
+  );
+  console.log();
+
+  if (data.reverse_dns) {
+    kvLine('Reverse DNS', data.reverse_dns);
+  }
+  if (data.is_tor_exit !== undefined) {
+    kvLine('Tor Exit Node', data.is_tor_exit ? chalk.red('Yes') : chalk.green('No'));
+  }
+
+  if (data.blacklists) {
+    if (Array.isArray(data.blacklists)) {
+      const listed = data.blacklists.filter(b => b.listed);
+      if (listed.length > 0) {
+        kvLine('Blacklisted on', chalk.red(listed.map(b => b.name || b.list).join(', ')));
+      } else {
+        kvLine('Blacklists', chalk.green('Clean'));
+      }
+    } else if (data.blacklists.listed_on?.length) {
+      kvLine('Blacklisted on', chalk.red(data.blacklists.listed_on.join(', ')));
+    } else {
+      kvLine('Blacklists', chalk.green('Clean'));
+    }
+  }
+  console.log();
+}
+
+/**
+ * Format URL safety result.
+ */
+export function formatUrl(data) {
+  console.log();
+  console.log(
+    `🔗 URL: ${chalk.bold(data.url)} | Risk: ${riskBadge(data.risk_level, data.risk_score)}`
+  );
+  console.log();
+
+  if (data.threats?.length) {
+    console.log('   ⚠️  Threats detected:');
+    for (const threat of data.threats) {
+      if (typeof threat === 'string') {
+        console.log(`      • ${chalk.red(threat)}`);
+      } else {
+        const src = threat.source ? chalk.gray(`[${threat.source}]`) + ' ' : '';
+        console.log(`      • ${src}${chalk.red(threat.detail || threat.type || JSON.stringify(threat))}`);
+      }
+    }
+  } else {
+    console.log(`   ${chalk.green('✅ No threats detected')}`);
+  }
+
+  if (data.checks) {
+    sectionHeader('Checks');
+    for (const [key, value] of Object.entries(data.checks)) {
+      const label = key.replace(/_/g, ' ');
+      if (typeof value === 'object' && value !== null) {
+        // Complex check result — show found/reachable status or warnings
+        if (value.found !== undefined) {
+          kvLine(label, value.found ? chalk.red('Found in database') : chalk.green('Clean'));
+        } else if (value.reachable !== undefined) {
+          kvLine(label, value.reachable ? chalk.green('Reachable') : chalk.yellow('Unreachable'));
+        } else if (value.warnings?.length) {
+          kvLine(label, chalk.yellow(`${value.warnings.length} warning(s)`));
+        } else {
+          kvLine(label, chalk.green('OK'));
+        }
+      } else {
+        const status = value ? chalk.green('Passed') : chalk.red('Failed');
+        kvLine(label, status);
+      }
+    }
+  }
+  console.log();
+}
+
+/**
+ * Format full scan result.
+ */
+export function formatScan(data) {
+  console.log();
+  console.log(chalk.bold.underline('🛡️  Full Security Scan Results'));
+
+  // Support both flat (data.password) and nested (data.checks.password) structures
+  const checks = data.checks || {};
+  const pw = data.password || checks.password;
+  const emailData = data.email || checks.email_breaches || checks.email;
+  const domainData = data.domain || checks.domain;
+  const ipData = data.ip || checks.ip;
+  const urlData = data.url || checks.url;
+
+  if (pw) {
+    sectionHeader('🔑 Password');
+    if (pw.found) {
+      console.log(`   ${chalk.red.bold('COMPROMISED')} — found in ${formatNumber(pw.count)} breaches`);
+    } else {
+      console.log(`   ${chalk.green('Safe')} — not found in breach databases`);
+    }
+  }
+
+  if (emailData) {
+    sectionHeader('📧 Email');
+    const breaches = emailData.breaches || [];
+    if (breaches.length > 0) {
+      console.log(`   ${chalk.red.bold(breaches.length + ' breaches')} | Risk: ${riskBadge(emailData.risk_level, emailData.risk_score)}`);
+      for (const b of breaches) {
+        console.log(`   • ${b.name || b.title || 'Unknown'}`);
+      }
+    } else if (emailData.domain_breach_count > 0) {
+      console.log(`   ${chalk.yellow(emailData.domain_breach_count + ' domain breach(es)')} | Risk: ${riskBadge(emailData.risk_level, emailData.risk_score)}`);
+    } else {
+      console.log(`   ${chalk.green('No breaches found')}`);
+    }
+  }
+
+  if (domainData) {
+    sectionHeader('🌐 Domain');
+    const label = domainData.domain ? `${domainData.domain} — ` : '';
+    console.log(`   ${label}Risk: ${riskBadge(domainData.risk_level, domainData.risk_score)}`);
+  }
+
+  if (ipData) {
+    sectionHeader('🖥  IP');
+    console.log(`   Risk: ${riskBadge(ipData.risk_level, ipData.risk_score)}`);
+    if (ipData.is_tor_exit) console.log(`   ${chalk.red('⚠️  Tor exit node')}`);
+  }
+
+  if (urlData) {
+    sectionHeader('🔗 URL');
+    console.log(`   Risk: ${riskBadge(urlData.risk_level, urlData.risk_score)}`);
+    if (urlData.threats?.length) {
+      for (const t of urlData.threats) {
+        const text = typeof t === 'string' ? t : (t.detail || t.type || JSON.stringify(t));
+        console.log(`   • ${chalk.red(text)}`);
+      }
+    }
+  }
+
+  // Overall risk
+  if (data.overall_risk_level || data.overall_risk_score != null) {
+    console.log();
+    console.log(`Overall Risk: ${riskBadge(data.overall_risk_level, data.overall_risk_score)}`);
+  }
+
+  // Summary lines
+  if (data.summary?.length) {
+    console.log();
+    for (const line of data.summary) {
+      console.log(`   ${line}`);
+    }
+  }
+
+  console.log();
+}
+
+/**
+ * Format health check result.
+ */
+export function formatHealth(data) {
+  console.log();
+  console.log(chalk.green.bold('✅ ShieldAPI is healthy'));
+  console.log();
+
+  if (data.endpoints) {
+    console.log(chalk.bold('Available endpoints:'));
+    console.log();
+    for (const ep of data.endpoints) {
+      const name = ep.path || ep.endpoint || ep.name;
+      const price = ep.price || ep.cost;
+      console.log(`   ${chalk.cyan(name)}${price ? ` — ${chalk.yellow(price + ' USDC')}` : ''}`);
+    }
+  } else if (typeof data === 'object') {
+    // Fallback: just show the keys
+    for (const [key, value] of Object.entries(data)) {
+      console.log(`   ${chalk.gray(key + ':')} ${JSON.stringify(value)}`);
+    }
+  }
+  console.log();
+}

package/src/lib/wallet.js

@@ -0,0 +1,43 @@
+import { createWalletClient, http, publicActions } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+import { toClientEvmSigner } from '@x402/evm';
+
+/**
+ * Create a viem wallet client + x402 signer from a private key.
+ * 
+ * @param {string} privateKey - Hex private key (with or without 0x prefix)
+ * @returns {{ client: import('viem').WalletClient, signer: object }}
+ */
+export function createWallet(privateKey) {
+  if (!privateKey) return null;
+
+  const key = privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`;
+
+  try {
+    const account = privateKeyToAccount(key);
+    const client = createWalletClient({
+      account,
+      chain: base,
+      transport: http(),
+    }).extend(publicActions);
+
+    const signer = toClientEvmSigner(client);
+
+    return { client, signer, address: account.address };
+  } catch (err) {
+    throw new Error(`Invalid private key: ${err.message}`);
+  }
+}
+
+/**
+ * Resolve wallet/signer from CLI option or environment variable.
+ * 
+ * @param {object} opts - Commander options
+ * @returns {{ signer: object, address: string }|null}
+ */
+export function resolveWallet(opts) {
+  const key = opts?.wallet || process.env.SHIELDAPI_WALLET_KEY;
+  if (!key) return null;
+  return createWallet(key);
+}