@bankofai/x402-cli 1.0.0 → 1.0.1-beta.0

package/README.md

@@ -3,12 +3,13 @@
 TypeScript command-line client for BankofAI x402 payments. This version uses
 the npm TypeScript SDK packages only:
 
-- `@bankofai/x402-core@1.0.0`
-- `@bankofai/x402-evm@1.0.0`
-- `@bankofai/x402-tron@1.0.0`
+- `@bankofai/x402-core@1.0.1-beta.2`
+- `@bankofai/x402-evm@1.0.1-beta.2`
+- `@bankofai/x402-tron@1.0.1-beta.2`
 
-Stablecoin payments use `scheme=exact` with
-`extra.assetTransferMethod=permit2`.
+Stablecoin payments support `scheme=exact` and TRON `scheme=exact_gasfree`.
+The GasFree flow lets the relayer pay network energy while deducting its fee
+from the payment token, so the payer does not need TRX.
 
 ## Install
 
@@ -74,6 +75,20 @@ node dist/cli.js pay http://127.0.0.1:4020/pay \
   --token USDT
 ```
 
+Pay a TRON GasFree endpoint (the CLI normally selects this automatically from
+the server challenge):
+
+```bash
+TRON_PRIVATE_KEY=<hex> \
+node dist/cli.js pay https://api.example.com/pay \
+  --network tron:nile \
+  --token USDT \
+  --scheme exact_gasfree
+```
+
+Use `--gasfree-api-url <url>` or `X402_GASFREE_API_URL` to override the SDK's
+default relayer endpoint.
+
 For EVM networks use `EVM_PRIVATE_KEY` or `PRIVATE_KEY`.
 
 ### Roundtrip
@@ -114,5 +129,6 @@ Pass a facilitator URL when needed:
 x402-cli serve --facilitator-url https://facilitator.bankofai.io ...
 ```
 
-CLI payment challenges and payload selection always emit `scheme: "exact"` for
-the SDK 1.0 Permit2 path.
+`serve --scheme exact_gasfree` advertises a TRON GasFree requirement. The
+configured facilitator must advertise and settle `exact_gasfree` for that
+network and token.

package/dist/cli.js

@@ -315,6 +315,7 @@ Options:
   --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-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
@@ -335,6 +336,7 @@ Options:
   --amount <amount>         Human-readable token amount (default: 0.0001)
   --raw-amount <amount>     Smallest-unit amount
   --network <caip2>         Payment network (default: tron:nile)
+  --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
@@ -476,7 +478,7 @@ function loadProviderFile(file) {
     const provider = expandDeep(readYaml(file));
     validateProvider(provider, file);
     provider.operator.network = normalizeNetwork(provider.operator.network);
-    provider.operator.scheme = "exact";
+    provider.operator.scheme = provider.operator.scheme ?? "exact";
     return provider;
 }
 function validateProvider(provider, file = "provider.yml") {
@@ -524,6 +526,9 @@ function providerPrice(endpoint) {
 function providerAssetTransferMethod(provider) {
     return provider.operator?.asset_transfer_method ?? provider.operator?.assetTransferMethod ?? "permit2";
 }
+function providerScheme(provider) {
+    return provider.operator?.scheme ?? "exact";
+}
 function providerCatalog(provider) {
     return {
         name: provider.name,
@@ -540,7 +545,7 @@ function providerCatalog(provider) {
             upstream_path: endpoint.path,
             description: endpoint.description ?? "",
             paid: providerPrice(endpoint) > 0 ? {
-                scheme: "exact",
+                scheme: providerScheme(provider),
                 network: normalizeNetwork(provider.operator.network),
                 currency: provider.operator.currencies?.usd?.[0] ?? "USDT",
                 price_usd: providerPrice(endpoint),
@@ -548,7 +553,7 @@ function providerCatalog(provider) {
             x402_routes: providerPrice(endpoint) > 0 ? [{
                     provider: provider.name,
                     network: normalizeNetwork(provider.operator.network),
-                    scheme: "exact",
+                    scheme: providerScheme(provider),
                     assetTransferMethod: providerAssetTransferMethod(provider),
                     url: `/providers/${provider.name}${endpoint.path}`,
                 }] : [],
@@ -964,6 +969,12 @@ async function catalogExportGateway(gatewayUrl, options) {
 }
 function buildRequirement(options) {
     const network = normalizeNetwork(opt(options, "network", "tron:nile"));
+    const scheme = opt(options, "scheme", "exact");
+    if (!["exact", "exact_gasfree"].includes(scheme))
+        throw new Error(`unsupported scheme ${scheme}`);
+    if (scheme === "exact_gasfree" && !network.startsWith("tron:")) {
+        throw new Error("exact_gasfree is supported only on TRON networks");
+    }
     const tokenSymbol = opt(options, "token", "USDT");
     const explicitAsset = opt(options, "asset");
     const registryToken = explicitAsset
@@ -986,13 +997,13 @@ function buildRequirement(options) {
     const assetAddress = explicitAsset ?? registryToken.address;
     const assetTransferMethod = registryToken?.assetTransferMethod ?? "permit2";
     return {
-        scheme: "exact",
+        scheme,
         network,
         amount,
         asset: assetAddress,
         payTo: opt(options, "pay-to") ?? opt(options, "payTo") ?? "",
         maxTimeoutSeconds: Number(opt(options, "valid-for-seconds", "300")),
-        extra: assetTransferMethod ? { assetTransferMethod } : {},
+        extra: scheme === "exact" && assetTransferMethod ? { assetTransferMethod } : {},
     };
 }
 async function facilitatorPost(baseUrl, path, body, options) {
@@ -1039,7 +1050,7 @@ function serveDaemon(argv, options) {
         command: "server",
         mode: outputMode(options),
         network: requirement.network,
-        scheme: "exact",
+        scheme: requirement.scheme,
         result: {
             pid: child.pid,
             pay_url: resourceUrl,
@@ -1092,7 +1103,7 @@ async function serve(options) {
             }
             if (pathname === "/.well-known/x402") {
                 response.writeHead(200, { "content-type": "application/json" });
-                response.end(JSON.stringify({ network: requirement.network, scheme: "exact", asset: requirement.asset, rawAmount: requirement.amount, amount: requirement.amount, payTo: requirement.payTo, pay_url: resourceUrl }));
+                response.end(JSON.stringify({ network: requirement.network, scheme: requirement.scheme, asset: requirement.asset, rawAmount: requirement.amount, amount: requirement.amount, payTo: requirement.payTo, pay_url: resourceUrl }));
                 return;
             }
             if (pathname !== "/pay") {
@@ -1139,7 +1150,7 @@ async function serve(options) {
                 "content-type": "application/json",
                 [headers.response]: encodeResponse(settle),
             });
-            response.end(JSON.stringify({ success: true, network: requirement.network, scheme: "exact", transaction: settle.transaction ?? settle.txHash ?? null }));
+            response.end(JSON.stringify({ success: true, network: requirement.network, scheme: requirement.scheme, transaction: settle.transaction ?? settle.txHash ?? null }));
         }
         catch (error) {
             response.writeHead(500, { "content-type": "application/json" });
@@ -1153,7 +1164,7 @@ async function serve(options) {
             emit({
                 command: "server",
                 network: requirement.network,
-                scheme: "exact",
+                scheme: requirement.scheme,
                 mode: outputMode(options),
                 result: { pay_url: resourceUrl, token: opt(options, "token", "USDT"), rawAmount: requirement.amount, pay_to: requirement.payTo },
             });
@@ -1213,7 +1224,7 @@ async function pay(url, options) {
         emit({
             command: "client",
             network: selected.network,
-            scheme: "exact",
+            scheme: selected.scheme,
             mode: outputMode(options),
             result: {
                 url,
@@ -1230,6 +1241,7 @@ async function pay(url, options) {
         extensions: required.extensions,
         rpcUrl: opt(options, "rpc-url"),
         privateKey: opt(options, "private-key"),
+        gasfreeApiUrl: opt(options, "gasfree-api-url"),
     }));
     const retryHeaders = new Headers(baseHeaders);
     retryHeaders.set(headers.signature, encodeSignature(payload));
@@ -1253,7 +1265,7 @@ async function pay(url, options) {
     emit({
         command: "client",
         network: selected.network,
-        scheme: "exact",
+        scheme: selected.scheme,
         mode: outputMode(options),
         result,
     });
@@ -1408,7 +1420,7 @@ function catalogPayAssets(target, options) {
         network: normalizeNetwork(provider.operator.network),
         currency: provider.operator.currencies?.usd?.[0] ?? "USDT",
         price_usd: providerPrice(endpoint),
-        scheme: "exact",
+        scheme: providerScheme(provider),
         assetTransferMethod: providerAssetTransferMethod(provider),
     })));
     emit({

package/dist/gateway/cli.js

@@ -65,17 +65,21 @@ function opt(options, key, fallback) {
 function flag(options, key) {
     return options[key] === true;
 }
-function version() {
+function rawHasFlag(argv, name, short) {
+    return argv.some(item => item === `--${name}` || item.startsWith(`--${name}=`) || (short ? item === short : false));
+}
+function readVersion() {
     try {
         const url = new URL("../package.json", import.meta.url);
-        return String(JSON.parse(fs.readFileSync(url, "utf8")).version ?? "0.0.0");
+        const version = JSON.parse(fs.readFileSync(url, "utf8")).version;
+        return typeof version === "string" && version ? version : undefined;
     }
     catch {
-        return "0.0.0";
+        return undefined;
     }
 }
 function help() {
-    return `x402-gateway ${version()}
+    return `x402-gateway ${readVersion() ?? "unknown"}
 
 Usage:
   x402-gateway start --providers <dir> [options]
@@ -105,6 +109,9 @@ Examples:
 `;
 }
 function providerPath(options) {
+    if (opt(options, "provider") && opt(options, "providers")) {
+        throw new CliError("Options --provider and --providers are mutually exclusive.");
+    }
     const source = opt(options, "providers", opt(options, "provider", process.env.X402_GATEWAY_PROVIDERS_DIR));
     if (!source)
         throw new CliError("No provider source configured. Use --provider <file> or --providers <dir>.");
@@ -120,25 +127,56 @@ function parsePort(value) {
     }
     return port;
 }
+function parseHost(value) {
+    const host = value ?? process.env.X402_GATEWAY_HOST ?? "127.0.0.1";
+    if (!host.trim())
+        throw new CliError("Invalid --host; expected a non-empty host.");
+    return host;
+}
+function listenErrorMessage(error, host, port) {
+    const err = error;
+    if (err?.code === "EADDRINUSE")
+        return `Port ${port} is already in use on ${host}. Choose another --port or stop the existing process.`;
+    if (err?.code === "EADDRNOTAVAIL")
+        return `Host ${host} is not available on this machine. Use --host 127.0.0.1 for local runs or --host 0.0.0.0 in containers.`;
+    return error instanceof Error ? error.message : String(error);
+}
 function publicHost(host) {
     return host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
 }
-function printStartup(options, host, port, providers) {
+function localUrls(host, port) {
+    const base = `http://${publicHost(host)}:${port}`;
+    return {
+        base,
+        health: `${base}/__402/health`,
+        ready: `${base}/__402/ready`,
+    };
+}
+function printStartup(options, source, host, port, providers) {
     if (flag(options, "quiet"))
         return;
+    const urls = localUrls(host, port);
     if (flag(options, "json")) {
-        process.stdout.write(JSON.stringify({ ok: true, host, port, providers }, null, 2) + "\n");
+        process.stdout.write(JSON.stringify({ ok: true, source, host, port, count: providers.length, providers, health: urls.health, ready: urls.ready }, null, 2) + "\n");
         return;
     }
-    const base = `http://${publicHost(host)}:${port}`;
-    process.stdout.write(`x402-gateway listening on ${base}\n`);
+    process.stdout.write(`x402-gateway listening on ${urls.base}\n`);
     process.stdout.write(`providers: ${providers.length} loaded\n`);
-    process.stdout.write(`health: ${base}/__402/health\n`);
-    process.stdout.write(`ready: ${base}/__402/ready\n`);
+    process.stdout.write(`health: ${urls.health}\n`);
+    process.stdout.write(`ready: ${urls.ready}\n`);
+}
+function loadProvidersForCli(action, source) {
+    try {
+        return loadProviders(source);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`failed to load providers from ${source} for ${action}: ${message}`);
+    }
 }
 function check(options) {
     const source = providerPath(options);
-    const providers = loadProviders(source);
+    const providers = loadProvidersForCli("check", source);
     const summary = [...providers.values()].map(entry => ({
         name: entry.config.name,
         network: entry.config.operator.network,
@@ -148,6 +186,8 @@ function check(options) {
         process.stdout.write(JSON.stringify({ ok: true, source, count: summary.length, providers: summary }, null, 2) + "\n");
         return;
     }
+    if (flag(options, "quiet"))
+        return;
     process.stdout.write(`ok: ${summary.length} provider${summary.length === 1 ? "" : "s"} loaded from ${source}\n`);
     for (const item of summary) {
         process.stdout.write(`  ${item.name} (${item.network}) endpoints=${item.endpoints}\n`);
@@ -155,22 +195,29 @@ function check(options) {
 }
 async function start(options) {
     const source = providerPath(options);
-    const host = opt(options, "host", process.env.X402_GATEWAY_HOST || "127.0.0.1");
+    const host = parseHost(opt(options, "host"));
     const port = parsePort(opt(options, "port"));
-    const providers = loadProviders(source);
+    const providers = loadProvidersForCli("start", source);
     const server = createGatewayServer(providers);
     await new Promise((resolve, reject) => {
-        server.once("error", reject);
+        server.once("error", error => reject(new Error(listenErrorMessage(error, host, port))));
         server.listen(port, host, () => {
             server.off("error", reject);
-            printStartup(options, host, port, [...providers.keys()]);
+            printStartup(options, source, host, port, [...providers.keys()]);
             resolve();
         });
     });
     const shutdown = (signal) => {
         if (!flag(options, "quiet") && !flag(options, "json"))
             process.stderr.write(`received ${signal}, shutting down...\n`);
+        const timeout = setTimeout(() => {
+            if (!flag(options, "quiet") && !flag(options, "json"))
+                process.stderr.write("server close timed out; exiting\n");
+            process.exit(1);
+        }, 10_000);
+        timeout.unref();
         server.close(() => {
+            clearTimeout(timeout);
             if (!flag(options, "quiet") && !flag(options, "json"))
                 process.stderr.write("server closed\n");
             process.exit(0);
@@ -186,7 +233,10 @@ async function main() {
         return;
     }
     if (flag(parsed.options, "version")) {
-        process.stdout.write(`${version()}\n`);
+        const version = readVersion();
+        if (!version)
+            throw new Error("Unable to read package version.");
+        process.stdout.write(`${version}\n`);
         return;
     }
     if (parsed.command === "check")
@@ -195,22 +245,17 @@ async function main() {
         await start(parsed.options);
 }
 main().catch(error => {
-    const parsed = (() => {
-        try {
-            return parseArgs(process.argv.slice(2));
-        }
-        catch {
-            return { options: {} };
-        }
-    })();
+    const argv = process.argv.slice(2);
+    const json = rawHasFlag(argv, "json");
+    const debug = rawHasFlag(argv, "debug");
     const message = error instanceof Error ? error.message : String(error);
-    if (flag(parsed.options, "json")) {
+    if (json) {
         process.stdout.write(JSON.stringify({ ok: false, error: { message } }, null, 2) + "\n");
     }
     else {
         process.stderr.write(`x402-gateway: ${message}\n`);
         process.stderr.write("Run `x402-gateway --help` for usage.\n");
-        if (flag(parsed.options, "debug") && error instanceof Error && error.stack) {
+        if (debug && error instanceof Error && error.stack) {
             process.stderr.write(`${error.stack}\n`);
         }
     }

package/dist/x402.js

@@ -2,6 +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 { createPublicClient, http } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { TronWeb } from "tronweb";
@@ -33,6 +34,8 @@ export function decodeResponse(value) {
     return decodePaymentResponseHeader(value);
 }
 export function ensurePermit2(requirement) {
+    if (requirement.scheme !== "exact")
+        return requirement;
     const extra = { ...(requirement.extra ?? {}) };
     if (!extra.assetTransferMethod) {
         const token = findTokenByAddress(requirement.network, requirement.asset);
@@ -40,7 +43,7 @@ export function ensurePermit2(requirement) {
             extra.assetTransferMethod = "permit2";
         }
     }
-    return { ...requirement, scheme: "exact", extra };
+    return { ...requirement, extra };
 }
 export function paymentRequired(requirement, resource, extensions) {
     return {
@@ -131,6 +134,8 @@ export async function createPaymentPayload(args) {
     const selected = ensurePermit2(args.selected);
     const required = paymentRequired(selected, args.resource, args.extensions);
     if (selected.network.startsWith("eip155:")) {
+        if (selected.scheme !== "exact")
+            throw new Error(`unsupported scheme ${selected.scheme} on ${selected.network}`);
         const privateKey = privateKeyFrom(["EVM_PRIVATE_KEY", "AGENT_WALLET_PRIVATE_KEY", "PRIVATE_KEY"], args.privateKey, ["evm_client", "payer", "default"]);
         const account = privateKeyToAccount(privateKey);
         const rpcUrl = evmRpcUrl(selected.network, args.rpcUrl);
@@ -150,9 +155,23 @@ export async function createPaymentPayload(args) {
             apiKey: args.apiKey || process.env.TRON_GRID_API_KEY,
             allowanceMode: args.allowanceMode || process.env.X402_TRON_ALLOWANCE_MODE || "auto",
         });
-        return new x402Client()
-            .register(selected.network, new ExactTronScheme(signer))
-            .createPaymentPayload(required);
+        const client = new x402Client();
+        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 } } }
+                    : {}),
+            });
+        }
+        else if (selected.scheme === "exact") {
+            client.register(selected.network, new ExactTronScheme(signer));
+        }
+        else {
+            throw new Error(`unsupported scheme ${selected.scheme} on ${selected.network}`);
+        }
+        return client.createPaymentPayload(required);
     }
     throw new Error(`unsupported network ${selected.network}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bankofai/x402-cli",
-  "version": "1.0.0",
+  "version": "1.0.1-beta.0",
   "type": "module",
   "files": [
     "dist"
@@ -20,10 +20,10 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@bankofai/x402-core": "1.0.0",
-    "@bankofai/x402-evm": "1.0.0",
+    "@bankofai/x402-core": "1.0.1-beta.2",
+    "@bankofai/x402-evm": "1.0.1-beta.2",
     "@bankofai/x402-gateway": "^1.0.0",
-    "@bankofai/x402-tron": "1.0.0",
+    "@bankofai/x402-tron": "1.0.1-beta.2",
     "tronweb": "6.4.0",
     "viem": "^2.55.0",
     "yaml": "^2.8.2"