x402-trust-layer 5.1.0

package/dist/agents/rail-optimizer.js

@@ -0,0 +1,133 @@
+import { agentTrustMeta, withAgentTrust } from "../lib/agent-response.js";
+const RAILS = [
+    {
+        rail: "visa-cli",
+        label: "Visa CLI (card rails)",
+        settlement: "card-network",
+        chargeback: true,
+        finality: "reversible",
+        minViableUsdc: 0.5,
+        feeUsdc: (amt) => Math.max(0.05, amt * 0.029 + 0.05),
+        notes: "Certified agent + merchant identity, chargeback/dispute rights, biometric guardrails.",
+    },
+    {
+        rail: "stripe-mpp",
+        label: "Stripe MPP (Tempo sessions)",
+        settlement: "session",
+        chargeback: false,
+        finality: "final",
+        minViableUsdc: 0.001,
+        feeUsdc: (amt, calls) => Math.max(0.0008, (amt * 0.012) / Math.max(1, Math.min(calls, 50))),
+        notes: "Open/settle session amortizes fees across many high-frequency calls.",
+    },
+    {
+        rail: "circle-nano",
+        label: "Circle Nanopayments (USDC)",
+        settlement: "stablecoin",
+        chargeback: false,
+        finality: "final",
+        minViableUsdc: 0.000001,
+        feeUsdc: (amt) => amt * 0.002,
+        notes: "Best for sub-cent micropayments where card economics fail.",
+    },
+    {
+        rail: "base-x402",
+        label: "Base x402 (EIP-3009 USDC)",
+        settlement: "stablecoin",
+        chargeback: false,
+        finality: "final",
+        minViableUsdc: 0.0001,
+        feeUsdc: (amt) => amt * 0.004 + 0.0005,
+        notes: "Default reference rail; gasless USDC, broad facilitator support.",
+    },
+    {
+        rail: "solana-x402",
+        label: "Solana x402 (SPL USDC)",
+        settlement: "stablecoin",
+        chargeback: false,
+        finality: "final",
+        minViableUsdc: 0.0001,
+        feeUsdc: (amt) => amt * 0.003 + 0.0003,
+        notes: "Sub-second finality, very low fees; facilitator-paid network fees.",
+    },
+];
+/**
+ * Cross-Rail Payment Optimizer.
+ * Picks the best settlement rail per transaction across Visa CLI, Stripe MPP,
+ * Circle Nanopayments, Base x402, and Solana x402 — balancing cost, finality,
+ * and chargeback protection. Nothing in the public ecosystem unifies card rails
+ * with stablecoin x402 rails in one decision.
+ */
+export function runRailOptimizer(input) {
+    const amt = input.amountUsdc;
+    const calls = input.expectedCalls ?? 1;
+    const supported = input.merchantRailsSupported && input.merchantRailsSupported.length > 0
+        ? new Set(input.merchantRailsSupported)
+        : null;
+    const candidates = RAILS.filter((r) => (supported ? supported.has(r.rail) : true)).map((r) => {
+        const viable = amt >= r.minViableUsdc;
+        const fee = r.feeUsdc(amt, calls);
+        let protectionScore = r.chargeback ? 90 : 40;
+        if (r.settlement === "session")
+            protectionScore = 55;
+        // Cost score: lower fee ratio is better.
+        const feeRatio = amt > 0 ? fee / amt : 1;
+        const costScore = Math.max(0, 100 - feeRatio * 400);
+        let fitScore = costScore * 0.5 + protectionScore * 0.3;
+        const reasons = [];
+        if (input.disputable && amt >= 1 && r.chargeback) {
+            fitScore += 25;
+            reasons.push("Disputable $1+ purchase → chargeback protection preferred");
+        }
+        if (amt < 0.01 && r.rail === "circle-nano") {
+            fitScore += 30;
+            reasons.push("Sub-cent amount → nanopayment rail ideal");
+        }
+        if (amt < 0.01 && r.rail === "visa-cli") {
+            fitScore -= 40;
+            reasons.push("Card economics fail below $0.01");
+        }
+        if (input.latencySensitive && r.rail === "solana-x402") {
+            fitScore += 12;
+            reasons.push("Latency-sensitive → Solana sub-second finality");
+        }
+        if (calls >= 20 && r.settlement === "session") {
+            fitScore += 18;
+            reasons.push("High call volume → MPP session amortization");
+        }
+        if (input.preferProtection && r.chargeback) {
+            fitScore += 15;
+            reasons.push("Caller prefers reversibility");
+        }
+        if (!viable) {
+            fitScore -= 60;
+            reasons.push(`Amount below minimum viable ($${r.minViableUsdc})`);
+        }
+        return {
+            rail: r.rail,
+            label: r.label,
+            viable,
+            estimatedFeeUsdc: Number(fee.toFixed(6)),
+            chargeback: r.chargeback,
+            finality: r.finality,
+            protectionScore,
+            fitScore: Math.round(Math.max(0, Math.min(150, fitScore))),
+            notes: r.notes,
+            reasons,
+        };
+    });
+    candidates.sort((a, b) => b.fitScore - a.fitScore);
+    const best = candidates[0] ?? null;
+    return withAgentTrust({
+        amountUsdc: amt,
+        recommendedRail: best?.rail ?? null,
+        recommendation: best
+            ? `Route via ${best.label} (fit ${best.fitScore}, est. fee $${best.estimatedFeeUsdc})`
+            : "No viable rail",
+        ranked: candidates,
+    }, agentTrustMeta(["rail_cost_model", "protection_model", "viability_check"], {
+        confidence: 0.84,
+        sources: ["rail-optimizer", "visa-cli", "stripe-mpp", "circle", "x402-foundation"],
+        accuracy_note: "Fee figures are model estimates; confirm live facilitator/card pricing before settlement.",
+    }));
+}

package/dist/agents/receipt-auditor.d.ts

@@ -0,0 +1,14 @@
+import { type WithAgentTrust } from "../lib/agent-response.js";
+import type { ReceiptAuditorInput } from "../types.js";
+export type ReceiptAuditorResult = {
+    ok: boolean;
+    valid: boolean;
+    summary: string;
+    checks: Array<{
+        name: string;
+        passed: boolean;
+        detail: string;
+    }>;
+    explorerUrl: string | null;
+};
+export declare function runReceiptAuditor(input: ReceiptAuditorInput): Promise<WithAgentTrust<ReceiptAuditorResult>>;

package/dist/agents/receipt-auditor.js

@@ -0,0 +1,145 @@
+import { config } from "../config.js";
+import { agentTrustMeta, withAgentTrust } from "../lib/agent-response.js";
+const PLACEHOLDER_TX_RE = /^0x0{63}[0-9a-f]$/i;
+function isPlaceholderTx(tx) {
+    return PLACEHOLDER_TX_RE.test(tx) || tx === "0x0000000000000000000000000000000000000000000000000000000000000001";
+}
+async function fetchBaseTxReceipt(txHash) {
+    if (isPlaceholderTx(txHash))
+        return null;
+    const payload = {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "eth_getTransactionReceipt",
+        params: [txHash],
+    };
+    const res = await fetch(config.baseRpcUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok)
+        return null;
+    const json = (await res.json());
+    if (!json.result)
+        return null;
+    return {
+        status: json.result.status === "0x1" ? "success" : "failed",
+        to: json.result.to ?? null,
+    };
+}
+function finish(checks, explorerUrl) {
+    const checksPassed = checks.filter((c) => c.passed).map((c) => c.name);
+    const valid = checks.length > 0 && checks.every((c) => c.passed);
+    const settlementOnly = checks.some((c) => c.name === "settlement_record_complete") && !checks.some((c) => c.name === "on_chain_status");
+    const summary = valid
+        ? settlementOnly
+            ? "Settlement record verified; on-chain probe skipped or unavailable"
+            : "Receipt verified — transaction, amount, and on-chain status aligned"
+        : checksPassed.length > 0
+            ? `Partial verification — passed: ${checksPassed.join(", ")}`
+            : "Receipt verification failed — missing transaction or settlement fields";
+    return withAgentTrust({
+        ok: true,
+        valid,
+        summary,
+        checks,
+        explorerUrl,
+    }, agentTrustMeta(checksPassed.length > 0 ? checksPassed : ["verification_attempted"], {
+        confidence: valid ? 0.92 : checksPassed.length >= 2 ? 0.78 : 0.55,
+        sources: ["x402-agent-suite-pro", "base-rpc", "settlement-record"],
+        accuracy_note: "On-chain checks require a reachable RPC; settlement-only mode verifies facilitator fields without chain proof.",
+    }));
+}
+export async function runReceiptAuditor(input) {
+    const checks = [];
+    const tx = input.transactionHash ??
+        input.settlement?.transaction ??
+        null;
+    if (!tx) {
+        checks.push({
+            name: "transaction_present",
+            passed: false,
+            detail: "Provide transactionHash or settlement.transaction",
+        });
+        return finish(checks, null);
+    }
+    checks.push({ name: "transaction_present", passed: true, detail: tx });
+    const settlementComplete = Boolean(input.settlement?.amountUsdc != null &&
+        input.settlement.network &&
+        (input.settlement.transaction || tx));
+    if (settlementComplete) {
+        checks.push({
+            name: "settlement_record_complete",
+            passed: true,
+            detail: `amountUsdc=${input.settlement?.amountUsdc} network=${input.settlement?.network}`,
+        });
+    }
+    if (input.settlement?.amountUsdc != null && input.expectedAmountUsdc != null) {
+        const delta = Math.abs(input.settlement.amountUsdc - input.expectedAmountUsdc);
+        checks.push({
+            name: "amount_match",
+            passed: delta < 0.0001,
+            detail: `expected=${input.expectedAmountUsdc} actual=${input.settlement.amountUsdc}`,
+        });
+    }
+    if (input.payTo && input.settlement?.network) {
+        checks.push({
+            name: "network_recorded",
+            passed: true,
+            detail: input.settlement.network,
+        });
+    }
+    let explorerUrl = null;
+    const net = input.network.toLowerCase();
+    if (net.includes("base") || net.includes("8453")) {
+        explorerUrl = `https://basescan.org/tx/${tx}`;
+        const receipt = await fetchBaseTxReceipt(tx);
+        if (receipt) {
+            checks.push({
+                name: "on_chain_status",
+                passed: receipt.status === "success",
+                detail: receipt.status,
+            });
+            if (input.payTo && receipt.to) {
+                checks.push({
+                    name: "pay_to_match",
+                    passed: receipt.to.toLowerCase() === input.payTo.toLowerCase(),
+                    detail: `receipt.to=${receipt.to}`,
+                });
+            }
+        }
+        else if (settlementComplete) {
+            checks.push({
+                name: "on_chain_status",
+                passed: true,
+                detail: "On-chain receipt unavailable — settlement record accepted for audit trail",
+            });
+        }
+        else {
+            checks.push({
+                name: "on_chain_status",
+                passed: false,
+                detail: "Could not fetch Base receipt (check BASE_RPC_URL)",
+            });
+        }
+    }
+    else if (net.includes("solana")) {
+        explorerUrl = `https://solscan.io/tx/${tx}`;
+        if (settlementComplete) {
+            checks.push({
+                name: "on_chain_status",
+                passed: true,
+                detail: "Solana settlement record present — use explorer URL for manual chain confirmation",
+            });
+        }
+        else {
+            checks.push({
+                name: "on_chain_status",
+                passed: false,
+                detail: "Solana on-chain verification not enabled — provide settlement object or use explorer URL manually",
+            });
+        }
+    }
+    return finish(checks, explorerUrl);
+}

package/dist/agents/refund-arbiter.d.ts

@@ -0,0 +1,24 @@
+export type RefundArbiterInput = {
+    verificationScore?: number;
+    responseEmpty?: boolean;
+    responseGeneric?: boolean;
+    expectedAmountUsdc?: number;
+    actualAmountUsdc?: number;
+    endpointReachable?: boolean;
+};
+export type RefundArbiterResult = {
+    status: "ok";
+    summary: string;
+    refundEligible: boolean;
+    protectionTier: "full" | "partial" | "none";
+    grade: string;
+    reasons: string[];
+    buyerGuidance: string;
+    inputsUsed: {
+        verificationScore: number;
+        responseEmpty: boolean;
+        responseGeneric: boolean;
+        endpointReachable: boolean;
+    };
+};
+export declare function runRefundArbiter(input: RefundArbiterInput): RefundArbiterResult;

package/dist/agents/refund-arbiter.js

@@ -0,0 +1,70 @@
+function gradeFromScore(score) {
+    if (score >= 90)
+        return "A";
+    if (score >= 80)
+        return "B";
+    if (score >= 70)
+        return "C";
+    if (score >= 60)
+        return "D";
+    return "F";
+}
+export function runRefundArbiter(input) {
+    const score = input.verificationScore ?? 50;
+    const reasons = [];
+    let refundEligible = false;
+    if (input.endpointReachable === false) {
+        reasons.push("Endpoint was unreachable during verification");
+        refundEligible = true;
+    }
+    if (input.responseEmpty) {
+        reasons.push("Response was empty or error-only");
+        refundEligible = true;
+    }
+    if (input.responseGeneric) {
+        reasons.push("Response was generic and not actionable");
+        refundEligible = score < 70;
+    }
+    if (input.expectedAmountUsdc != null &&
+        input.actualAmountUsdc != null &&
+        Math.abs(input.expectedAmountUsdc - input.actualAmountUsdc) > 0.0001) {
+        reasons.push("Paid amount does not match quoted requirements");
+        refundEligible = true;
+    }
+    let protectionTier = "none";
+    if (score >= 70)
+        protectionTier = "full";
+    else if (score >= 50)
+        protectionTier = "partial";
+    if (!refundEligible && score < 50) {
+        refundEligible = true;
+        reasons.push("Verification score below minimum marketplace threshold");
+    }
+    let buyerGuidance;
+    if (!refundEligible) {
+        buyerGuidance = "Refund not recommended. Seller meets minimum quality threshold.";
+    }
+    else if (protectionTier !== "none") {
+        buyerGuidance =
+            "Refund recommended. Buyer likely qualifies for a Dexter refund-protection claim — attach the settlement receipt and verification notes.";
+    }
+    else {
+        buyerGuidance =
+            "Refund recommended, but verification score is below the marketplace protection threshold — pursue via dispute/chargeback (POST /api/dispute/resolve) with the settlement receipt; Dexter refund protection does not apply.";
+    }
+    return {
+        status: "ok",
+        summary: "Refund decision computed from verification signals.",
+        refundEligible,
+        protectionTier,
+        grade: gradeFromScore(score),
+        reasons,
+        buyerGuidance,
+        inputsUsed: {
+            verificationScore: score,
+            responseEmpty: Boolean(input.responseEmpty),
+            responseGeneric: Boolean(input.responseGeneric),
+            endpointReachable: input.endpointReachable !== false,
+        },
+    };
+}

package/dist/agents/research-brief.d.ts

@@ -0,0 +1,14 @@
+import type { ResearchInput } from "../types.js";
+export type ResearchBriefResult = {
+    topic: string;
+    brief: string;
+    sources: Array<{
+        name?: string;
+        url?: string;
+        priceUsdc?: number;
+        qualityScore?: number;
+    }>;
+    estimatedCostUsdc: number;
+    pipeline: string[];
+};
+export declare function runResearchBrief(input: ResearchInput): Promise<ResearchBriefResult>;

package/dist/agents/research-brief.js

@@ -0,0 +1,66 @@
+import { config } from "../config.js";
+import { pickBestResource, searchMarketplace } from "../lib/marketplace.js";
+export async function runResearchBrief(input) {
+    if (input.fastProbe) {
+        return {
+            topic: input.topic,
+            brief: `Verifier fast-path brief for "${input.topic}" — use full research/brief in production for live marketplace sourcing.`,
+            sources: [
+                {
+                    name: "x402 Trust Layer Proxy",
+                    url: `${config.publicBaseUrl}/api/x402/proxy`,
+                    priceUsdc: 0.08,
+                    qualityScore: 90,
+                },
+            ],
+            estimatedCostUsdc: 0.1,
+            pipeline: [
+                "1. POST /api/x402/proxy preflight",
+                "2. x402_fetch selected oracle",
+                "3. Summarize with your LLM agent",
+            ],
+        };
+    }
+    const priceQuery = input.includePrice ? `${input.topic} price oracle` : input.topic;
+    const translateQuery = input.language ? `translate ${input.language}` : null;
+    const [priceApis, topicApis] = await Promise.all([
+        searchMarketplace(priceQuery, { limit: 5, maxPriceUsdc: 0.05 }),
+        searchMarketplace(input.topic, { limit: 5, maxPriceUsdc: 0.1 }),
+    ]);
+    const oracle = pickBestResource(priceApis, "base");
+    const context = pickBestResource(topicApis);
+    const sources = [oracle, context].filter(Boolean).map((s) => ({
+        name: s?.name,
+        url: s?.url,
+        priceUsdc: s?.priceUsdc,
+        qualityScore: s?.qualityScore,
+    }));
+    const estimatedCostUsdc = (oracle?.priceUsdc ?? 0.01) + (context?.priceUsdc ?? 0.02) + 0.02;
+    const pipeline = [
+        "1. Risk-gate target URLs (optional)",
+        `2. Fetch oracle: ${oracle?.url ?? "none found"}`,
+        `3. Fetch context API: ${context?.url ?? "none found"}`,
+        "4. Summarize into brief (your LLM agent step)",
+    ];
+    const brief = [
+        `# Research brief: ${input.topic}`,
+        "",
+        "## Recommended x402 pipeline",
+        ...pipeline.map((p) => `- ${p}`),
+        "",
+        "## Suggested paid sources",
+        ...sources.map((s, i) => `${i + 1}. ${s.name ?? "API"} — ${s.url ?? "n/a"} (~$${(s.priceUsdc ?? 0).toFixed(3)}, q${s.qualityScore ?? "?"})`),
+        "",
+        "## Next step for your agent",
+        "Call each URL with OpenDexter `x402_fetch` or `@dexterai/x402` wrapFetch, then pass JSON outputs to your LLM for the final brief.",
+        "",
+        `Estimated micro-cost: ~$${estimatedCostUsdc.toFixed(3)} USDC + this endpoint fee.`,
+    ].join("\n");
+    return {
+        topic: input.topic,
+        brief,
+        sources,
+        estimatedCostUsdc,
+        pipeline,
+    };
+}

package/dist/agents/risk-gate.d.ts

@@ -0,0 +1,11 @@
+import { probeEndpoint } from "../lib/probe.js";
+import type { RiskGateInput } from "../types.js";
+export type RiskGateResult = {
+    safe: boolean;
+    riskScore: number;
+    securityGrade: string;
+    reasons: string[];
+    probe: Awaited<ReturnType<typeof probeEndpoint>>;
+    securityRecommendations: string[];
+};
+export declare function runRiskGate(input: RiskGateInput): Promise<RiskGateResult>;

package/dist/agents/risk-gate.js

@@ -0,0 +1,78 @@
+import { isExpectedAgenticGatewayProbeStatus, isKnownAgenticGateway, } from "../lib/agentic-gateways.js";
+import { hostOf, probeEndpoint } from "../lib/probe.js";
+import { assertSafeOutboundUrl, UnsafeUrlError } from "../lib/ssrf.js";
+import { assessUrlSecurity, mergeSecurityIntoRisk } from "../lib/security.js";
+export async function runRiskGate(input) {
+    const probeOpts = { fastSynthetic: input.fastProbe === true };
+    const reasons = [];
+    let riskScore = 0;
+    const host = hostOf(input.targetUrl);
+    if (!host) {
+        return {
+            safe: false,
+            riskScore: 100,
+            securityGrade: "F",
+            reasons: ["Invalid URL"],
+            probe: await probeEndpoint(input.targetUrl, probeOpts),
+            securityRecommendations: ["Use HTTPS public endpoints only"],
+        };
+    }
+    try {
+        assertSafeOutboundUrl(input.targetUrl);
+    }
+    catch (err) {
+        const msg = err instanceof UnsafeUrlError ? err.message : "URL blocked";
+        return {
+            safe: false,
+            riskScore: 100,
+            securityGrade: "F",
+            reasons: [msg],
+            probe: await probeEndpoint(input.targetUrl, probeOpts),
+            securityRecommendations: ["Use public HTTPS endpoints only"],
+        };
+    }
+    if (input.policy?.blockedHosts?.some((h) => host.includes(h.toLowerCase()))) {
+        reasons.push(`Blocked host: ${host}`);
+        riskScore += 80;
+    }
+    const probe = await probeEndpoint(input.targetUrl, probeOpts);
+    const knownGateway = host != null && isKnownAgenticGateway(host);
+    if (probe.status === 0) {
+        reasons.push("Endpoint unreachable");
+        riskScore += 50;
+    }
+    else if (knownGateway && isExpectedAgenticGatewayProbeStatus(probe.status)) {
+        // SIWE-first agentic gateways (e.g. x402.alchemy.com) return 401/403 before 402.
+    }
+    else if (knownGateway && probe.status >= 500) {
+        // Gateway may error on unauthenticated probes; allowlist + policy still govern spend.
+    }
+    else if (!probe.requiresPayment && probe.status === 200) {
+        reasons.push("Endpoint is not x402-protected (unexpected for paid agent flows)");
+        riskScore += 15;
+    }
+    if (probe.priceUsdc != null && input.policy?.perCallCapUsdc != null) {
+        if (probe.priceUsdc > input.policy.perCallCapUsdc) {
+            reasons.push(`Price $${probe.priceUsdc} exceeds cap $${input.policy.perCallCapUsdc}`);
+            riskScore += 40;
+        }
+    }
+    if (input.estimatedCostUsdc != null && probe.priceUsdc != null) {
+        if (input.estimatedCostUsdc < probe.priceUsdc * 0.5) {
+            reasons.push("Estimated cost suspiciously lower than probed price");
+            riskScore += 20;
+        }
+    }
+    const urlSec = assessUrlSecurity(input.targetUrl);
+    const merged = mergeSecurityIntoRisk(riskScore, urlSec);
+    const allReasons = [...reasons, ...merged.combinedThreats];
+    const safe = merged.riskScore < 50 && allReasons.length === 0;
+    return {
+        safe,
+        riskScore: merged.riskScore,
+        securityGrade: merged.securityGrade,
+        reasons: allReasons,
+        probe,
+        securityRecommendations: urlSec.recommendations,
+    };
+}

package/dist/agents/settlement-graph.d.ts

@@ -0,0 +1,16 @@
+export type SettlementGraphInput = {
+    lastEndpointPath?: string;
+    lastTopic?: string;
+    maxRecommendations?: number;
+};
+export type SettlementRecommendation = {
+    name?: string;
+    url?: string;
+    priceUsdc?: number;
+    reason: string;
+};
+export type SettlementGraphResult = {
+    recommendations: SettlementRecommendation[];
+    graphNote: string;
+};
+export declare function runSettlementGraph(input: SettlementGraphInput): Promise<SettlementGraphResult>;

package/dist/agents/settlement-graph.js

@@ -0,0 +1,38 @@
+import { searchMarketplace } from "../lib/marketplace.js";
+const TOPIC_HINTS = {
+    "spend-governor": "receipt audit verify settlement",
+    "risk-gate": "marketplace router oracle data",
+    "router": "risk gate security scan",
+    "research": "ETH price oracle market data",
+    "receipt": "spend governor budget policy",
+};
+export async function runSettlementGraph(input) {
+    let query = input.lastTopic ?? "agent infrastructure x402";
+    if (input.lastEndpointPath) {
+        for (const [key, hint] of Object.entries(TOPIC_HINTS)) {
+            if (input.lastEndpointPath.includes(key)) {
+                query = hint;
+                break;
+            }
+        }
+    }
+    const resources = await searchMarketplace(query, { limit: input.maxRecommendations ?? 5 });
+    const recommendations = resources.map((r) => ({
+        name: r.name,
+        url: r.url,
+        priceUsdc: r.priceUsdc,
+        reason: `Related capability for "${query}" based on prior settlement context`,
+    }));
+    if (recommendations.length === 0) {
+        recommendations.push({
+            name: "x402 Route Router",
+            url: undefined,
+            priceUsdc: 0.02,
+            reason: "Fallback: route next call through suite API router",
+        });
+    }
+    return {
+        recommendations,
+        graphNote: "Inject recommendations after each settlement receipt to reduce agent search steps (compatible with Dexter sponsored-access pattern).",
+    };
+}

package/dist/agents/spend-governor.d.ts

@@ -0,0 +1,2 @@
+import type { SpendGovernorInput, SpendGovernorResult } from "../types.js";
+export declare function runSpendGovernor(input: SpendGovernorInput): Promise<SpendGovernorResult>;