@bankofai/x402-cli 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BankofAI
+
+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,106 @@
+# x402-cli
+
+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`
+
+Stablecoin payments use `scheme=exact` with
+`extra.assetTransferMethod=permit2`.
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+Run from source during development:
+
+```bash
+npm run dev -- serve --pay-to <recipient> --amount 0.0001 --network tron:nile --token USDT
+```
+
+Run the compiled CLI:
+
+```bash
+node dist/cli.js <command> [options]
+```
+
+## Commands
+
+### Serve
+
+Start a local x402 paywall endpoint:
+
+```bash
+node dist/cli.js serve \
+  --pay-to <recipient> \
+  --amount 0.0001 \
+  --network tron:nile \
+  --token USDT \
+  --port 4020
+```
+
+The server exposes:
+
+- `GET /health`
+- `GET /.well-known/x402`
+- `GET /pay` returns `402 Payment Required`
+- `POST /pay` verifies and settles with the facilitator
+
+### Pay
+
+Pay an x402-protected URL:
+
+```bash
+TRON_PRIVATE_KEY=<hex> \
+node dist/cli.js pay http://127.0.0.1:4020/pay \
+  --network tron:nile \
+  --token USDT
+```
+
+For EVM networks use `EVM_PRIVATE_KEY` or `PRIVATE_KEY`.
+
+### Roundtrip
+
+Start a temporary local server and immediately pay it:
+
+```bash
+TRON_PRIVATE_KEY=<hex> \
+node dist/cli.js roundtrip \
+  --pay-to <recipient> \
+  --amount 0.0001 \
+  --network tron:nile \
+  --token USDT
+```
+
+## Networks
+
+Supported built-in token registry:
+
+- `tron:mainnet` USDT, USDD
+- `tron:nile` USDT, USDD
+- `tron:shasta` USDT
+- `eip155:56` USDT
+- `eip155:97` USDT, USDC
+
+Aliases accepted:
+
+- `tron-mainnet` -> `tron:mainnet`
+- `tron-nile` -> `tron:nile`
+- `bsc-mainnet` -> `eip155:56`
+- `bsc-testnet` -> `eip155:97`
+
+## Facilitator
+
+Set a facilitator URL when needed:
+
+```bash
+FACILITATOR_URL=https://facilitator.bankofai.io
+```
+
+CLI payment challenges and payload selection always emit `scheme: "exact"` for
+the SDK 1.0 Permit2 path.

package/dist/cli.js

@@ -0,0 +1,624 @@
+#!/usr/bin/env node
+import http from "node:http";
+import { setTimeout as delay } from "node:timers/promises";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import YAML from "yaml";
+import { createPaymentPayload, decodeRequired, decodeResponse, encodeRequired, encodeResponse, encodeSignature, headers } from "./x402.js";
+import { getToken, normalizeNetwork, toSmallestUnit } from "./tokens.js";
+function parseArgs(argv) {
+    const [command = "help", ...rest] = argv;
+    const positional = [];
+    const options = {};
+    for (let i = 0; i < rest.length; i += 1) {
+        const item = rest[i];
+        if (!item.startsWith("--")) {
+            positional.push(item);
+            continue;
+        }
+        const key = item.slice(2);
+        const next = rest[i + 1];
+        if (!next || next.startsWith("--")) {
+            options[key] = true;
+        }
+        else {
+            if (key === "header") {
+                const current = options[key];
+                options[key] = Array.isArray(current) ? [...current, next] : current ? [String(current), next] : [next];
+            }
+            else {
+                options[key] = next;
+            }
+            i += 1;
+        }
+    }
+    return { command, positional, options };
+}
+function opt(options, key, fallback) {
+    const value = options[key];
+    return typeof value === "string" ? value : fallback;
+}
+function optAll(options, key) {
+    const value = options[key];
+    if (Array.isArray(value))
+        return value;
+    return typeof value === "string" ? [value] : [];
+}
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function readYaml(file) {
+    return YAML.parse(fs.readFileSync(file, "utf8"));
+}
+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 providerFiles(root) {
+    const stat = fs.statSync(root);
+    if (stat.isFile())
+        return [root];
+    const out = [];
+    for (const entry of fs.readdirSync(root, { recursive: true })) {
+        const file = path.join(root, String(entry));
+        if (file.endsWith("provider.yml") || file.endsWith("provider.yaml"))
+            out.push(file);
+    }
+    return out.sort();
+}
+function loadProviderFile(file) {
+    const provider = expandDeep(readYaml(file));
+    validateProvider(provider, file);
+    provider.operator.network = normalizeNetwork(provider.operator.network);
+    provider.operator.scheme = "exact";
+    return provider;
+}
+function validateProvider(provider, file = "provider.yml") {
+    const required = [
+        ["name", provider?.name],
+        ["forward_url", provider?.forward_url],
+        ["operator.network", provider?.operator?.network],
+        ["operator.recipient", provider?.operator?.recipient],
+    ];
+    for (const [name, value] of required) {
+        if (typeof value !== "string" || !value.trim())
+            throw new Error(`${file}: ${name} is required`);
+    }
+    if (!Array.isArray(provider.endpoints) || !provider.endpoints.length) {
+        throw new Error(`${file}: endpoints must contain at least one endpoint`);
+    }
+    const seen = new Set();
+    for (const endpoint of provider.endpoints) {
+        if (typeof endpoint.method !== "string" || typeof endpoint.path !== "string") {
+            throw new Error(`${file}: each endpoint needs method and path`);
+        }
+        const key = `${endpoint.method.toUpperCase()} ${endpoint.path}`;
+        if (seen.has(key))
+            throw new Error(`${file}: duplicate endpoint ${key}`);
+        seen.add(key);
+    }
+}
+function providerPrice(endpoint) {
+    return endpoint?.metering?.dimensions?.[0]?.tiers?.[0]?.price_usd ?? 0;
+}
+function providerAssetTransferMethod(provider) {
+    return provider.operator?.asset_transfer_method ?? provider.operator?.assetTransferMethod ?? "permit2";
+}
+function providerCatalog(provider) {
+    return {
+        name: provider.name,
+        title: provider.title ?? provider.name,
+        description: provider.description ?? "",
+        category: provider.category ?? "other",
+        service_url: provider.display?.service_url,
+        tags: provider.display?.tags ?? [],
+        network: normalizeNetwork(provider.operator.network),
+        currency: provider.operator.currencies?.usd?.[0] ?? "USDT",
+        endpoints: (provider.endpoints ?? []).map((endpoint) => ({
+            method: endpoint.method.toUpperCase(),
+            path: `/providers/${provider.name}${endpoint.path}`,
+            upstream_path: endpoint.path,
+            description: endpoint.description ?? "",
+            paid: providerPrice(endpoint) > 0 ? {
+                scheme: "exact",
+                network: normalizeNetwork(provider.operator.network),
+                currency: provider.operator.currencies?.usd?.[0] ?? "USDT",
+                price_usd: providerPrice(endpoint),
+            } : null,
+            x402_routes: providerPrice(endpoint) > 0 ? [{
+                    provider: provider.name,
+                    network: normalizeNetwork(provider.operator.network),
+                    scheme: "exact",
+                    assetTransferMethod: providerAssetTransferMethod(provider),
+                    url: `/providers/${provider.name}${endpoint.path}`,
+                }] : [],
+        })),
+    };
+}
+async function readCatalog(source) {
+    const text = await readText(source);
+    const parsed = JSON.parse(text);
+    if (Array.isArray(parsed))
+        return parsed;
+    if (Array.isArray(parsed.providers))
+        return parsed.providers;
+    if (Array.isArray(parsed.items))
+        return parsed.items;
+    return [];
+}
+async function readText(source) {
+    if (!source.startsWith("http://") && !source.startsWith("https://")) {
+        return fs.readFileSync(source, "utf8");
+    }
+    const response = await fetch(source);
+    if (!response.ok)
+        throw new Error(`failed to fetch ${source}: ${response.status}`);
+    return response.text();
+}
+async function readJson(source) {
+    return JSON.parse(await readText(source));
+}
+function catalogDetailSource(source, section, name) {
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+        const base = new URL(source);
+        const pathname = base.pathname.endsWith("/catalog.json")
+            ? base.pathname.slice(0, -"catalog.json".length)
+            : base.pathname.endsWith("/")
+                ? base.pathname
+                : `${base.pathname}/`;
+        base.pathname = `${pathname}${section}/${name}.json`;
+        base.search = "";
+        base.hash = "";
+        return base.toString();
+    }
+    const stat = fs.existsSync(source) ? fs.statSync(source) : undefined;
+    const root = stat?.isDirectory() ? source : path.dirname(source);
+    return path.join(root, section, `${name}.json`);
+}
+async function readCatalogProvider(source, name) {
+    const providers = await readCatalog(source);
+    const summary = providers.find((item) => item.name === name || item.fqn === name);
+    if (!summary)
+        throw new Error(`provider not found: ${name}`);
+    if (Array.isArray(summary.endpoints) && summary.endpoints.length)
+        return summary;
+    const fqn = summary.fqn ?? summary.name ?? name;
+    try {
+        return await readJson(catalogDetailSource(source, "providers", fqn));
+    }
+    catch {
+        return summary;
+    }
+}
+async function readCatalogPayProvider(source, name) {
+    const providers = await readCatalog(source);
+    const summary = providers.find((item) => item.name === name || item.fqn === name);
+    const fqn = summary?.fqn ?? summary?.name ?? name;
+    try {
+        return await readJson(catalogDetailSource(source, "pay", fqn));
+    }
+    catch {
+        if (summary)
+            return readCatalogProvider(source, name);
+        throw new Error(`provider not found: ${name}`);
+    }
+}
+function buildRequirement(options) {
+    const network = normalizeNetwork(opt(options, "network", "tron:nile"));
+    const tokenSymbol = opt(options, "token", "USDT");
+    const token = getToken(network, tokenSymbol);
+    const amount = opt(options, "rawAmount") ?? toSmallestUnit(opt(options, "amount", "0.0001"), token.decimals);
+    return {
+        scheme: "exact",
+        network,
+        amount,
+        asset: opt(options, "asset") ?? token.address,
+        payTo: opt(options, "pay-to") ?? opt(options, "payTo") ?? "",
+        maxTimeoutSeconds: Number(opt(options, "valid-for-seconds", "300")),
+        extra: token.assetTransferMethod ? { assetTransferMethod: token.assetTransferMethod } : {},
+    };
+}
+async function facilitatorPost(baseUrl, path, body) {
+    const response = await fetch(new URL(path, baseUrl), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        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;
+}
+function requestHeaders(options) {
+    const headersOut = new Headers();
+    for (const header of optAll(options, "header")) {
+        const idx = header.indexOf(":");
+        if (idx <= 0)
+            throw new Error(`invalid --header '${header}', expected 'Name: Value'`);
+        headersOut.set(header.slice(0, idx).trim(), header.slice(idx + 1).trim());
+    }
+    return headersOut;
+}
+function validateAmountLimits(selected, options) {
+    const maxRaw = opt(options, "max-rawAmount") ?? opt(options, "max-raw-amount");
+    const maxAmount = opt(options, "max-amount");
+    if (maxRaw && BigInt(selected.amount) > BigInt(maxRaw)) {
+        throw new Error(`payment raw amount ${selected.amount} exceeds --max-rawAmount ${maxRaw}`);
+    }
+    if (maxAmount) {
+        const token = getToken(selected.network, opt(options, "token", "USDT"));
+        if (BigInt(selected.amount) > BigInt(toSmallestUnit(maxAmount, token.decimals))) {
+            throw new Error(`payment amount exceeds --max-amount ${maxAmount}`);
+        }
+    }
+}
+async function serve(options) {
+    const host = opt(options, "host", "127.0.0.1");
+    const port = Number(opt(options, "port", "4020"));
+    const facilitatorUrl = opt(options, "facilitator-url", process.env.FACILITATOR_URL ?? "https://facilitator.bankofai.io");
+    const requirement = buildRequirement(options);
+    if (!requirement.payTo)
+        throw new Error("--pay-to is required");
+    const resourceUrl = opt(options, "resource-url", `http://${host}:${port}/pay`);
+    const challenge = {
+        x402Version: 2,
+        error: "Payment required",
+        resource: { url: resourceUrl },
+        accepts: [requirement],
+    };
+    const server = http.createServer(async (request, response) => {
+        try {
+            if (request.url?.startsWith("/health")) {
+                response.writeHead(200, { "content-type": "application/json" });
+                response.end(JSON.stringify({ ok: true }));
+                return;
+            }
+            if (request.url?.startsWith("/.well-known/x402")) {
+                response.writeHead(200, { "content-type": "application/json" });
+                response.end(JSON.stringify({ network: requirement.network, scheme: "exact", asset: requirement.asset, amount: requirement.amount, payTo: requirement.payTo, pay_url: resourceUrl }));
+                return;
+            }
+            if (!request.url?.startsWith("/pay")) {
+                response.writeHead(404).end("not found");
+                return;
+            }
+            const signature = request.headers[headers.signature.toLowerCase()];
+            if (!signature || Array.isArray(signature)) {
+                response.writeHead(402, {
+                    "content-type": "application/json",
+                    [headers.required]: encodeRequired(challenge),
+                });
+                response.end(JSON.stringify(challenge));
+                return;
+            }
+            const payload = Buffer.from(signature, "base64").toString("utf8").startsWith("{")
+                ? JSON.parse(Buffer.from(signature, "base64").toString("utf8"))
+                : signature;
+            const verify = await facilitatorPost(facilitatorUrl, "/verify", {
+                paymentPayload: payload,
+                paymentRequirements: requirement,
+            });
+            if (verify?.valid === false || verify?.isValid === false) {
+                response.writeHead(400, { "content-type": "application/json" });
+                response.end(JSON.stringify({ error: "payment verification failed", verify }));
+                return;
+            }
+            const settle = await facilitatorPost(facilitatorUrl, "/settle", {
+                paymentPayload: payload,
+                paymentRequirements: requirement,
+            });
+            response.writeHead(200, {
+                "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 }));
+        }
+        catch (error) {
+            response.writeHead(500, { "content-type": "application/json" });
+            response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+        }
+    });
+    server.listen(port, host, () => {
+        printJson({ ok: true, command: "server", network: requirement.network, scheme: "exact", result: { pay_url: resourceUrl, token: opt(options, "token", "USDT"), rawAmount: requirement.amount, pay_to: requirement.payTo } });
+    });
+}
+function selectRequirement(accepts, options) {
+    const network = opt(options, "network");
+    const scheme = opt(options, "scheme");
+    const token = opt(options, "token");
+    const selected = accepts.find(req => {
+        if (network && normalizeNetwork(network) !== req.network)
+            return false;
+        if (scheme && scheme !== req.scheme)
+            return false;
+        if (token) {
+            const tokenInfo = getToken(req.network, token);
+            if (tokenInfo.address.toLowerCase() !== req.asset.toLowerCase())
+                return false;
+        }
+        return true;
+    });
+    if (!selected)
+        throw new Error("no matching payment requirement");
+    return selected;
+}
+async function pay(url, options) {
+    const method = opt(options, "method", "GET");
+    const baseHeaders = requestHeaders(options);
+    const probe = await fetch(url, {
+        method,
+        headers: baseHeaders,
+        body: ["GET", "HEAD"].includes(method.toUpperCase()) ? undefined : opt(options, "body"),
+    });
+    if (probe.status !== 402) {
+        printJson({ ok: true, command: "client", result: { status: probe.status, body: await probe.text() } });
+        return;
+    }
+    const header = probe.headers.get(headers.required);
+    if (!header)
+        throw new Error("402 response missing PAYMENT-REQUIRED header");
+    const required = decodeRequired(header);
+    const selected = selectRequirement(required.accepts ?? [], options);
+    validateAmountLimits(selected, options);
+    if (options["dry-run"]) {
+        printJson({
+            ok: true,
+            command: "client",
+            network: selected.network,
+            scheme: "exact",
+            result: {
+                url,
+                resource: required.resource?.url ?? url,
+                selected,
+                message: "Dry run - no payment submitted",
+            },
+        });
+        return;
+    }
+    const payload = await createPaymentPayload({
+        selected,
+        resource: required.resource?.url ?? url,
+        extensions: required.extensions,
+        rpcUrl: opt(options, "rpc-url"),
+        privateKey: opt(options, "private-key"),
+    });
+    const retryHeaders = new Headers(baseHeaders);
+    retryHeaders.set(headers.signature, encodeSignature(payload));
+    const paid = await fetch(url, {
+        method,
+        headers: retryHeaders,
+        body: opt(options, "body"),
+    });
+    const text = await paid.text();
+    const paymentResponse = paid.headers.get(headers.response);
+    printJson({
+        ok: paid.ok,
+        command: "client",
+        network: selected.network,
+        scheme: "exact",
+        result: {
+            status: paid.status,
+            body: text,
+            ...(paymentResponse ? { paymentResponse: decodeResponse(paymentResponse) } : {}),
+        },
+    });
+}
+async function roundtrip(options) {
+    const port = Number(opt(options, "port", "4020"));
+    serve(options);
+    await delay(500);
+    await pay(`http://127.0.0.1:${port}/pay`, options);
+    process.exit(0);
+}
+function gatewayBinary() {
+    return process.env.X402_GATEWAY_BIN ||
+        path.resolve(process.cwd(), "../x402-gateway/dist/cli.js");
+}
+async function gatewayStart(args) {
+    const child = spawn(process.execPath, [gatewayBinary(), ...args], {
+        stdio: "inherit",
+        env: process.env,
+    });
+    await new Promise((resolve, reject) => {
+        child.on("exit", code => code === 0 ? resolve() : reject(new Error(`gateway exited with ${code}`)));
+        child.on("error", reject);
+    });
+}
+function gatewayCheck(target) {
+    const files = providerFiles(target);
+    const providers = files.map(loadProviderFile);
+    const names = new Set();
+    for (const provider of providers) {
+        if (names.has(provider.name))
+            throw new Error(`duplicate provider name: ${provider.name}`);
+        names.add(provider.name);
+    }
+    printJson({ ok: true, providers: providers.map(p => p.name), count: providers.length });
+}
+function gatewayScaffold(name, options) {
+    const outputDir = opt(options, "output-dir", path.join("providers", name));
+    const forwardUrl = opt(options, "forward-url", "https://api.example.com");
+    fs.mkdirSync(outputDir, { recursive: true });
+    const body = `name: ${name}
+title: "${name}"
+description: "x402 provider"
+category: data
+version: v1
+
+forward_url: ${forwardUrl}
+
+routing:
+  type: proxy
+
+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: \${X402_FACILITATOR_API_KEY}
+  valid_for_seconds: 300
+
+endpoints:
+  - method: GET
+    path: /v1/ping
+    metering:
+      dimensions:
+        - tiers:
+            - price_usd: 0.0001
+`;
+    fs.writeFileSync(path.join(outputDir, "provider.yml"), body);
+    printJson({ ok: true, file: path.join(outputDir, "provider.yml") });
+}
+function catalogBuild(target, options) {
+    const providers = providerFiles(target).map(loadProviderFile).map(providerCatalog);
+    const catalog = { version: 1, generatedAt: new Date().toISOString(), providers };
+    const output = opt(options, "output", opt(options, "dist-dir") ? path.join(opt(options, "dist-dir"), "catalog.json") : undefined);
+    if (output) {
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.writeFileSync(output, JSON.stringify(catalog, null, 2));
+        printJson({ ok: true, output, count: providers.length });
+    }
+    else {
+        printJson(catalog);
+    }
+}
+function catalogPayAssets(target) {
+    const rows = providerFiles(target).map(loadProviderFile).flatMap(provider => (provider.endpoints ?? []).map((endpoint) => ({
+        provider: provider.name,
+        method: endpoint.method,
+        path: `/providers/${provider.name}${endpoint.path}`,
+        network: normalizeNetwork(provider.operator.network),
+        currency: provider.operator.currencies?.usd?.[0] ?? "USDT",
+        price_usd: providerPrice(endpoint),
+        scheme: "exact",
+        assetTransferMethod: providerAssetTransferMethod(provider),
+    })));
+    printJson({ assets: rows, count: rows.length });
+}
+async function catalogSearch(source, query, options) {
+    const providers = await readCatalog(source);
+    const q = query.toLowerCase();
+    const hits = providers
+        .map((provider) => {
+        const haystack = [
+            provider.fqn,
+            provider.name,
+            provider.title,
+            provider.main_title,
+            provider.mainTitle,
+            provider.description,
+            provider.category,
+            ...(provider.chains ?? []),
+            ...(provider.featured_tags ?? []),
+            ...(provider.featuredTags ?? []),
+            ...(provider.tags ?? []),
+            ...(provider.endpoints ?? []).map((e) => `${e.method} ${e.path} ${e.description ?? ""}`),
+        ].join(" ").toLowerCase();
+        const score = q.split(/\s+/).filter(Boolean).reduce((sum, term) => sum + (haystack.includes(term) ? 1 : 0), 0);
+        return { provider, score };
+    })
+        .filter(item => item.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, Number(opt(options, "limit", "10")));
+    printJson({ query, count: hits.length, results: hits.map(item => item.provider) });
+}
+async function catalogShow(source, name) {
+    printJson(await readCatalogProvider(source, name));
+}
+async function catalogEndpoints(source, name) {
+    const provider = await readCatalogProvider(source, name);
+    printJson({ provider: provider.fqn ?? provider.name, endpoints: provider.endpoints ?? [] });
+}
+async function catalogPayJson(source, name) {
+    const provider = await readCatalogPayProvider(source, name);
+    const endpoint = (provider.endpoints ?? []).find((item) => item.paid || item.x402_routes?.length || item.x402Routes?.length) ?? provider.endpoints?.[0];
+    if (!endpoint)
+        throw new Error(`provider has no endpoints: ${name}`);
+    printJson({
+        provider: provider.fqn ?? provider.name,
+        url: endpoint.url ?? endpoint.path,
+        method: endpoint.method,
+        paid: endpoint.paid,
+        x402_routes: endpoint.x402_routes ?? endpoint.x402Routes ?? [],
+        endpoint,
+    });
+}
+async function handleGateway(args) {
+    const { command, positional, options } = parseArgs(args);
+    if (command === "start")
+        await gatewayStart(["--providers", opt(options, "providers", opt(options, "providers-dir", positional[0] ?? "providers")), "--host", opt(options, "host", "127.0.0.1"), "--port", opt(options, "port", "4020")]);
+    else if (command === "check")
+        gatewayCheck(positional[0] ?? opt(options, "providers", "providers"));
+    else if (command === "scaffold")
+        gatewayScaffold(positional[0] ?? "example-provider", options);
+    else if (command === "catalog")
+        await handleGatewayCatalog(positional, options);
+    else
+        throw new Error("Usage: x402-cli gateway <start|check|scaffold|catalog>");
+}
+async function handleGatewayCatalog(positional, options) {
+    const sub = positional[0] ?? "build";
+    const target = positional[1] ?? opt(options, "providers", "providers");
+    if (sub === "build")
+        catalogBuild(target, options);
+    else if (sub === "check")
+        gatewayCheck(target);
+    else if (sub === "pay-assets")
+        catalogPayAssets(target);
+    else if (sub === "search")
+        await catalogSearch(opt(options, "catalog", target), positional.slice(2).join(" ") || opt(options, "query", ""), options);
+    else
+        throw new Error("Usage: x402-cli gateway catalog <build|check|pay-assets|search>");
+}
+async function handleCatalog(args) {
+    const { command, positional, options } = parseArgs(args);
+    const source = opt(options, "catalog", process.env.X402_CATALOG || "dist/catalog.json");
+    if (command === "search")
+        await catalogSearch(source, positional.join(" "), options);
+    else if (command === "show")
+        await catalogShow(source, positional[0]);
+    else if (command === "endpoints")
+        await catalogEndpoints(source, positional[0]);
+    else if (command === "pay-json")
+        await catalogPayJson(source, positional[0]);
+    else if (command === "build")
+        catalogBuild(positional[0] ?? "providers", options);
+    else
+        throw new Error("Usage: x402-cli catalog <search|show|endpoints|pay-json|build>");
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const { command, positional, options } = parseArgs(argv);
+    if (command === "serve")
+        await serve(options);
+    else if (command === "pay")
+        await pay(positional[0], options);
+    else if (command === "roundtrip")
+        await roundtrip(options);
+    else if (command === "gateway")
+        await handleGateway(argv.slice(1));
+    else if (command === "catalog")
+        await handleCatalog(argv.slice(1));
+    else {
+        process.stdout.write("Usage: x402-cli <serve|pay|roundtrip|gateway|catalog> [options]\n");
+    }
+}
+main().catch(error => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/tokens.js

@@ -0,0 +1,99 @@
+export const TOKENS = {
+    "tron:mainnet": {
+        USDT: {
+            address: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+            decimals: 6,
+            name: "Tether USD",
+            symbol: "USDT",
+            version: "1",
+            assetTransferMethod: "permit2",
+        },
+        USDD: {
+            address: "TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz",
+            decimals: 18,
+            name: "Decentralized USD",
+            symbol: "USDD",
+            version: "1",
+            assetTransferMethod: "permit2",
+        },
+    },
+    "tron:nile": {
+        USDT: {
+            address: "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
+            decimals: 6,
+            name: "Tether USD",
+            symbol: "USDT",
+            version: "1",
+            assetTransferMethod: "permit2",
+        },
+        USDD: {
+            address: "TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK",
+            decimals: 18,
+            name: "Decentralized USD",
+            symbol: "USDD",
+            version: "1",
+            assetTransferMethod: "permit2",
+        },
+    },
+    "tron:shasta": {
+        USDT: {
+            address: "TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs",
+            decimals: 6,
+            name: "Tether USD",
+            symbol: "USDT",
+            version: "1",
+        },
+    },
+    "eip155:56": {
+        USDT: {
+            address: "0x55d398326f99059fF775485246999027B3197955",
+            decimals: 18,
+            name: "Tether USD",
+            symbol: "USDT",
+            version: "1",
+            assetTransferMethod: "permit2",
+        },
+    },
+    "eip155:97": {
+        USDT: {
+            address: "0x64544969ed7EBf5f083679233325356EbE738930",
+            decimals: 18,
+            name: "USD Coin",
+            symbol: "USDT",
+            version: "1",
+            assetTransferMethod: "permit2",
+        },
+        USDC: {
+            address: "0x64544969ed7EBf5f083679233325356EbE738930",
+            decimals: 18,
+            name: "USD Coin",
+            symbol: "USDC",
+            version: "1",
+            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 token = TOKENS[normalizeNetwork(network)]?.[symbol.toUpperCase()];
+    if (!token)
+        throw new Error(`unknown token ${symbol} on ${network}`);
+    return token;
+}
+export function findTokenByAddress(network, address) {
+    const lower = address.toLowerCase();
+    return Object.values(TOKENS[normalizeNetwork(network)] ?? {}).find(token => token.address.toLowerCase() === lower);
+}
+export function toSmallestUnit(amount, decimals) {
+    const [whole, fraction = ""] = 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,151 @@
+import { decodePaymentRequiredHeader, decodePaymentResponseHeader, decodePaymentSignatureHeader, encodePaymentRequiredHeader, encodePaymentResponseHeader, encodePaymentSignatureHeader, } from "@bankofai/x402-core/http";
+import { x402Client } from "@bankofai/x402-core/client";
+import { ExactEvmScheme, toClientEvmSigner } from "@bankofai/x402-evm";
+import { ExactTronScheme, createClientTronSigner } from "@bankofai/x402-tron";
+import { createPublicClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { TronWeb } from "tronweb";
+import { findTokenByAddress } from "./tokens.js";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const headers = {
+    required: "PAYMENT-REQUIRED",
+    signature: "PAYMENT-SIGNATURE",
+    response: "PAYMENT-RESPONSE",
+};
+export function encodeRequired(value) {
+    return encodePaymentRequiredHeader(value);
+}
+export function encodeSignature(value) {
+    return encodePaymentSignatureHeader(value);
+}
+export function encodeResponse(value) {
+    return encodePaymentResponseHeader(value);
+}
+export function decodeRequired(value) {
+    return decodePaymentRequiredHeader(value);
+}
+export function decodeSignature(value) {
+    return decodePaymentSignatureHeader(value);
+}
+export function decodeResponse(value) {
+    return decodePaymentResponseHeader(value);
+}
+export function ensurePermit2(requirement) {
+    const extra = { ...(requirement.extra ?? {}) };
+    if (!extra.assetTransferMethod) {
+        const token = findTokenByAddress(requirement.network, requirement.asset);
+        if (token?.assetTransferMethod === "permit2") {
+            extra.assetTransferMethod = "permit2";
+        }
+    }
+    return { ...requirement, scheme: "exact", extra };
+}
+export function paymentRequired(requirement, resource, extensions) {
+    return {
+        x402Version: 2,
+        resource: { url: resource },
+        accepts: [ensurePermit2(requirement)],
+        ...(extensions ? { extensions } : {}),
+    };
+}
+function normalizePrivateKey(value) {
+    if (!value?.trim())
+        return undefined;
+    const trimmed = value.trim();
+    return (trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`);
+}
+function privateKeyFromAgentWallet(walletIds) {
+    const configPath = process.env.AGENT_WALLET_CONFIG ||
+        path.join(process.env.AGENT_WALLET_DIR || path.join(os.homedir(), ".agent-wallet"), "wallets_config.json");
+    if (!fs.existsSync(configPath))
+        return undefined;
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        const wallets = config.wallets ?? {};
+        const ids = [
+            process.env.AGENT_WALLET_ID,
+            config.activeWalletId,
+            ...walletIds,
+            ...Object.keys(wallets),
+        ].filter(Boolean);
+        for (const id of ids) {
+            const wallet = wallets[String(id)];
+            const key = wallet?.params?.private_key ?? wallet?.material?.private_key ?? wallet?.private_key;
+            const normalized = normalizePrivateKey(key);
+            if (normalized)
+                return normalized;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function privateKeyFrom(names, explicit, walletIds) {
+    for (const value of [explicit, ...names.map(name => process.env[name])]) {
+        const normalized = normalizePrivateKey(value);
+        if (normalized)
+            return normalized;
+    }
+    const walletKey = privateKeyFromAgentWallet(walletIds);
+    if (walletKey)
+        return walletKey;
+    throw new Error(`missing private key; set one of ${names.join(", ")}`);
+}
+function evmRpcUrl(network, explicit) {
+    const chainId = network.split(":")[1];
+    return (explicit ||
+        process.env[`EVM_RPC_URL_${chainId}`] ||
+        process.env.RPC_URL ||
+        process.env.EVM_RPC_URL ||
+        (chainId === "56" ? "https://bsc-dataseed.binance.org" : undefined) ||
+        (chainId === "97" ? "https://data-seed-prebsc-1-s1.binance.org:8545" : undefined));
+}
+async function createTronWallet(privateKey) {
+    const rawKey = privateKey.replace(/^0x/, "");
+    const tronWeb = new TronWeb({ fullHost: "https://api.trongrid.io" });
+    const address = TronWeb.address.fromPrivateKey(rawKey);
+    if (!address)
+        throw new Error("invalid TRON private key");
+    return {
+        getAddress: () => address,
+        async signTypedData(args) {
+            const signature = await tronWeb.trx._signTypedData(args.domain, args.types, args.message, rawKey);
+            return signature.startsWith("0x") ? signature : `0x${signature}`;
+        },
+        async signTransaction(tx) {
+            return tronWeb.trx.sign(tx, rawKey);
+        },
+    };
+}
+export async function createPaymentPayload(args) {
+    const selected = ensurePermit2(args.selected);
+    const required = paymentRequired(selected, args.resource, args.extensions);
+    if (selected.network.startsWith("eip155:")) {
+        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);
+        const publicClient = rpcUrl ? createPublicClient({ transport: http(rpcUrl) }) : undefined;
+        const signer = toClientEvmSigner(account, publicClient);
+        const scheme = new ExactEvmScheme(signer, rpcUrl ? { rpcUrl } : undefined);
+        return new x402Client()
+            .register(selected.network, scheme)
+            .createPaymentPayload(required);
+    }
+    if (selected.network.startsWith("tron:")) {
+        const privateKey = privateKeyFrom(["TRON_PRIVATE_KEY", "AGENT_WALLET_PRIVATE_KEY", "PRIVATE_KEY"], args.privateKey, ["tron_client", "payer", "default"]);
+        const wallet = await createTronWallet(privateKey);
+        const signer = await createClientTronSigner(wallet, {
+            network: selected.network,
+            rpcUrl: args.rpcUrl || process.env.TRON_RPC_URL,
+            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);
+    }
+    throw new Error(`unsupported network ${selected.network}`);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@bankofai/x402-cli",
+  "version": "1.0.0-beta.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "x402-cli": "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",
+    "tronweb": "^6.0.4",
+    "viem": "^2.40.3",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}