@bankofai/x402-cli 1.0.1-beta.4 → 1.0.1-beta.6

package/README.md

@@ -13,6 +13,15 @@ from the payment token, so the payer does not need TRX.
 
 ## Install
 
+Install the CLI package:
+
+```bash
+npm install -g @bankofai/x402-cli
+x402-cli --version
+```
+
+For repository development:
+
 ```bash
 npm install
 npm run build
@@ -61,8 +70,8 @@ The server exposes:
 
 - `GET /health`
 - `GET /.well-known/x402`
-- `GET /pay` returns `402 Payment Required`
-- `POST /pay` verifies and settles with the facilitator
+- `/pay` returns `402 Payment Required` without a payment signature
+- The signed retry uses the same HTTP method, then verifies and settles with the facilitator
 
 ### Pay
 
@@ -75,6 +84,9 @@ node dist/cli.js pay http://127.0.0.1:4020/pay \
   --token USDT
 ```
 
+For automated or unfamiliar endpoints, set `--max-amount` or
+`--max-raw-amount` before allowing the CLI to sign a payment.
+
 Pay a TRON GasFree endpoint (the CLI normally selects this automatically from
 the server challenge):
 
@@ -89,7 +101,31 @@ node dist/cli.js pay https://api.example.com/pay \
 Use `--gasfree-api-url <url>` or `X402_GASFREE_API_URL` to override the SDK's
 default relayer endpoint.
 
+GasFree fees are separate from the advertised payment amount. Set a fee limit
+so the CLI estimates the relayer fee and rejects the payment before signing if
+the estimate is too high:
+
+```bash
+x402-cli pay https://api.example.com/pay \
+  --scheme exact_gasfree \
+  --max-amount 0.01 \
+  --max-gasfree-fee 0.5 \
+  --json
+```
+
+Use `--max-gasfree-fee-raw` to express the fee limit in the token's smallest
+unit. Successful and failed paid responses distinguish `settled` (payment
+completed) from `delivered` (HTTP business response succeeded). A settled
+upstream failure has `paid=true`, `settled=true`, and `delivered=false` and
+includes its transaction information.
+
 For EVM networks use `EVM_PRIVATE_KEY` or `PRIVATE_KEY`.
+Prefer environment variables over `--private-key` in shared environments,
+because command-line arguments may be visible to other local processes.
+
+If the gateway settles a payment but the upstream request fails, JSON error
+output includes `error.details.paymentResponse` for reconciliation. Do not retry
+such a request blindly; inspect the transaction and provider behavior first.
 
 ### Roundtrip
 

package/dist/cli.js

@@ -18,11 +18,13 @@ class CliError extends Error {
     code;
     hint;
     exitCode;
-    constructor(code, message, hint, exitCode = 1) {
+    details;
+    constructor(code, message, hint, exitCode = 1, details) {
         super(message);
         this.code = code;
         this.hint = hint;
         this.exitCode = exitCode;
+        this.details = details;
     }
 }
 function parseArgs(argv) {
@@ -144,6 +146,8 @@ function emit(args) {
         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(" ");
@@ -171,6 +175,7 @@ function classify(error) {
             code: error.code,
             message,
             hint: error.hint,
+            details: error.details,
         };
     }
     const lower = message.toLowerCase();
@@ -316,6 +321,8 @@ Options:
   --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
@@ -737,7 +744,7 @@ async function fetchWithTimeout(input, init = {}, timeout = DEFAULT_TIMEOUT_MS,
         return await fetch(input, { ...init, signal: controller.signal });
     }
     catch (error) {
-        if (error?.name === "AbortError")
+        if (error instanceof Error && error.name === "AbortError")
             throw new Error(`${label} timed out after ${timeout}ms`);
         throw error;
     }
@@ -1079,6 +1086,31 @@ function validateAmountLimits(selected, options) {
         }
     }
 }
+function gasfreeFeeLimitRaw(selected, options) {
+    const maxRaw = opt(options, "max-gasfree-fee-raw");
+    const maxHuman = opt(options, "max-gasfree-fee");
+    if (maxRaw && maxHuman) {
+        throw new CliError("INVALID_ARGUMENT", "--max-gasfree-fee and --max-gasfree-fee-raw are mutually exclusive", "Pass one GasFree fee limit.", 2);
+    }
+    if (selected.scheme !== "exact_gasfree") {
+        if (maxRaw || maxHuman)
+            throw new Error("GasFree fee limits require an exact_gasfree payment requirement");
+        return undefined;
+    }
+    if (maxRaw)
+        return assertRawAmount(maxRaw, "--max-gasfree-fee-raw");
+    if (!maxHuman)
+        return undefined;
+    const token = findTokenByAddress(selected.network, selected.asset);
+    const decimalsOption = opt(options, "decimals");
+    if (!token && decimalsOption === undefined) {
+        throw new Error("cannot evaluate --max-gasfree-fee for an unknown asset; pass --max-gasfree-fee-raw or --decimals");
+    }
+    const decimals = decimalsOption !== undefined ? Number(decimalsOption) : token.decimals;
+    if (!Number.isInteger(decimals) || decimals < 0)
+        throw new Error("--decimals must be a non-negative integer");
+    return toSmallestUnit(maxHuman, decimals);
+}
 async function serve(options) {
     const host = opt(options, "host", "127.0.0.1");
     const port = Number(opt(options, "port", "4020"));
@@ -1182,7 +1214,13 @@ function selectRequirement(accepts, options) {
         if (scheme && scheme !== req.scheme)
             return false;
         if (token) {
-            const tokenInfo = getToken(req.network, token);
+            let tokenInfo;
+            try {
+                tokenInfo = getToken(req.network, token);
+            }
+            catch {
+                return false;
+            }
             if (tokenInfo.address.toLowerCase() !== req.asset.toLowerCase())
                 return false;
         }
@@ -1225,6 +1263,7 @@ async function pay(url, options) {
     const required = decodeRequired(header);
     const selected = selectRequirement(required.accepts ?? [], options);
     validateAmountLimits(selected, options);
+    const maxGasfreeFeeRaw = gasfreeFeeLimitRaw(selected, options);
     if (options["dry-run"]) {
         emit({
             command: "client",
@@ -1240,16 +1279,17 @@ async function pay(url, options) {
         });
         return;
     }
-    const payload = await withSdkStdoutRedirect(outputMode(options) === "json", () => createPaymentPayload({
+    const creation = await withSdkStdoutRedirect(outputMode(options) === "json", () => createPaymentPayload({
         selected,
         resource: required.resource?.url ?? url,
         extensions: required.extensions,
         rpcUrl: opt(options, "rpc-url"),
         privateKey: opt(options, "private-key"),
         gasfreeApiUrl: opt(options, "gasfree-api-url"),
+        maxGasfreeFeeRaw,
     }));
     const retryHeaders = new Headers(baseHeaders);
-    retryHeaders.set(headers.signature, encodeSignature(payload));
+    retryHeaders.set(headers.signature, encodeSignature(creation.payload));
     const paid = await fetchWithTimeout(url, {
         method,
         headers: retryHeaders,
@@ -1257,16 +1297,26 @@ async function pay(url, options) {
     }, timeoutMs(options), `fetch ${url}`);
     const body = await responsePayload(paid);
     const paymentResponse = paid.headers.get(headers.response);
+    const settlement = paymentResponse ? decodeResponse(paymentResponse) : undefined;
+    const settled = settlement !== undefined;
     const result = {
         url,
         status: paid.status,
-        paid: paid.ok,
+        paid: settled,
+        settled,
+        delivered: paid.ok,
         response: body,
-        ...(paymentResponse ? { paymentResponse: decodeResponse(paymentResponse) } : {}),
+        ...(settlement !== undefined ? {
+            paymentResponse: settlement,
+            transaction: settlement?.transaction ?? settlement?.txHash ?? null,
+        } : {}),
+        ...(creation.gasfreeEstimate ? { gasfreeEstimate: creation.gasfreeEstimate } : {}),
     };
     if (!paid.ok) {
         const retryAfter = paid.headers.get("retry-after");
-        throw new Error(`HTTP ${paid.status} from ${url}${retryAfter ? ` (retry after ${retryAfter}s)` : ""}: ${typeof body === "string" ? body.slice(0, 500) : JSON.stringify(body).slice(0, 500)}`);
+        throw new CliError(paid.status === 429 ? "RATE_LIMITED" : "HTTP_ERROR", `HTTP ${paid.status} from ${url}${retryAfter ? ` (retry after ${retryAfter}s)` : ""}: ${typeof body === "string" ? body.slice(0, 500) : JSON.stringify(body).slice(0, 500)}`, paymentResponse
+            ? "The gateway reports that payment was settled; retain paymentResponse for support or reconciliation."
+            : "Inspect the HTTP response and retry only when it is safe to do so.", 1, result);
     }
     emit({
         command: "client",
@@ -1278,8 +1328,7 @@ async function pay(url, options) {
 }
 async function roundtrip(options) {
     const port = Number(opt(options, "port", "4020"));
-    serve(options);
-    await delay(500);
+    await serve(options);
     await pay(`http://127.0.0.1:${port}/pay`, options);
     process.exit(0);
 }

package/dist/gateway/config.js

@@ -104,15 +104,21 @@ export function loadProvider(file) {
     validateProvider(config, file);
     config.operator.network = normalizeNetwork(config.operator.network);
     normalizePaymentProtocol(config, file);
+    const facilitatorUrl = config.operator.facilitator_url ||
+        process.env.X402_FACILITATOR_URL ||
+        process.env.FACILITATOR_URL ||
+        "https://facilitator.bankofai.io";
+    assertHttpUrl(facilitatorUrl, `${file}: facilitator URL`);
+    const configuredApiKeyEnv = config.operator.facilitator_api_key_env;
+    if (configuredApiKeyEnv && !process.env[configuredApiKeyEnv]) {
+        throw new Error(`${file}: environment variable ${configuredApiKeyEnv} is not set`);
+    }
     return {
         config,
-        facilitatorUrl: config.operator.facilitator_url ||
-            process.env.X402_FACILITATOR_URL ||
-            process.env.FACILITATOR_URL ||
-            "https://facilitator.bankofai.io",
+        facilitatorUrl,
         facilitatorApiKey: config.operator.facilitator_api_key ||
-            (config.operator.facilitator_api_key_env
-                ? process.env[config.operator.facilitator_api_key_env]
+            (configuredApiKeyEnv
+                ? process.env[configuredApiKeyEnv]
                 : undefined) ||
             process.env.X402_FACILITATOR_API_KEY ||
             process.env.FACILITATOR_API_KEY,

package/dist/gateway/server.js

@@ -18,9 +18,20 @@ class RequestTooLargeError extends HttpError {
         super(413, "request body too large");
     }
 }
-const MAX_BODY_BYTES = Number(process.env.X402_GATEWAY_MAX_BODY_BYTES ?? 1_000_000);
-const FACILITATOR_TIMEOUT_MS = Number(process.env.X402_GATEWAY_FACILITATOR_TIMEOUT_MS ?? 10_000);
-const UPSTREAM_TIMEOUT_MS = Number(process.env.X402_GATEWAY_UPSTREAM_TIMEOUT_MS ?? 30_000);
+function positiveIntegerEnv(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "")
+        return fallback;
+    if (!/^\d+$/.test(raw))
+        throw new Error(`${name} must be a positive integer`);
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${name} must be a positive integer`);
+    return value;
+}
+const MAX_BODY_BYTES = positiveIntegerEnv("X402_GATEWAY_MAX_BODY_BYTES", 1_000_000);
+const FACILITATOR_TIMEOUT_MS = positiveIntegerEnv("X402_GATEWAY_FACILITATOR_TIMEOUT_MS", 10_000);
+const UPSTREAM_TIMEOUT_MS = positiveIntegerEnv("X402_GATEWAY_UPSTREAM_TIMEOUT_MS", 30_000);
 const STRIP_REQUEST_HEADERS = new Set([
     "host",
     "connection",
@@ -48,14 +59,22 @@ const STRIP_RESPONSE_HEADERS = new Set([
     "authorization",
     "proxy-authorization",
     "set-cookie",
+    "payment-required",
+    "x-payment-required",
+    "payment-signature",
+    "x-payment",
+    "payment-response",
+    "x-payment-response",
 ]);
-const metrics = {
-    requests: 0,
-    paidRequests: 0,
-    verifyFailures: 0,
-    settleFailures: 0,
-    upstreamFailures: 0,
-};
+function createMetrics() {
+    return {
+        requests: 0,
+        paidRequests: 0,
+        verifyFailures: 0,
+        settleFailures: 0,
+        upstreamFailures: 0,
+    };
+}
 async function readBody(request) {
     const chunks = [];
     let total = 0;
@@ -79,7 +98,7 @@ async function fetchWithTimeout(url, init, timeoutMs, label = "upstream") {
         return await fetch(url, { ...init, signal: controller.signal });
     }
     catch (error) {
-        if (error?.name === "AbortError")
+        if (error instanceof Error && error.name === "AbortError")
             throw new HttpError(504, `${label} request timed out`);
         throw error;
     }
@@ -112,12 +131,25 @@ async function facilitatorPost(entry, path, body) {
     }
     return data;
 }
-function resourceUrl(url) {
+function configuredPublicBaseUrl() {
+    const value = process.env.X402_GATEWAY_PUBLIC_BASE_URL?.trim();
+    if (!value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (!["http:", "https:"].includes(url.protocol))
+            throw new Error("unsupported protocol");
+        return `${value.replace(/\/+$/, "")}/`;
+    }
+    catch {
+        throw new Error("X402_GATEWAY_PUBLIC_BASE_URL must be a valid http(s) URL");
+    }
+}
+function resourceUrl(url, publicBaseUrl) {
     const path = `${url.pathname}${url.search}`;
-    const publicBaseUrl = process.env.X402_GATEWAY_PUBLIC_BASE_URL?.trim();
     if (!publicBaseUrl)
         return path;
-    return new URL(path, `${publicBaseUrl.replace(/\/+$/, "")}/`).toString();
+    return new URL(path, publicBaseUrl).toString();
 }
 function logFacilitatorFailure(entry, path, response, body, data) {
     const requirement = body?.paymentRequirements;
@@ -205,7 +237,7 @@ function upstreamUrl(entry, request, routePath) {
     }
     return upstream;
 }
-async function forward(entry, request, response, routePath, body, paymentResponse) {
+async function forward(metrics, entry, request, response, routePath, body, paymentResponse) {
     const upstream = upstreamUrl(entry, request, routePath);
     let upstreamResponse;
     try {
@@ -229,10 +261,13 @@ async function forward(entry, request, response, routePath, body, paymentRespons
     });
     if (paymentResponse)
         responseHeaders[headers.response] = encodeResponse(paymentResponse);
+    const responseBody = Buffer.from(await upstreamResponse.arrayBuffer());
     response.writeHead(upstreamResponse.status, responseHeaders);
-    response.end(Buffer.from(await upstreamResponse.arrayBuffer()));
+    response.end(responseBody);
 }
 export function createGatewayServer(providers) {
+    const publicBaseUrl = configuredPublicBaseUrl();
+    const metrics = createMetrics();
     return http.createServer(async (request, response) => {
         try {
             metrics.requests += 1;
@@ -302,7 +337,7 @@ export function createGatewayServer(providers) {
             const body = await readBody(request);
             const requirements = paymentRequirements(entry.config, priceUsd(endpoint, requestParams(url, body, request)));
             if (!requirements.length) {
-                await forward(entry, request, response, routePath, body);
+                await forward(metrics, entry, request, response, routePath, body);
                 return;
             }
             const paymentHeader = request.headers[headers.signature.toLowerCase()];
@@ -311,7 +346,7 @@ export function createGatewayServer(providers) {
                 const challenge = {
                     x402Version: 2,
                     error: "Payment required",
-                    resource: { url: resourceUrl(url) },
+                    resource: { url: resourceUrl(url, publicBaseUrl) },
                     accepts,
                 };
                 json(response, 402, challenge, { [headers.required]: encodeRequired(challenge) });
@@ -356,7 +391,20 @@ export function createGatewayServer(providers) {
                 return;
             }
             metrics.paidRequests += 1;
-            await forward(entry, request, response, routePath, body, settle);
+            try {
+                await forward(metrics, entry, request, response, routePath, body, settle);
+            }
+            catch (error) {
+                const status = error instanceof HttpError ? error.status : 502;
+                const extraHeaders = error instanceof HttpError ? error.responseHeaders : {};
+                json(response, status, {
+                    error: "upstream failed after payment settlement",
+                    settled: true,
+                }, {
+                    ...extraHeaders,
+                    [headers.response]: encodeResponse(settle),
+                });
+            }
         }
         catch (error) {
             if (error instanceof HttpError) {

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";
@@ -142,9 +142,10 @@ 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"]);
@@ -156,14 +157,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 +178,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.4",
+  "version": "1.0.1-beta.6",
   "type": "module",
   "files": [
     "dist"
@@ -22,7 +22,7 @@
   "dependencies": {
     "@bankofai/x402-core": "1.0.1-beta.4",
     "@bankofai/x402-evm": "1.0.1-beta.4",
-    "@bankofai/x402-gateway": "1.0.1-beta.4",
+    "@bankofai/x402-gateway": "1.0.1-beta.5",
     "@bankofai/x402-tron": "1.0.1-beta.4",
     "tronweb": "6.4.0",
     "viem": "^2.55.0",
@@ -32,5 +32,8 @@
     "@types/node": "^24.10.1",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "ws": "8.21.0"
   }
 }