@bankofai/x402-cli 1.0.1-beta.1 → 1.0.1-beta.10

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;
+    }
+}

package/dist/tokens.js

@@ -74,19 +74,25 @@ export const TOKENS = {
     },
 };
 export function normalizeNetwork(network) {
-    return ({
+    const legacyTronIds = {
         "tron-mainnet": "tron:0x2b6653dc",
         "tron:mainnet": "tron:0x2b6653dc",
-        "mainnet": "tron:0x2b6653dc",
+        mainnet: "tron:0x2b6653dc",
         "tron-shasta": "tron:0x94a9059e",
         "tron:shasta": "tron:0x94a9059e",
-        "shasta": "tron:0x94a9059e",
+        shasta: "tron:0x94a9059e",
         "tron-nile": "tron:0xcd8690dc",
         "tron:nile": "tron:0xcd8690dc",
-        "nile": "tron:0xcd8690dc",
+        nile: "tron:0xcd8690dc",
+    };
+    const canonical = legacyTronIds[network];
+    if (canonical) {
+        throw new Error(`legacy TRON network identifier ${network} is not supported; use ${canonical}`);
+    }
+    return {
         "bsc-mainnet": "eip155:56",
         "bsc-testnet": "eip155:97",
-    }[network] ?? network);
+    }[network] ?? network;
 }
 export function getToken(network, symbol) {
     const token = TOKENS[normalizeNetwork(network)]?.[symbol.toUpperCase()];
@@ -104,8 +110,8 @@ export function assertRawAmount(value, name = "raw amount") {
     return value.replace(/^0+(?=\d)/, "");
 }
 export function toSmallestUnit(amount, decimals) {
-    if (!Number.isInteger(decimals) || decimals < 0)
-        throw new Error("token decimals must be a non-negative integer");
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 255)
+        throw new Error("token decimals must be an integer between 0 and 255");
     if (!/^\d+(\.\d+)?$/.test(amount))
         throw new Error("amount must be a non-negative decimal string");
     const [whole, fraction = ""] = amount.split(".");

package/dist/x402.js

@@ -2,7 +2,7 @@ import { decodePaymentRequiredHeader, decodePaymentResponseHeader, decodePayment
 import { x402Client } from "@bankofai/x402-core/client";
 import { ExactEvmScheme, toClientEvmSigner } from "@bankofai/x402-evm";
 import { ExactTronScheme, createClientTronSigner } from "@bankofai/x402-tron";
-import { registerExactGasFreeTronScheme } from "@bankofai/x402-tron/gasfree/client";
+import { ExactGasFreeTronScheme, createGasFreeApiClients, getGasFreeApiBaseUrl } from "@bankofai/x402-tron/gasfree";
 import { createPublicClient, http } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { TronWeb } from "tronweb";
@@ -106,7 +106,7 @@ function evmRpcUrl(network, explicit) {
         (chainId === "56" ? "https://bsc-dataseed.binance.org" : undefined) ||
         (chainId === "97" ? "https://data-seed-prebsc-1-s1.binance.org:8545" : undefined));
 }
-async function createTronWallet(privateKey) {
+async function createTronWallet(privateKey, maxGasfreeFeeRaw) {
     const rawKey = privateKey.replace(/^0x/, "");
     const tronWeb = new TronWeb({ fullHost: "https://api.trongrid.io" });
     const address = TronWeb.address.fromPrivateKey(rawKey);
@@ -115,6 +115,12 @@ async function createTronWallet(privateKey) {
     return {
         getAddress: () => address,
         async signTypedData(args) {
+            if (maxGasfreeFeeRaw !== undefined && args?.primaryType === "PermitTransfer") {
+                const maxFee = BigInt(args?.message?.maxFee ?? -1);
+                if (maxFee < 0n || maxFee > BigInt(maxGasfreeFeeRaw)) {
+                    throw new Error(`final GasFree maxFee ${maxFee} exceeds --max-gasfree-fee limit ${maxGasfreeFeeRaw}`);
+                }
+            }
             const signature = await signTronTypedData(tronWeb, args, rawKey);
             return signature.startsWith("0x") ? signature : `0x${signature}`;
         },
@@ -142,13 +148,14 @@ export async function createPaymentPayload(args) {
         const publicClient = rpcUrl ? createPublicClient({ transport: http(rpcUrl) }) : undefined;
         const signer = toClientEvmSigner(account, publicClient);
         const scheme = new ExactEvmScheme(signer, rpcUrl ? { rpcUrl } : undefined);
-        return new x402Client()
+        const payload = await new x402Client()
             .register(selected.network, scheme)
             .createPaymentPayload(required);
+        return { payload };
     }
     if (selected.network.startsWith("tron:")) {
         const privateKey = privateKeyFrom(["TRON_PRIVATE_KEY", "AGENT_WALLET_PRIVATE_KEY", "PRIVATE_KEY"], args.privateKey, ["tron_client", "payer", "default"]);
-        const wallet = await createTronWallet(privateKey);
+        const wallet = await createTronWallet(privateKey, selected.scheme === "exact_gasfree" ? args.maxGasfreeFeeRaw : undefined);
         const signer = await createClientTronSigner(wallet, {
             network: selected.network,
             rpcUrl: args.rpcUrl || process.env.TRON_RPC_URL,
@@ -156,14 +163,20 @@ export async function createPaymentPayload(args) {
             allowanceMode: args.allowanceMode || process.env.X402_TRON_ALLOWANCE_MODE || "auto",
         });
         const client = new x402Client();
+        let gasfreeEstimate;
         if (selected.scheme === "exact_gasfree") {
-            registerExactGasFreeTronScheme(client, {
-                signer,
-                networks: [selected.network],
-                ...(args.gasfreeApiUrl || process.env.X402_GASFREE_API_URL
-                    ? { schemeOptions: { apiBaseUrls: { [selected.network]: args.gasfreeApiUrl || process.env.X402_GASFREE_API_URL } } }
-                    : {}),
+            const apiUrl = args.gasfreeApiUrl || process.env.X402_GASFREE_API_URL || getGasFreeApiBaseUrl(selected.network);
+            const scheme = new ExactGasFreeTronScheme(signer, {
+                apiClients: createGasFreeApiClients({ [selected.network]: apiUrl }),
             });
+            const total = await scheme.estimateCost(selected);
+            const amount = BigInt(selected.amount);
+            const fee = total - amount;
+            if (args.maxGasfreeFeeRaw !== undefined && fee > BigInt(args.maxGasfreeFeeRaw)) {
+                throw new Error(`estimated GasFree fee ${fee} exceeds --max-gasfree-fee limit ${args.maxGasfreeFeeRaw}`);
+            }
+            gasfreeEstimate = { fee: fee.toString(), total: total.toString() };
+            client.register(selected.network, scheme);
         }
         else if (selected.scheme === "exact") {
             client.register(selected.network, new ExactTronScheme(signer));
@@ -171,7 +184,8 @@ export async function createPaymentPayload(args) {
         else {
             throw new Error(`unsupported scheme ${selected.scheme} on ${selected.network}`);
         }
-        return client.createPaymentPayload(required);
+        const payload = await client.createPaymentPayload(required);
+        return { payload, ...(gasfreeEstimate ? { gasfreeEstimate } : {}) };
     }
     throw new Error(`unsupported network ${selected.network}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bankofai/x402-cli",
-  "version": "1.0.1-beta.1",
+  "version": "1.0.1-beta.10",
   "type": "module",
   "files": [
     "dist"
@@ -9,10 +9,12 @@
     "x402-cli": "dist/cli.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "clean": "node scripts/clean.mjs",
+    "build": "npm run clean && tsc -p tsconfig.json",
     "bundle:gateway": "node scripts/bundle-gateway.mjs",
     "prepack": "npm run build && npm run bundle:gateway",
     "test": "npm run build && node --test tests/*.test.mjs",
+    "test:package": "node scripts/test-package.mjs",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts"
   },
@@ -20,17 +22,19 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@bankofai/x402-core": "1.0.1-beta.4",
-    "@bankofai/x402-evm": "1.0.1-beta.4",
-    "@bankofai/x402-gateway": "1.0.1-beta.1",
-    "@bankofai/x402-tron": "1.0.1-beta.4",
+    "@bankofai/x402-core": "1.0.1",
+    "@bankofai/x402-evm": "1.0.1",
+    "@bankofai/x402-gateway": "1.0.1-beta.10",
+    "@bankofai/x402-tron": "1.0.1",
     "tronweb": "6.4.0",
-    "viem": "^2.55.0",
-    "yaml": "^2.8.2"
+    "viem": "^2.55.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "ws": "8.21.0"
   }
 }