@bankofai/x402-gateway 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BANK OF AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# x402 Gateway
+
+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`
+
+Payment requirements are emitted as `scheme=exact`; supported stablecoins add
+`extra.assetTransferMethod=permit2`.
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+## Run
+
+Start from a single provider file:
+
+```bash
+node dist/cli.js --provider examples/provider.yml --host 127.0.0.1 --port 4020
+```
+
+Start from a providers directory:
+
+```bash
+node dist/cli.js --providers providers --host 0.0.0.0 --port 4020
+```
+
+Health check:
+
+```bash
+curl http://127.0.0.1:4020/__402/health
+```
+
+Paid provider path:
+
+```bash
+curl -i http://127.0.0.1:4020/providers/tron-nile-usdt/v1/ping
+```
+
+If the endpoint has metering, the gateway returns `402 Payment Required` with a
+`PAYMENT-REQUIRED` header. After the client retries with `PAYMENT-SIGNATURE`,
+the gateway verifies and settles with the facilitator, then forwards to the
+configured upstream.
+
+## Provider Config
+
+Provider files stay in YAML:
+
+```yaml
+name: tron-nile-usdt
+forward_url: ${X402_PROVIDER_FORWARD_URL}
+
+routing:
+  auth:
+    method: header
+    key: Authorization
+    prefix: "Bearer "
+    value_from_env: X402_PROVIDER_API_TOKEN
+
+operator:
+  network: tron-nile
+  currencies:
+    usd: ["USDT"]
+  recipient: ${X402_PROVIDER_RECIPIENT_TRON}
+  scheme: exact
+  protocol: exact
+  asset_transfer_method: permit2
+  facilitator_url: ${X402_FACILITATOR_URL}
+  facilitator_api_key_env: X402_FACILITATOR_API_KEY
+  valid_for_seconds: 300
+
+endpoints:
+  - method: GET
+    path: /v1/ping
+    metering:
+      dimensions:
+        - tiers:
+            - 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`.
+
+Network aliases accepted:
+
+- `tron-mainnet` -> `tron:mainnet`
+- `tron-nile` -> `tron:nile`
+- `bsc-mainnet` -> `eip155:56`
+- `bsc-testnet` -> `eip155:97`
+
+## Environment
+
+```bash
+X402_FACILITATOR_URL=https://facilitator.bankofai.io
+X402_FACILITATOR_API_KEY=<optional-facilitator-api-key>
+X402_PROVIDER_FORWARD_URL=<upstream-base-url>
+X402_PROVIDER_RECIPIENT_TRON=<recipient-T-address>
+X402_PROVIDER_API_TOKEN=<upstream-token>
+```

package/dist/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { loadProviders } from "./config.js";
+import { createGatewayServer } from "./server.js";
+function parseArgs(argv) {
+    const options = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const item = argv[i];
+        if (!item.startsWith("--"))
+            continue;
+        const key = item.slice(2);
+        const next = argv[i + 1];
+        if (!next || next.startsWith("--"))
+            options[key] = true;
+        else {
+            options[key] = next;
+            i += 1;
+        }
+    }
+    return options;
+}
+function opt(options, key, fallback) {
+    const value = options[key];
+    return typeof value === "string" ? value : fallback;
+}
+const options = parseArgs(process.argv.slice(2));
+const providersPath = opt(options, "providers", opt(options, "provider", process.env.X402_GATEWAY_PROVIDERS_DIR || "/app/providers"));
+const host = opt(options, "host", process.env.X402_GATEWAY_HOST || "0.0.0.0");
+const port = Number(opt(options, "port", process.env.PORT || "8080"));
+const providers = loadProviders(providersPath);
+const server = createGatewayServer(providers);
+server.listen(port, host, () => {
+    process.stdout.write(JSON.stringify({ ok: true, host, port, providers: [...providers.keys()] }, null, 2) + "\n");
+});

package/dist/config.js

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { getToken, normalizeNetwork, toSmallestUnit } from "./tokens.js";
+function expandEnv(value) {
+    return value.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? "");
+}
+function expandDeep(value) {
+    if (typeof value === "string")
+        return expandEnv(value);
+    if (Array.isArray(value))
+        return value.map(expandDeep);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, expandDeep(item)]));
+    }
+    return value;
+}
+function assertString(value, name) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${name} is required`);
+}
+function validateProvider(config, file) {
+    assertString(config.name, `${file}: name`);
+    assertString(config.forward_url, `${file}: forward_url`);
+    assertString(config.operator?.network, `${file}: operator.network`);
+    assertString(config.operator?.recipient, `${file}: operator.recipient`);
+    if (!config.endpoints?.length)
+        throw new Error(`${file}: endpoints must contain at least one endpoint`);
+    const seen = new Set();
+    for (const [index, endpoint] of config.endpoints.entries()) {
+        assertString(endpoint.method, `${file}: endpoints[${index}].method`);
+        assertString(endpoint.path, `${file}: endpoints[${index}].path`);
+        if (!endpoint.path.startsWith("/"))
+            throw new Error(`${file}: endpoint path must start with /`);
+        const method = endpoint.method.toUpperCase();
+        if (!["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].includes(method)) {
+            throw new Error(`${file}: unsupported endpoint method ${endpoint.method}`);
+        }
+        const key = `${method} ${endpoint.path}`;
+        if (seen.has(key))
+            throw new Error(`${file}: duplicate endpoint ${key}`);
+        seen.add(key);
+        for (const [tierIndex, tier] of (endpoint.metering?.dimensions?.[0]?.tiers ?? []).entries()) {
+            if (typeof tier.price_usd !== "number" || tier.price_usd < 0) {
+                throw new Error(`${file}: endpoints[${index}].metering tier ${tierIndex} price_usd must be >= 0`);
+            }
+        }
+    }
+}
+export function loadProvider(file) {
+    const config = expandDeep(YAML.parse(fs.readFileSync(file, "utf8")));
+    validateProvider(config, file);
+    config.operator.network = normalizeNetwork(config.operator.network);
+    normalizePaymentProtocol(config, file);
+    return {
+        config,
+        facilitatorUrl: config.operator.facilitator_url ||
+            process.env.X402_FACILITATOR_URL ||
+            process.env.FACILITATOR_URL ||
+            "https://facilitator.bankofai.io",
+        facilitatorApiKey: config.operator.facilitator_api_key ||
+            (config.operator.facilitator_api_key_env
+                ? process.env[config.operator.facilitator_api_key_env]
+                : undefined) ||
+            process.env.X402_FACILITATOR_API_KEY ||
+            process.env.FACILITATOR_API_KEY,
+    };
+}
+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`);
+    }
+    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);
+    const files = stat.isDirectory()
+        ? fs.readdirSync(providerPath, { recursive: true })
+            .map(item => path.join(providerPath, String(item)))
+            .filter(item => item.endsWith("provider.yml") || item.endsWith("provider.yaml"))
+        : [providerPath];
+    const entries = files.map(file => {
+        const entry = loadProvider(file);
+        return [entry.config.name, entry];
+    });
+    const names = new Set();
+    for (const [name] of entries) {
+        if (names.has(name))
+            throw new Error(`duplicate provider name: ${name}`);
+        names.add(name);
+    }
+    return new Map(entries);
+}
+export function endpointFor(provider, method, routePath) {
+    return provider.endpoints?.find(endpoint => endpoint.method.toUpperCase() === method.toUpperCase() && pathMatches(endpoint.path, routePath));
+}
+function pathMatches(template, routePath) {
+    const templateParts = template.split("/").filter(Boolean);
+    const routeParts = routePath.split("/").filter(Boolean);
+    if (templateParts.length !== routeParts.length)
+        return false;
+    return templateParts.every((part, index) => {
+        if (part.startsWith("{") && part.endsWith("}"))
+            return routeParts[index].length > 0;
+        return part === routeParts[index];
+    });
+}
+export function priceUsd(endpoint, params = {}) {
+    const variant = endpoint?.metering?.variants?.find(item => params[item.param] === item.value);
+    return (variant?.dimensions ?? endpoint?.metering?.dimensions)?.[0]?.tiers?.[0]?.price_usd ?? 0;
+}
+export function paymentRequirements(provider, price) {
+    if (price <= 0)
+        return [];
+    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 token = getToken(network, symbol);
+        const transferMethod = provider.operator.assetTransferMethod || provider.operator.asset_transfer_method || token.assetTransferMethod;
+        return {
+            scheme: "exact",
+            network,
+            amount: toSmallestUnit(price, token.decimals),
+            asset: token.address,
+            payTo,
+            maxTimeoutSeconds: provider.operator.valid_for_seconds ?? 300,
+            extra: transferMethod === "permit2" ? { assetTransferMethod: "permit2" } : {},
+        };
+    });
+}

package/dist/server.js

@@ -0,0 +1,249 @@
+import http from "node:http";
+import { URL } from "node:url";
+import { endpointFor, paymentRequirements, priceUsd } from "./config.js";
+import { decodeSignature, encodeRequired, encodeResponse, headers, matchRequirement } from "./x402.js";
+const metrics = {
+    requests: 0,
+    paidRequests: 0,
+    verifyFailures: 0,
+    settleFailures: 0,
+    upstreamFailures: 0,
+};
+async function readBody(request) {
+    const chunks = [];
+    for await (const chunk of request)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks);
+}
+function json(response, status, body, extraHeaders = {}) {
+    response.writeHead(status, { "content-type": "application/json", ...extraHeaders });
+    response.end(JSON.stringify(body));
+}
+async function facilitatorPost(entry, path, body) {
+    const headers = { "content-type": "application/json" };
+    if (entry.facilitatorApiKey) {
+        headers.authorization = `Bearer ${entry.facilitatorApiKey}`;
+    }
+    const response = await fetch(new URL(path, entry.facilitatorUrl), {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    const data = text ? JSON.parse(text) : {};
+    if (!response.ok)
+        throw new Error(`facilitator ${path} failed: ${response.status} ${text}`);
+    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 {
+        return requirements;
+    }
+}
+function isAdminAllowed(request) {
+    const token = process.env.X402_GATEWAY_ADMIN_TOKEN;
+    if (!token)
+        return true;
+    const auth = request.headers.authorization ?? "";
+    return auth === `Bearer ${token}`;
+}
+function requestParams(url, body, request) {
+    const params = {};
+    url.searchParams.forEach((value, key) => { params[key] = value; });
+    const contentType = String(request.headers["content-type"] ?? "").split(";", 1)[0].toLowerCase();
+    try {
+        if (body.length && contentType === "application/json") {
+            const parsed = JSON.parse(body.toString("utf8"));
+            if (parsed && typeof parsed === "object") {
+                for (const [key, value] of Object.entries(parsed)) {
+                    if (["string", "number", "boolean"].includes(typeof value))
+                        params[key] = String(value);
+                }
+            }
+        }
+        else if (body.length && contentType === "application/x-www-form-urlencoded") {
+            new URLSearchParams(body.toString("utf8")).forEach((value, key) => { params[key] = value; });
+        }
+    }
+    catch {
+        // Metering variants are advisory; malformed bodies just do not add params.
+    }
+    return params;
+}
+function upstreamHeaders(request, entry) {
+    const headersOut = new Headers();
+    for (const [key, value] of Object.entries(request.headers)) {
+        if (!value)
+            continue;
+        const lower = key.toLowerCase();
+        if (["host", "connection", "content-length", "authorization", "payment-signature"].includes(lower))
+            continue;
+        headersOut.set(key, Array.isArray(value) ? value.join(",") : value);
+    }
+    const auth = entry.config.routing?.auth;
+    if (auth) {
+        const value = auth.value ?? (auth.value_from_env ? process.env[auth.value_from_env] : undefined);
+        if (value && ["header", "access_token", "oauth2", undefined].includes(auth.method)) {
+            headersOut.set(auth.key ?? "Authorization", `${auth.prefix ?? ""}${value}`);
+        }
+    }
+    return headersOut;
+}
+function upstreamUrl(entry, request, routePath) {
+    const sourceUrl = new URL(request.url ?? "/", "http://local");
+    const upstream = new URL(routePath + (sourceUrl.search || ""), entry.config.forward_url);
+    const auth = entry.config.routing?.auth;
+    const value = auth?.value ?? (auth?.value_from_env ? process.env[auth.value_from_env] : undefined);
+    if (auth?.method === "query_param" && value) {
+        upstream.searchParams.set(auth.param ?? auth.key ?? "api_key", value);
+    }
+    return upstream;
+}
+async function forward(entry, request, response, routePath, body, paymentResponse) {
+    const upstream = upstreamUrl(entry, request, routePath);
+    const upstreamResponse = await fetch(upstream, {
+        method: request.method,
+        headers: upstreamHeaders(request, entry),
+        body: ["GET", "HEAD"].includes(request.method ?? "GET") ? undefined : new Uint8Array(body),
+    });
+    const responseHeaders = {};
+    upstreamResponse.headers.forEach((value, key) => {
+        if (!["connection", "transfer-encoding", "content-encoding", "content-length"].includes(key.toLowerCase())) {
+            responseHeaders[key] = value;
+        }
+    });
+    if (paymentResponse)
+        responseHeaders[headers.response] = encodeResponse(paymentResponse);
+    response.writeHead(upstreamResponse.status, responseHeaders);
+    response.end(Buffer.from(await upstreamResponse.arrayBuffer()));
+}
+export function createGatewayServer(providers) {
+    return http.createServer(async (request, response) => {
+        try {
+            metrics.requests += 1;
+            const url = new URL(request.url ?? "/", "http://local");
+            if (url.pathname === "/__402/health") {
+                json(response, 200, { ok: true, providers: providers.size });
+                return;
+            }
+            if (url.pathname === "/__402/ready") {
+                json(response, 200, { ok: true, providers: providers.size });
+                return;
+            }
+            if (url.pathname === "/__402/providers") {
+                if (!isAdminAllowed(request))
+                    return json(response, 401, { error: "unauthorized" });
+                json(response, 200, { providers: [...providers.values()].map(entry => ({
+                        name: entry.config.name,
+                        title: entry.config.title,
+                        network: entry.config.operator.network,
+                        facilitatorUrl: entry.facilitatorUrl,
+                        endpoints: entry.config.endpoints?.length ?? 0,
+                    })) });
+                return;
+            }
+            if (url.pathname === "/__402/endpoints") {
+                if (!isAdminAllowed(request))
+                    return json(response, 401, { error: "unauthorized" });
+                json(response, 200, { endpoints: [...providers.values()].flatMap(entry => (entry.config.endpoints ?? []).map(endpoint => ({
+                        provider: entry.config.name,
+                        method: endpoint.method,
+                        path: endpoint.path,
+                        priceUsd: priceUsd(endpoint),
+                        network: entry.config.operator.network,
+                    }))) });
+                return;
+            }
+            if (url.pathname === "/metrics") {
+                response.writeHead(200, { "content-type": "text/plain; version=0.0.4" });
+                response.end([
+                    `x402_gateway_requests_total ${metrics.requests}`,
+                    `x402_gateway_paid_requests_total ${metrics.paidRequests}`,
+                    `x402_gateway_verify_failures_total ${metrics.verifyFailures}`,
+                    `x402_gateway_settle_failures_total ${metrics.settleFailures}`,
+                    `x402_gateway_upstream_failures_total ${metrics.upstreamFailures}`,
+                    "",
+                ].join("\n"));
+                return;
+            }
+            const match = url.pathname.match(/^\/providers\/([^/]+)(\/.*)$/);
+            if (!match) {
+                json(response, 404, { error: "not found" });
+                return;
+            }
+            const entry = providers.get(match[1]);
+            if (!entry) {
+                json(response, 404, { error: "provider not found" });
+                return;
+            }
+            const routePath = match[2];
+            const endpoint = endpointFor(entry.config, request.method ?? "GET", routePath);
+            if (!endpoint) {
+                json(response, 404, { error: "endpoint not found" });
+                return;
+            }
+            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);
+                return;
+            }
+            const paymentHeader = request.headers[headers.signature.toLowerCase()];
+            if (!paymentHeader || Array.isArray(paymentHeader)) {
+                const accepts = await attachFeeQuotes(entry, requirements);
+                const challenge = {
+                    x402Version: 2,
+                    error: "Payment required",
+                    resource: { url: url.pathname },
+                    accepts,
+                };
+                json(response, 402, challenge, { [headers.required]: encodeRequired(challenge) });
+                return;
+            }
+            const payload = decodeSignature(paymentHeader);
+            const requirement = requirements.find(item => matchRequirement(payload, item));
+            if (!requirement) {
+                json(response, 400, { error: "payment does not match any requirement" });
+                return;
+            }
+            const verify = await facilitatorPost(entry, "/verify", {
+                paymentPayload: payload,
+                paymentRequirements: requirement,
+            });
+            if (verify?.valid === false || verify?.isValid === false) {
+                metrics.verifyFailures += 1;
+                json(response, 400, { error: "payment verification failed", verify });
+                return;
+            }
+            let settle;
+            try {
+                settle = await facilitatorPost(entry, "/settle", {
+                    paymentPayload: payload,
+                    paymentRequirements: requirement,
+                });
+            }
+            catch (error) {
+                metrics.settleFailures += 1;
+                throw error;
+            }
+            metrics.paidRequests += 1;
+            await forward(entry, request, response, routePath, body, settle);
+        }
+        catch (error) {
+            json(response, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+}

package/dist/tokens.js

@@ -0,0 +1,38 @@
+export const TOKENS = {
+    "tron:mainnet": {
+        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": {
+        USDT: { address: "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", decimals: 6, name: "Tether USD", symbol: "USDT", assetTransferMethod: "permit2" },
+        USDD: { address: "TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK", decimals: 18, name: "Decentralized USD", symbol: "USDD", assetTransferMethod: "permit2" },
+    },
+    "eip155:56": {
+        USDT: { address: "0x55d398326f99059fF775485246999027B3197955", decimals: 18, name: "Tether USD", symbol: "USDT", assetTransferMethod: "permit2" },
+    },
+    "eip155:97": {
+        USDT: { address: "0x337610d27c682E347C9cD60BD4b3b107C9d34dDd", decimals: 18, name: "Tether USD", symbol: "USDT", assetTransferMethod: "permit2" },
+        USDC: { address: "0x64544969ed7EBf5f083679233325356EbE738930", decimals: 18, name: "USD Coin", symbol: "USDC", assetTransferMethod: "permit2" },
+    },
+};
+export function normalizeNetwork(network) {
+    return ({
+        "tron-mainnet": "tron:mainnet",
+        "tron-shasta": "tron:shasta",
+        "tron-nile": "tron:nile",
+        "bsc-mainnet": "eip155:56",
+        "bsc-testnet": "eip155:97",
+    }[network] ?? network);
+}
+export function getToken(network, symbol) {
+    const normalized = normalizeNetwork(network);
+    const token = TOKENS[normalized]?.[symbol.toUpperCase()];
+    if (!token)
+        throw new Error(`unknown token ${symbol} on ${network}`);
+    return token;
+}
+export function toSmallestUnit(amount, decimals) {
+    const [whole, fraction = ""] = String(amount).split(".");
+    const padded = (fraction + "0".repeat(decimals)).slice(0, decimals);
+    return (BigInt(whole || "0") * 10n ** BigInt(decimals) + BigInt(padded || "0")).toString();
+}

package/dist/x402.js

@@ -0,0 +1,25 @@
+import { decodePaymentSignatureHeader, encodePaymentRequiredHeader, encodePaymentResponseHeader, } from "@bankofai/x402-core/http";
+export const headers = {
+    required: "PAYMENT-REQUIRED",
+    signature: "PAYMENT-SIGNATURE",
+    response: "PAYMENT-RESPONSE",
+};
+export function encodeRequired(value) {
+    return encodePaymentRequiredHeader(value);
+}
+export function encodeResponse(value) {
+    return encodePaymentResponseHeader(value);
+}
+export function decodeSignature(value) {
+    return decodePaymentSignatureHeader(value);
+}
+export function matchRequirement(payload, requirement) {
+    const accepted = payload?.accepted ?? payload?.payment?.accepted ?? payload;
+    if (!accepted || typeof accepted !== "object")
+        return false;
+    return (accepted.scheme === requirement.scheme &&
+        accepted.network === requirement.network &&
+        String(accepted.amount) === requirement.amount &&
+        String(accepted.asset).toLowerCase() === requirement.asset.toLowerCase() &&
+        String(accepted.payTo) === requirement.payTo);
+}

package/examples/provider.yml

@@ -0,0 +1,53 @@
+name: tron-nile-usdt
+title: "TRON Nile USDT Provider"
+description: "TRON Nile provider protected by x402 exact Permit2 USDT payment"
+category: data
+version: v1
+
+forward_url: ${X402_PROVIDER_FORWARD_URL}
+openapi_url: ${X402_PROVIDER_OPENAPI_URL}
+
+display:
+  service_url: ${X402_GATEWAY_PUBLIC_BASE_URL}/providers/tron-nile-usdt
+  tags: ["tron-nile", "usdt", "x402"]
+
+discovery:
+  use_case: "Use for validating TRON Nile USDT x402 payments."
+  spend_aware_usage:
+    - "Use small Nile USDT amounts while validating facilitator and gateway wiring."
+  when_to_use:
+    - "Use when testing x402 exact Permit2 payments on TRON Nile."
+  request_examples:
+    - "GET /providers/tron-nile-usdt/v1/ping"
+
+routing:
+  type: proxy
+  auth:
+    method: header
+    key: Authorization
+    prefix: "Bearer "
+    value_from_env: X402_PROVIDER_API_TOKEN
+
+operator:
+  network: tron-nile
+  currencies:
+    usd: ["USDT"]
+  recipient: ${X402_PROVIDER_RECIPIENT_TRON}
+  scheme: exact
+  protocol: exact
+  asset_transfer_method: permit2
+  facilitator_url: https://tn-facilitator.bankofai.io
+  facilitator_api_key_env: X402_FACILITATOR_API_KEY
+  valid_for_seconds: 300
+
+endpoints:
+  - method: GET
+    path: /v1/ping
+    description: "TRON Nile USDT paid ping endpoint"
+    metering:
+      dimensions:
+        - direction: usage
+          unit: requests
+          scale: 1
+          tiers:
+            - price_usd: 0.0001

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@bankofai/x402-gateway",
+  "version": "1.0.0-beta.0",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "x402-gateway": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/cli.js",
+    "dev": "tsx src/cli.ts"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@bankofai/x402-core": "1.0.0",
+    "@bankofai/x402-evm": "1.0.0",
+    "@bankofai/x402-tron": "1.0.0",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}