@bankofai/x402-gateway 1.0.0 → 1.0.1-beta.2

package/README.md

@@ -3,12 +3,13 @@
 TypeScript reverse proxy for paid HTTP APIs. This version uses the npm
 TypeScript x402 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`
 
-Payment requirements are emitted as `scheme=exact`; supported stablecoins add
-`extra.assetTransferMethod=permit2`.
+Payment requirements support `scheme=exact` and TRON `scheme=exact_gasfree`.
+Exact requirements add `extra.assetTransferMethod=permit2`; GasFree requirements
+receive fee terms from the configured facilitator.
 
 ## Install
 
@@ -148,10 +149,11 @@ endpoints:
             - price_usd: 0.002
 ```
 
-`@bankofai/x402-*` 1.0.0 uses `scheme: exact` with
-`extra.assetTransferMethod: permit2` in the payment requirement. Older provider
-configs that say `exact_permit` are normalized at load time, but new provider
-configs should use `protocol: exact` and `asset_transfer_method: permit2`.
+`@bankofai/x402-*` 1.0.1-beta.2 uses `scheme: exact` with
+`extra.assetTransferMethod: permit2`, or TRON `scheme: exact_gasfree`. Older
+provider configs that say `exact_permit` are normalized to `exact`. For GasFree,
+set both `scheme` and `protocol` to `exact_gasfree`; the facilitator must support
+GasFree for the selected TRON network and token.
 
 Network aliases accepted:
 

package/dist/config.js

@@ -119,15 +119,31 @@ export function loadProvider(file) {
     };
 }
 function normalizePaymentProtocol(config, file) {
-    const raw = String(config.operator.protocol || config.operator.scheme || "exact").toLowerCase();
-    const normalized = raw.replace(/[-:\s]/g, "_");
-    if (!["exact", "exact_permit", "permit2", "exact_permit2"].includes(normalized)) {
-        throw new Error(`${file}: unsupported x402 protocol ${raw}; use exact + permit2`);
+    const rawSchemes = config.operator.schemes?.length
+        ? config.operator.schemes
+        : [config.operator.protocol || config.operator.scheme || "exact"];
+    const schemes = [...new Set(rawSchemes.map(value => {
+            const raw = String(value).toLowerCase();
+            const normalized = raw.replace(/[-:\s]/g, "_");
+            if (!["exact", "exact_gasfree", "exact_permit", "permit2", "exact_permit2"].includes(normalized)) {
+                throw new Error(`${file}: unsupported x402 protocol ${raw}; use exact or exact_gasfree`);
+            }
+            return normalized === "exact_gasfree" ? "exact_gasfree" : "exact";
+        }))];
+    if (schemes.includes("exact_gasfree") && !config.operator.network.startsWith("tron:")) {
+        throw new Error(`${file}: exact_gasfree is supported only on TRON networks`);
+    }
+    config.operator.schemes = schemes;
+    config.operator.scheme = schemes[0];
+    config.operator.protocol = schemes[0];
+    if (schemes.includes("exact")) {
+        config.operator.asset_transfer_method = "permit2";
+        config.operator.assetTransferMethod = "permit2";
+    }
+    else {
+        delete config.operator.asset_transfer_method;
+        delete config.operator.assetTransferMethod;
     }
-    config.operator.scheme = "exact";
-    config.operator.protocol = "exact";
-    config.operator.asset_transfer_method = "permit2";
-    config.operator.assetTransferMethod = "permit2";
 }
 export function loadProviders(providerPath) {
     const stat = fs.statSync(providerPath);
@@ -178,20 +194,23 @@ export function paymentRequirements(provider, price) {
     const network = normalizeNetwork(provider.operator.network);
     const symbols = provider.operator.currencies?.usd ?? ["USDT"];
     const payTo = provider.recipients?.[provider.operator.recipient]?.account ?? provider.operator.recipient;
-    return symbols.map(symbol => {
+    const schemes = provider.operator.schemes?.length
+        ? provider.operator.schemes.map(scheme => scheme === "exact_gasfree" ? "exact_gasfree" : "exact")
+        : [provider.operator.scheme === "exact_gasfree" ? "exact_gasfree" : "exact"];
+    return schemes.flatMap(scheme => symbols.map(symbol => {
         const token = getToken(network, symbol);
         const transferMethod = provider.operator.assetTransferMethod || provider.operator.asset_transfer_method || token.assetTransferMethod;
         const amount = toSmallestUnit(price, token.decimals);
         if (amount === "0")
             throw new Error(`positive price produced zero amount for ${symbol} on ${network}`);
         return {
-            scheme: "exact",
+            scheme,
             network,
             amount,
             asset: token.address,
             payTo,
             maxTimeoutSeconds: provider.operator.valid_for_seconds ?? 300,
-            extra: transferMethod === "permit2" ? { assetTransferMethod: "permit2" } : {},
+            extra: scheme === "exact" && transferMethod === "permit2" ? { assetTransferMethod: "permit2" } : {},
         };
-    });
+    }));
 }

package/dist/server.js

@@ -5,10 +5,12 @@ import { decodeSignature, encodeRequired, encodeResponse, headers, matchRequirem
 class HttpError extends Error {
     status;
     publicMessage;
-    constructor(status, publicMessage, message = publicMessage) {
+    responseHeaders;
+    constructor(status, publicMessage, message = publicMessage, responseHeaders = {}) {
         super(message);
         this.status = status;
         this.publicMessage = publicMessage;
+        this.responseHeaders = responseHeaders;
     }
 }
 class RequestTooLargeError extends HttpError {
@@ -52,7 +54,6 @@ const metrics = {
     paidRequests: 0,
     verifyFailures: 0,
     settleFailures: 0,
-    feeQuoteFailures: 0,
     upstreamFailures: 0,
 };
 async function readBody(request) {
@@ -89,7 +90,7 @@ async function fetchWithTimeout(url, init, timeoutMs, label = "upstream") {
 async function facilitatorPost(entry, path, body) {
     const headers = { "content-type": "application/json" };
     if (entry.facilitatorApiKey) {
-        headers.authorization = `Bearer ${entry.facilitatorApiKey}`;
+        headers["x-api-key"] = entry.facilitatorApiKey;
     }
     const response = await fetchWithTimeout(new URL(path, entry.facilitatorUrl), { method: "POST", headers, body: JSON.stringify(body) }, FACILITATOR_TIMEOUT_MS, "facilitator");
     const text = await response.text();
@@ -98,31 +99,43 @@ async function facilitatorPost(entry, path, body) {
         data = text ? JSON.parse(text) : {};
     }
     catch {
+        logFacilitatorFailure(entry, path, response, body, { code: "invalid_json" });
         throw new HttpError(502, "facilitator returned invalid response");
     }
-    if (!response.ok)
-        throw new HttpError(502, "facilitator request failed", `facilitator ${path} failed: ${response.status} ${text}`);
+    if (!response.ok) {
+        logFacilitatorFailure(entry, path, response, body, data);
+        if (response.status === 429) {
+            const retryAfter = response.headers.get("retry-after");
+            throw new HttpError(429, "facilitator rate limited", `facilitator ${path} rate limited`, retryAfter ? { "retry-after": retryAfter } : {});
+        }
+        throw new HttpError(502, "facilitator request failed", `facilitator ${path} failed: ${response.status}`);
+    }
     return data;
 }
-async function attachFeeQuotes(entry, requirements, context) {
-    try {
-        const quotes = await facilitatorPost(entry, "/fee_quote", {
-            paymentRequirements: requirements,
-            context,
-        });
-        const list = Array.isArray(quotes) ? quotes : quotes.quotes ?? quotes.fees ?? [];
-        return requirements.map(requirement => {
-            const quote = list.find((item) => item.scheme === requirement.scheme &&
-                item.network === requirement.network &&
-                String(item.asset).toLowerCase() === requirement.asset.toLowerCase());
-            return quote?.fee ? { ...requirement, extra: { ...requirement.extra, fee: quote.fee } } : requirement;
-        });
-    }
-    catch (error) {
-        metrics.feeQuoteFailures += 1;
-        console.warn("fee quote failed", error);
-        return requirements;
-    }
+function resourceUrl(url) {
+    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();
+}
+function logFacilitatorFailure(entry, path, response, body, data) {
+    const requirement = body?.paymentRequirements;
+    const nestedError = data?.error && typeof data.error === "object" ? data.error : undefined;
+    const message = nestedError?.message ?? data?.message ?? data?.detail ??
+        (typeof data?.error === "string" ? data.error : undefined);
+    console.error(JSON.stringify({
+        event: "facilitator_request_failed",
+        provider: entry.config.name,
+        endpoint: path,
+        status: response.status,
+        scheme: requirement?.scheme,
+        network: requirement?.network,
+        errorCode: nestedError?.code ?? data?.code,
+        errorMessage: typeof message === "string" ? message.slice(0, 200) : undefined,
+        retryAfter: response.headers.get("retry-after") ?? undefined,
+        cfRay: response.headers.get("cf-ray") ?? undefined,
+    }));
 }
 function isVerifySuccess(verify) {
     return verify?.valid === true || verify?.isValid === true;
@@ -265,7 +278,6 @@ export function createGatewayServer(providers) {
                     `x402_gateway_paid_requests_total ${metrics.paidRequests}`,
                     `x402_gateway_verify_failures_total ${metrics.verifyFailures}`,
                     `x402_gateway_settle_failures_total ${metrics.settleFailures}`,
-                    `x402_gateway_fee_quote_failures_total ${metrics.feeQuoteFailures}`,
                     `x402_gateway_upstream_failures_total ${metrics.upstreamFailures}`,
                     "",
                 ].join("\n"));
@@ -295,11 +307,11 @@ export function createGatewayServer(providers) {
             }
             const paymentHeader = request.headers[headers.signature.toLowerCase()];
             if (!paymentHeader || Array.isArray(paymentHeader)) {
-                const accepts = await attachFeeQuotes(entry, requirements);
+                const accepts = requirements;
                 const challenge = {
                     x402Version: 2,
                     error: "Payment required",
-                    resource: { url: url.pathname },
+                    resource: { url: resourceUrl(url) },
                     accepts,
                 };
                 json(response, 402, challenge, { [headers.required]: encodeRequired(challenge) });
@@ -348,7 +360,7 @@ export function createGatewayServer(providers) {
         }
         catch (error) {
             if (error instanceof HttpError) {
-                json(response, error.status, { error: error.publicMessage });
+                json(response, error.status, { error: error.publicMessage }, error.responseHeaders);
                 return;
             }
             console.error(error);

package/dist/tokens.js

@@ -1,9 +1,9 @@
 export const TOKENS = {
-    "tron:mainnet": {
+    "tron:0x2b6653dc": {
         USDT: { address: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", decimals: 6, name: "Tether USD", symbol: "USDT", assetTransferMethod: "permit2" },
         USDD: { address: "TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz", decimals: 18, name: "Decentralized USD", symbol: "USDD", assetTransferMethod: "permit2" },
     },
-    "tron:nile": {
+    "tron:0xcd8690dc": {
         USDT: { address: "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", decimals: 6, name: "Tether USD", symbol: "USDT", assetTransferMethod: "permit2" },
         USDD: { address: "TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK", decimals: 18, name: "Decentralized USD", symbol: "USDD", assetTransferMethod: "permit2" },
     },
@@ -17,9 +17,15 @@ export const TOKENS = {
 };
 export function normalizeNetwork(network) {
     return ({
-        "tron-mainnet": "tron:mainnet",
-        "tron-shasta": "tron:shasta",
-        "tron-nile": "tron:nile",
+        "tron-mainnet": "tron:0x2b6653dc",
+        "tron:mainnet": "tron:0x2b6653dc",
+        "mainnet": "tron:0x2b6653dc",
+        "tron-shasta": "tron:0x94a9059e",
+        "tron:shasta": "tron:0x94a9059e",
+        "shasta": "tron:0x94a9059e",
+        "tron-nile": "tron:0xcd8690dc",
+        "tron:nile": "tron:0xcd8690dc",
+        "nile": "tron:0xcd8690dc",
         "bsc-mainnet": "eip155:56",
         "bsc-testnet": "eip155:97",
     }[network] ?? network);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bankofai/x402-gateway",
-  "version": "1.0.0",
+  "version": "1.0.1-beta.2",
   "private": false,
   "type": "module",
   "files": [
@@ -22,9 +22,9 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@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.4",
+    "@bankofai/x402-evm": "1.0.1-beta.4",
+    "@bankofai/x402-tron": "1.0.1-beta.4",
     "yaml": "^2.8.2"
   },
   "devDependencies": {