@bankofai/x402-cli 1.0.1-beta.8 → 1.0.1

package/dist/daemon.js

@@ -0,0 +1,47 @@
+import net from "node:net";
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import { opt, outputMode } from "./args.js";
+import { emit } from "./output.js";
+function stripFlag(argv, flag) {
+    return argv.filter(item => item !== flag);
+}
+async function waitForPort(host, port, timeout = 5_000) {
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        const connected = await new Promise(resolve => {
+            const socket = net.createConnection({ host, port });
+            socket.setTimeout(250);
+            socket.once("connect", () => { socket.destroy(); resolve(true); });
+            socket.once("error", () => resolve(false));
+            socket.once("timeout", () => { socket.destroy(); resolve(false); });
+        });
+        if (connected)
+            return;
+        await delay(50);
+    }
+    throw new Error(`daemon did not become ready on ${host}:${port}`);
+}
+export async function startServeDaemon(argv, options, requirement, script) {
+    if (!requirement.payTo)
+        throw new Error("--pay-to is required");
+    const daemonArgs = stripFlag(stripFlag(argv, "--daemon"), "-d");
+    const child = spawn(process.execPath, [script, ...daemonArgs], { detached: true, stdio: "ignore", env: process.env });
+    child.unref();
+    const host = opt(options, "host", "127.0.0.1");
+    const port = Number(opt(options, "port", "4020"));
+    const resourceUrl = opt(options, "resource-url", `http://${host}:${port}/pay`);
+    try {
+        await waitForPort(host === "0.0.0.0" ? "127.0.0.1" : host === "::" ? "::1" : host, port);
+    }
+    catch (error) {
+        if (child.pid)
+            try {
+                process.kill(child.pid);
+            }
+            catch { /* child already exited */ }
+        throw error;
+    }
+    emit({ command: "server", mode: outputMode(options), network: requirement.network, scheme: requirement.scheme,
+        result: { pid: child.pid, pay_url: resourceUrl, resource_url: resourceUrl, daemon: true } });
+}

package/dist/gateway/catalog.js

@@ -0,0 +1,56 @@
+import { paymentRequirements, priceUsd } from "./config.js";
+function configs(input) {
+    return input instanceof Map ? [...input.values()].map(entry => entry.config) : [...input];
+}
+export function providerCatalogProjection(provider) {
+    return {
+        name: provider.name,
+        title: provider.title ?? provider.name,
+        description: "",
+        category: "other",
+        network: provider.operator.network,
+        currency: provider.operator.currencies?.usd?.[0] ?? "USDT",
+        endpoints: (provider.endpoints ?? []).map(endpoint => {
+            const price = priceUsd(endpoint);
+            const requirements = paymentRequirements(provider, price);
+            return {
+                method: endpoint.method.toUpperCase(),
+                path: `/providers/${provider.name}${endpoint.path}`,
+                upstream_path: endpoint.path,
+                description: "",
+                paid: price > 0 ? {
+                    scheme: requirements[0]?.scheme,
+                    network: requirements[0]?.network,
+                    currency: provider.operator.currencies?.usd?.[0] ?? "USDT",
+                    price_usd: price,
+                } : null,
+                x402_routes: requirements.map(requirement => ({
+                    provider: provider.name,
+                    network: requirement.network,
+                    scheme: requirement.scheme,
+                    ...(requirement.extra?.assetTransferMethod ? { assetTransferMethod: requirement.extra.assetTransferMethod } : {}),
+                    url: `/providers/${provider.name}${endpoint.path}`,
+                })),
+            };
+        }),
+    };
+}
+export function buildGatewayCatalog(input) {
+    return { version: 1, generatedAt: new Date().toISOString(), providers: configs(input).map(providerCatalogProjection) };
+}
+export function providerPaymentAssets(input) {
+    return configs(input).flatMap(provider => (provider.endpoints ?? []).flatMap(endpoint => {
+        const price = priceUsd(endpoint);
+        const currencies = provider.operator.currencies?.usd ?? ["USDT"];
+        return paymentRequirements(provider, price).map((requirement, index) => ({
+            provider: provider.name,
+            method: endpoint.method,
+            path: `/providers/${provider.name}${endpoint.path}`,
+            network: requirement.network,
+            currency: currencies[index % currencies.length],
+            price_usd: price,
+            scheme: requirement.scheme,
+            ...(requirement.extra?.assetTransferMethod ? { assetTransferMethod: requirement.extra.assetTransferMethod } : {}),
+        }));
+    }));
+}

package/dist/gateway/index.js

@@ -0,0 +1,3 @@
+export { endpointFor, loadProvider, loadProviders, paymentRequirements, priceUsd, } from "./config.js";
+export { getToken, normalizeNetwork, toSmallestUnit, TOKENS, } from "./tokens.js";
+export { buildGatewayCatalog, providerCatalogProjection, providerPaymentAssets } from "./catalog.js";

package/dist/gateway/rate-limit.js

@@ -0,0 +1,34 @@
+export class FixedWindowRateLimiter {
+    limit;
+    windowMs;
+    cleanupIntervalMs;
+    entries = new Map();
+    nextCleanupAt = 0;
+    constructor(limit, windowMs = 60_000, cleanupIntervalMs = 60_000) {
+        this.limit = limit;
+        this.windowMs = windowMs;
+        this.cleanupIntervalMs = cleanupIntervalMs;
+    }
+    consume(key, now = Date.now()) {
+        if (now >= this.nextCleanupAt) {
+            for (const [entryKey, entry] of this.entries) {
+                if (entry.resetAt <= now)
+                    this.entries.delete(entryKey);
+            }
+            this.nextCleanupAt = now + this.cleanupIntervalMs;
+        }
+        let entry = this.entries.get(key);
+        if (!entry || entry.resetAt <= now) {
+            entry = { count: 0, resetAt: now + this.windowMs };
+            this.entries.set(key, entry);
+        }
+        entry.count += 1;
+        return {
+            allowed: entry.count <= this.limit,
+            retryAfter: Math.max(1, Math.ceil((entry.resetAt - now) / 1000)),
+        };
+    }
+    get size() {
+        return this.entries.size;
+    }
+}

package/dist/gateway/server.js

@@ -2,6 +2,7 @@ import http from "node:http";
 import { timingSafeEqual } from "node:crypto";
 import { URL } from "node:url";
 import { endpointFor, paymentRequirements, priceUsd } from "./config.js";
+import { FixedWindowRateLimiter } from "./rate-limit.js";
 import { decodeSignature, encodeRequired, encodeResponse, headers, matchRequirement } from "./x402.js";
 class HttpError extends Error {
     status;
@@ -312,7 +313,7 @@ async function forward(metrics, entry, request, response, routePath, body, payme
 export function createGatewayServer(providers) {
     const publicBaseUrl = configuredPublicBaseUrl();
     const metrics = createMetrics();
-    const rateLimits = new Map();
+    const rateLimiter = new FixedWindowRateLimiter(RATE_LIMIT_PER_MINUTE);
     let activeRequests = 0;
     const server = http.createServer(async (request, response) => {
         let countedActive = false;
@@ -384,16 +385,10 @@ export function createGatewayServer(providers) {
             }
             const now = Date.now();
             const address = clientAddress(request);
-            let rate = rateLimits.get(address);
-            if (!rate || rate.resetAt <= now) {
-                rate = { count: 0, resetAt: now + 60_000 };
-                rateLimits.set(address, rate);
-            }
-            rate.count += 1;
-            if (rate.count > RATE_LIMIT_PER_MINUTE) {
+            const rate = rateLimiter.consume(address, now);
+            if (!rate.allowed) {
                 metrics.rejectedRequests += 1;
-                const retryAfter = Math.max(1, Math.ceil((rate.resetAt - now) / 1000));
-                throw new HttpError(429, "gateway rate limited", undefined, { "retry-after": String(retryAfter) });
+                throw new HttpError(429, "gateway rate limited", undefined, { "retry-after": String(rate.retryAfter) });
             }
             if (activeRequests >= MAX_CONCURRENT_REQUESTS) {
                 metrics.rejectedRequests += 1;

package/dist/gateway-commands.js

@@ -0,0 +1,145 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { opt, outputMode } from "./args.js";
+import { emit, printJson } from "./output.js";
+import { buildGatewayCatalog, loadProviders, providerPaymentAssets } from "@bankofai/x402-gateway";
+const require = createRequire(import.meta.url);
+function executableInPath(name) {
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, name);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Try the next PATH entry.
+        }
+    }
+    return undefined;
+}
+function resolveGatewayPackageRuntime() {
+    try {
+        return path.join(path.dirname(require.resolve("@bankofai/x402-gateway/package.json")), "dist", "cli.js");
+    }
+    catch {
+        return undefined;
+    }
+}
+function gatewayCommand(options) {
+    const explicit = opt(options, "gateway-bin");
+    const gatewayPackageRuntime = resolveGatewayPackageRuntime();
+    const candidates = [
+        explicit ? { file: explicit, source: "--gateway-bin" } : undefined,
+        gatewayPackageRuntime ? { file: gatewayPackageRuntime, source: "@bankofai/x402-gateway dependency" } : undefined,
+        { file: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "gateway", "cli.js"), source: "bundled gateway runtime" },
+        executableInPath("x402-gateway") ? { file: executableInPath("x402-gateway"), source: "PATH x402-gateway" } : undefined,
+        { file: path.resolve(process.cwd(), "../x402-gateway/dist/cli.js"), source: "sibling ../x402-gateway" },
+    ].filter(Boolean);
+    for (const candidate of candidates) {
+        try {
+            fs.accessSync(candidate.file, fs.constants.R_OK);
+            if (candidate.file.endsWith(".js")) {
+                return { command: process.execPath, argsPrefix: [candidate.file], source: candidate.source };
+            }
+            return { command: candidate.file, argsPrefix: [], source: candidate.source };
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    throw new Error("x402-gateway runtime not found. Install @bankofai/x402-gateway, run from a checkout with ../x402-gateway/dist/cli.js, or pass --gateway-bin <path>.");
+}
+export async function gatewayStart(args, options) {
+    const gateway = gatewayCommand(options);
+    const child = spawn(gateway.command, [...gateway.argsPrefix, ...args], {
+        stdio: "inherit",
+        env: process.env,
+    });
+    await new Promise((resolve, reject) => {
+        child.on("exit", code => code === 0 ? resolve() : reject(new Error(`gateway exited with ${code}`)));
+        child.on("error", reject);
+    });
+}
+export function gatewayCheck(target, options) {
+    const providers = loadProviders(target);
+    emit({
+        command: "gateway check",
+        mode: outputMode(options),
+        result: { providers: [...providers.keys()], count: providers.size },
+    });
+}
+export function gatewayScaffold(name, options) {
+    const outputDir = opt(options, "output-dir", path.join("providers", name));
+    const forwardUrl = opt(options, "forward-url", "https://api.example.com");
+    fs.mkdirSync(outputDir, { recursive: true });
+    const body = `name: ${name}
+title: "${name}"
+description: "x402 provider"
+category: data
+version: v1
+
+forward_url: ${forwardUrl}
+
+routing:
+  type: proxy
+
+operator:
+  network: tron:0xcd8690dc
+  currencies:
+    usd: ["USDT"]
+  recipient: <provider-recipient-address>
+  scheme: exact
+  protocol: exact
+  asset_transfer_method: permit2
+  facilitator_url: https://facilitator.bankofai.io
+  facilitator_api_key: <facilitator-api-key>
+  valid_for_seconds: 300
+
+endpoints:
+  - method: GET
+    path: /v1/ping
+    metering:
+      dimensions:
+        - tiers:
+            - price_usd: 0.0001
+  `;
+    fs.writeFileSync(path.join(outputDir, "provider.yml"), body);
+    emit({
+        command: "gateway scaffold",
+        mode: outputMode(options),
+        result: { file: path.join(outputDir, "provider.yml") },
+    });
+}
+export function catalogBuild(target, options) {
+    const providers = loadProviders(target);
+    const catalog = buildGatewayCatalog(providers);
+    const output = opt(options, "output", opt(options, "dist-dir") ? path.join(opt(options, "dist-dir"), "catalog.json") : undefined);
+    if (output) {
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.writeFileSync(output, JSON.stringify(catalog, null, 2));
+        emit({
+            command: "catalog build",
+            mode: outputMode(options),
+            result: { output, count: providers.size },
+        });
+    }
+    else if (outputMode(options) === "json") {
+        emit({ command: "catalog build", mode: "json", result: catalog });
+    }
+    else {
+        printJson(catalog);
+    }
+}
+export function catalogPayAssets(target, options) {
+    const rows = providerPaymentAssets(loadProviders(target));
+    emit({
+        command: "gateway catalog pay-assets",
+        mode: outputMode(options),
+        result: { count: rows.length, assets: rows },
+    });
+}

package/dist/help.js

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+export function getVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return String(pkg.version ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export function helpText(topic = "root") {
+    const sections = {
+        root: `x402-cli ${getVersion()}
+
+Usage:
+  x402-cli <command> [options]
+
+Commands:
+  pay <url>                 Pay an x402-protected URL
+  serve                     Run a local x402 paywall endpoint
+  roundtrip                 Start serve, pay it, then exit
+  gateway <command>         Manage local gateway provider files
+  catalog <command>         Search, cache, and export provider catalog assets
+
+Global options:
+  -h, --help                Show help
+  -V, --version             Show version
+  --json                    Print machine-readable JSON envelope
+  --human                   Print human-readable output (default)
+`,
+        pay: `Usage:
+  x402-cli pay <url> [options]
+
+Options:
+  --method <method>         HTTP method (default: GET)
+  --header "Name: Value"    Request header, repeatable
+  --body <body>             Request body for non-GET/HEAD methods
+  --network <caip2>         Require a specific network
+  --token <symbol>          Require a specific token
+  --scheme <scheme>         Require a specific x402 scheme
+  --gasfree-api-url <url>   Override the TRON GasFree relayer API URL
+  --max-gasfree-fee <amt>   Maximum GasFree relayer fee in token units
+  --max-gasfree-fee-raw <n> Maximum GasFree relayer fee in smallest units
+  --max-amount <amount>     Maximum human-readable payment amount
+  --max-raw-amount <amount> Maximum smallest-unit payment amount
+  --dry-run                 Read requirements but do not sign or pay
+  --private-key <hex>       Explicit payer private key (or PRIVATE_KEY/TRON_PRIVATE_KEY/EVM_PRIVATE_KEY)
+  --rpc-url <url>           Explicit network RPC URL
+  --timeout-ms <ms>         Network timeout in milliseconds (default: 30000)
+  --json                    Print JSON envelope
+
+Examples:
+  x402-cli pay https://api.example.com/paid --dry-run --json
+  x402-cli pay https://api.example.com/paid --max-amount 0.01
+`,
+        serve: `Usage:
+  x402-cli serve --pay-to <address> [options]
+
+Options:
+  --pay-to <address>        Recipient wallet address
+  --amount <amount>         Human-readable token amount (default: 0.0001)
+  --raw-amount <amount>     Smallest-unit amount
+  --network <caip2>         Payment network (default: tron:0xcd8690dc)
+  --scheme <scheme>         Payment scheme: exact or exact_gasfree (default: exact)
+  --token <symbol>          Token symbol (default: USDT)
+  --asset <address>         Explicit token address
+  --decimals <count>        Token decimals for unregistered --asset
+  --host <host>             Bind host (default: 127.0.0.1)
+  --port <port>             Bind port (default: 4020)
+  --resource-url <url>      URL advertised in payment requirements
+  --facilitator-url <url>   Facilitator base URL
+  --timeout-ms <ms>         Facilitator timeout in milliseconds (default: 30000)
+  --daemon                  Run in background and print the child pid
+  --json                    Print JSON envelope
+
+Examples:
+  x402-cli serve --pay-to T... --network tron:0xcd8690dc --token USDT
+  x402-cli serve --pay-to 0x... --network eip155:97 --token USDT --amount 0.0001
+`,
+        roundtrip: `Usage:
+  x402-cli roundtrip --pay-to <address> [serve/pay options]
+`,
+        gateway: `Usage:
+  x402-cli gateway <search|start|check|scaffold|catalog> [options]
+
+Commands:
+  search <query>            Search a gateway/catalog artifact
+  start                     Start a local x402 gateway process
+  check <providers>         Validate provider.yml files
+  scaffold <name>           Write a starter provider.yml
+  catalog <command>         Build/check/search gateway catalog assets
+`,
+        "gateway-catalog": `Usage:
+  x402-cli gateway catalog <build|check|pay-assets|search> [options]
+
+Commands:
+  build <providers>         Build a local catalog from provider.yml files
+  check <providers>         Validate local provider.yml files
+  pay-assets <providers>    List payable endpoint assets
+  search <query>            Search a catalog artifact
+`,
+        catalog: `Usage:
+  x402-cli catalog <update|search|show|endpoints|pay-json|export-gateway|build> [options]
+
+Commands:
+  update                    Cache hosted/local catalog assets under ~/.cache
+  search <query>            Search providers
+  show <provider>           Show provider detail JSON
+  endpoints <provider>      List provider endpoints
+  pay-json <provider>       Print provider pay JSON
+  export-gateway <url>      Export catalog.json and pay.md from a gateway
+  build <providers>         Build catalog from provider.yml files
+
+Options:
+  --catalog <source>        catalog.json path or URL
+  --provider <fqn>          Provider FQN for export-gateway
+  --output-dir <dir>        Output directory for generated files
+  -n, --limit <count>       Search result limit
+  --timeout-ms <ms>         Network timeout in milliseconds (default: 30000)
+  --include-blocked         Include blocked providers in search
+  --json                    Print JSON envelope
+`,
+        "catalog-search": `Usage:
+  x402-cli catalog search <query> [--catalog <source>] [options]
+
+Options:
+  --catalog <source>        catalog.json path or URL
+  -n, --limit <count>       Search result limit
+  --timeout-ms <ms>         Network timeout in milliseconds (default: 30000)
+  --include-blocked         Include blocked providers in search
+  --json                    Print JSON envelope
+`,
+        "catalog-show": `Usage:
+  x402-cli catalog show <provider> [--catalog <source>] [options]
+
+Options:
+  --catalog <source>        catalog.json path or URL
+  --timeout-ms <ms>         Network timeout in milliseconds (default: 30000)
+  --json                    Print JSON envelope
+`,
+        "catalog-pay-json": `Usage:
+  x402-cli catalog pay-json <provider> [--catalog <source>] [options]
+
+Options:
+  --catalog <source>        catalog.json path or URL
+  --timeout-ms <ms>         Network timeout in milliseconds (default: 30000)
+  --raw                     Print raw pay payload instead of JSON envelope
+  --json                    Print JSON envelope
+`,
+        "catalog-endpoints": `Usage:
+  x402-cli catalog endpoints <provider> [--catalog <source>] [options]
+
+Options:
+  --catalog <source>        catalog.json path or URL
+  --timeout-ms <ms>         Network timeout in milliseconds (default: 30000)
+  --json                    Print JSON envelope
+`,
+        "catalog-export-gateway": `Usage:
+  x402-cli catalog export-gateway <gateway-url> --provider <fqn> [options]
+
+Options:
+  --provider <fqn>          Provider FQN to export
+  --output-dir <dir>        Output directory for generated files
+  --force                   Overwrite existing files
+  --json                    Print JSON envelope
+`,
+    };
+    return sections[topic] ?? sections.root;
+}

package/dist/http-client.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import { CliError, opt } from "./args.js";
+const MAX_HTTP_BODY_BYTES = 10 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 30_000;
+export function positiveIntegerOption(options, key, fallback) {
+    const value = opt(options, key, String(fallback));
+    if (!/^\d+$/.test(value))
+        throw new CliError("INVALID_ARGUMENT", `--${key} must be a positive integer`, `Pass --${key} with a value greater than zero.`, 2);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new CliError("INVALID_ARGUMENT", `--${key} must be a positive integer`, `Pass --${key} with a value greater than zero.`, 2);
+    return parsed;
+}
+export function timeoutMs(options) {
+    return options ? positiveIntegerOption(options, "timeout-ms", DEFAULT_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
+}
+export async function fetchWithTimeout(input, init = {}, timeout = DEFAULT_TIMEOUT_MS, label = "request") {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+        return await fetch(input, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError")
+            throw new Error(`${label} timed out after ${timeout}ms`);
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function readBoundedText(response, label) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_HTTP_BODY_BYTES)
+        throw new Error(`${label} exceeds ${MAX_HTTP_BODY_BYTES} byte limit`);
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > MAX_HTTP_BODY_BYTES) {
+            await reader.cancel();
+            throw new Error(`${label} exceeds ${MAX_HTTP_BODY_BYTES} byte limit`);
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(bytes);
+}
+export async function readText(source, options) {
+    if (!source.startsWith("http://") && !source.startsWith("https://"))
+        return fs.readFileSync(source, "utf8");
+    const response = await fetchWithTimeout(source, {}, timeoutMs(options), `fetch ${source}`);
+    if (!response.ok)
+        throw new Error(`failed to fetch ${source}: ${response.status}`);
+    return readBoundedText(response, `response from ${source}`);
+}
+export async function readJson(source, options) {
+    return JSON.parse(await readText(source, options));
+}
+export async function responsePayload(response) {
+    const text = await readBoundedText(response, "HTTP response");
+    if ((response.headers.get("content-type") ?? "").toLowerCase().includes("json")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}

package/dist/output.js

@@ -0,0 +1,91 @@
+import { CliError } from "./args.js";
+export function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function emit(args) {
+    const mode = args.mode ?? "human";
+    if (mode === "json") {
+        const envelope = { ok: !args.error, command: args.command };
+        if (args.network)
+            envelope.network = args.network;
+        if (args.scheme)
+            envelope.scheme = args.scheme;
+        if (args.error)
+            envelope.error = args.error;
+        else
+            envelope.result = args.result ?? null;
+        printJson(envelope);
+        return;
+    }
+    if (args.error) {
+        process.stderr.write(`ERROR ${args.command}: ${args.error.code}\n`);
+        process.stderr.write(`  ${args.error.message}\n`);
+        if (args.error.hint)
+            process.stderr.write(`  hint: ${args.error.hint}\n`);
+        if (args.error.details !== undefined)
+            process.stderr.write(`  details: ${JSON.stringify(args.error.details)}\n`);
+        return;
+    }
+    const suffix = [args.network, args.scheme].filter(Boolean).join(" ");
+    process.stdout.write(`OK ${args.command}${suffix ? ` (${suffix})` : ""}\n`);
+    if (args.result && typeof args.result === "object" && !Array.isArray(args.result)) {
+        for (const [key, value] of Object.entries(args.result)) {
+            if (value === undefined)
+                continue;
+            process.stdout.write(value && typeof value === "object" ? `  ${key}: ${JSON.stringify(value)}\n` : `  ${key}: ${value}\n`);
+        }
+    }
+    else if (args.result !== undefined)
+        process.stdout.write(`  ${args.result}\n`);
+}
+export function classify(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof CliError)
+        return { code: error.code, message, hint: error.hint, details: error.details };
+    const lower = message.toLowerCase();
+    if (lower.includes("missing private key") || lower.includes("could not find a wallet"))
+        return { code: "WALLET_NOT_CONFIGURED", message, hint: "Set PRIVATE_KEY, TRON_PRIVATE_KEY, EVM_PRIVATE_KEY, or configure agent-wallet with a payer wallet." };
+    if (lower.includes("wallets_config") || lower.includes("wallet config"))
+        return { code: "WALLET_CONFIG_CORRUPT", message, hint: "Check ~/.agent-wallet/wallets_config.json or recreate the local agent-wallet configuration." };
+    if (lower.includes("does not exist") && lower.includes("account [t"))
+        return { code: "TRON_ACCOUNT_NOT_ACTIVATED", message, hint: "Activate the TRON address by sending it a small amount of TRX before signing contract calls." };
+    if (lower.includes("permit2_insufficient_balance") || lower.includes("insufficient") && lower.includes("balance"))
+        return { code: "INSUFFICIENT_TOKEN_BALANCE", message, hint: "Fund the payer address with the exact token and network advertised by the provider, then retry." };
+    if (lower.includes("transfer_from_failed") || lower.includes("transferfrom failed"))
+        return { code: "TOKEN_TRANSFER_FAILED", message, hint: "Check token balance, token contract, payer address, and that the selected x402 route matches the provider requirement." };
+    if (lower.includes("insufficient funds for gas") || lower.includes("insufficient gas") || lower.includes("energy"))
+        return { code: "INSUFFICIENT_GAS", message, hint: "Fund the payer address with the native gas token for this network." };
+    if (lower.includes("deadline") || lower.includes("expired"))
+        return { code: "DEADLINE_OR_CLOCK_SKEW", message, hint: "Check local clock sync and retry with a fresh payment requirement." };
+    if (lower.includes("permittransferfrom") || lower.includes("invalid signature") || lower.includes("permit reverted"))
+        return { code: "PERMIT_REVERTED", message, hint: "The token or Permit2 contract rejected the signature; retry with a fresh requirement and verify token/network support." };
+    if (lower.includes("tokenregistry") && lower.includes("import"))
+        return { code: "SDK_API_DRIFT", message, hint: "Installed x402 SDK packages do not match this CLI; reinstall @bankofai/x402-cli and SDK dependencies." };
+    if (lower.includes("429") || lower.includes("too many requests") || lower.includes("rate limit"))
+        return { code: "RATE_LIMITED", message, hint: "Wait briefly and retry; the upstream service or RPC is rate limiting requests." };
+    if (lower.includes("402 response missing"))
+        return { code: "INVALID_X402_RESPONSE", message, hint: "The endpoint returned HTTP 402 without a PAYMENT-REQUIRED header." };
+    if (lower.includes("no matching payment requirement"))
+        return { code: "NO_MATCHING_PAYMENT_REQUIREMENT", message, hint: "Relax --network, --token, or --scheme, or use values offered by the provider." };
+    if (lower.includes("exceeds --max"))
+        return { code: "PAYMENT_AMOUNT_TOO_HIGH", message, hint: "Increase the max amount flag only if this provider price is expected." };
+    if (lower.includes("failed to fetch") || lower.includes("fetch failed") || lower.includes("econnrefused") || lower.includes("timed out"))
+        return { code: "NETWORK_ERROR", message, hint: "Check the URL, local server, proxy, and network connectivity." };
+    if (lower.includes(" is required") || lower.includes("must be") || lower.includes("invalid --") || lower.includes("mutually exclusive"))
+        return { code: lower.includes("required") ? "MISSING_ARGUMENT" : "INVALID_ARGUMENT", message, hint: "Run the command with --help to see valid usage and options." };
+    return { code: "IO_ERROR", message, hint: "Run with --json for structured output, and check the provider/gateway logs for details." };
+}
+export async function withSdkStdoutRedirect(enabled, fn) {
+    if (!enabled)
+        return fn();
+    const originalLog = console.log;
+    console.log = (...args) => {
+        process.stderr.write(`${args.map(arg => typeof arg === "string" ? arg : JSON.stringify(arg, null, 2)).join(" ")}\n`);
+    };
+    try {
+        return await fn();
+    }
+    finally {
+        console.log = originalLog;
+    }
+}