@bankofai/x402-cli 1.0.1-beta.5 → 1.0.1-beta.7

package/README.md

@@ -3,9 +3,9 @@
 TypeScript command-line client for BankofAI x402 payments. This version uses
 the npm TypeScript SDK packages only:
 
-- `@bankofai/x402-core@1.0.1-beta.4`
-- `@bankofai/x402-evm@1.0.1-beta.4`
-- `@bankofai/x402-tron@1.0.1-beta.4`
+- `@bankofai/x402-core@1.0.1`
+- `@bankofai/x402-evm@1.0.1`
+- `@bankofai/x402-tron@1.0.1`
 
 Stablecoin payments support `scheme=exact` and TRON `scheme=exact_gasfree`.
 The GasFree flow lets the relayer pay network energy while deducting its fee
@@ -16,7 +16,7 @@ from the payment token, so the payer does not need TRX.
 Install the CLI package:
 
 ```bash
-npm install -g @bankofai/x402-cli
+npm install -g @bankofai/x402-cli@beta
 x402-cli --version
 ```
 
@@ -58,7 +58,7 @@ envelope with `ok`, `command`, `result`, or structured `error` fields.
 Start a local x402 paywall endpoint:
 
 ```bash
-node dist/cli.js serve \
+x402-cli serve \
   --pay-to <recipient> \
   --amount 0.0001 \
   --network tron:0xcd8690dc \
@@ -79,7 +79,7 @@ Pay an x402-protected URL:
 
 ```bash
 TRON_PRIVATE_KEY=<hex> \
-node dist/cli.js pay http://127.0.0.1:4020/pay \
+x402-cli pay http://127.0.0.1:4020/pay \
   --network tron:0xcd8690dc \
   --token USDT
 ```
@@ -92,7 +92,7 @@ the server challenge):
 
 ```bash
 TRON_PRIVATE_KEY=<hex> \
-node dist/cli.js pay https://api.example.com/pay \
+x402-cli pay https://api.example.com/pay \
   --network tron:0xcd8690dc \
   --token USDT \
   --scheme exact_gasfree
@@ -101,6 +101,24 @@ 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.
@@ -115,7 +133,7 @@ Start a temporary local server and immediately pay it:
 
 ```bash
 TRON_PRIVATE_KEY=<hex> \
-node dist/cli.js roundtrip \
+x402-cli roundtrip \
   --pay-to <recipient> \
   --amount 0.0001 \
   --network tron:0xcd8690dc \

package/dist/cli.js

@@ -321,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
@@ -1084,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"));
@@ -1236,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",
@@ -1251,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,
@@ -1268,12 +1297,20 @@ 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");

package/dist/gateway/server.js

@@ -173,6 +173,8 @@ function isVerifySuccess(verify) {
     return verify?.valid === true || verify?.isValid === true;
 }
 function isSettleSuccess(settle) {
+    if (settle?.success === false || settle?.settled === false)
+        return false;
     return (settle?.success === true ||
         settle?.settled === true ||
         (typeof settle?.transaction === "string" && settle.transaction.length > 0) ||

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.5",
+  "version": "1.0.1-beta.7",
   "type": "module",
   "files": [
     "dist"
@@ -20,10 +20,10 @@
     "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.5",
-    "@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.6",
+    "@bankofai/x402-tron": "1.0.1",
     "tronweb": "6.4.0",
     "viem": "^2.55.0",
     "yaml": "^2.8.2"