xytara 3.1.1 → 3.1.3

package/.env.example

@@ -1,8 +1,18 @@
 XYTARA_HOST=127.0.0.1
 XYTARA_PORT=4320
 XYTARA_BASE_URL=http://127.0.0.1:4320
-# local_signed is the default; set presence only for local demos (accepts any non-empty payment header)
+# local_signed is the default; presence (accepts any non-empty payment header) is for local demos;
+# x402_facilitator is trustless on-chain pay-per-call (see REAL_PAYMENT_SETUP.md and the vars below)
 XYTARA_PAYMENT_VERIFICATION_MODE=local_signed
+# used only when mode is x402_facilitator:
+XYTARA_X402_ACCEPTS_JSON=[]
+XYTARA_X402_FACILITATOR_URL=https://x402.org/facilitator
+XYTARA_X402_FACILITATOR_HEADERS_JSON={}
+XYTARA_X402_FACILITATOR_TIMEOUT_MS=15000
+XYTARA_X402_SETTLE=true
+# credit units a single self-serve /x402/credits/topup grants (default 1000);
+# an accepts entry may override per-payment via its extra.credits
+XYTARA_X402_TOPUP_UNITS=1000
 XYTARA_PAYMENT_MAX_AGE_SECONDS=300
 XYTARA_WALLET_REGISTRY_JSON=[]
 XYTARA_TREASURY_DESTINATION_ID=

package/README.md

@@ -2,6 +2,10 @@
 
 `xytara` is the runtime and payment layer for the public two-repo stack.
 
+> New to the code? Read [`ARCHITECTURE.md`](ARCHITECTURE.md) first. It separates
+> the small execution-and-settlement engine (~9,300 lines) from the large
+> machine-readable breadth catalog, so the real runtime is legible in one sitting.
+
 It exists to let agents, developers, and systems:
 
 - discover tasks and workflows

package/REAL_PAYMENT_SETUP.md

@@ -4,7 +4,7 @@ This guide explains how to move `xytara` from local placeholder payment acceptan
 
 ## What Changed
 
-`xytara` supports two payment-acceptance modes. `local_signed` is the default; `presence` has to be opted into explicitly.
+`xytara` supports three payment-acceptance modes. `local_signed` is the default; `presence` and `x402_facilitator` are opt-in.
 
 - `presence`
   - development/demo mode only, enabled with `XYTARA_PAYMENT_VERIFICATION_MODE=presence`
@@ -17,6 +17,54 @@ This guide explains how to move `xytara` from local placeholder payment acceptan
   - quote replay and nonce replay are blocked
   - accepted payments are routed into your configured merchant treasury destination posture
 
+- `x402_facilitator`
+  - trustless, on-chain, pay-per-call, the same mechanism proven live on the MCP executor
+  - the `/x402/commands/execute` and `/x402/mcp/tools/invoke` routes return a `402` that
+    advertises the configured `accepts` (network, asset, amount, payTo) in the
+    `PAYMENT-REQUIRED` header; a buyer signs a gasless x402 USDC authorization (EIP-3009)
+  - on the paid retry, a facilitator verifies the payment and settles it on-chain before any
+    work runs; the response carries a `PAYMENT-RESPONSE` settlement receipt
+  - fails closed: if the facilitator is unreachable or the payment does not settle, nothing runs
+  - the buyer needs no native gas token; the facilitator broadcasts the transfer
+  - enable with `XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator` and the x402 env below:
+
+```env
+XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator
+# what buyers pay, advertised in the 402 (Base Sepolia test USDC shown):
+XYTARA_X402_ACCEPTS_JSON=[{"scheme":"exact","network":"eip155:84532","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","amount":"1000","payTo":"<your-evm-address>","extra":{"name":"USDC","version":"2"},"maxTimeoutSeconds":60}]
+XYTARA_X402_FACILITATOR_URL=https://x402.org/facilitator
+# optional:
+XYTARA_X402_FACILITATOR_HEADERS_JSON={}
+XYTARA_X402_FACILITATOR_TIMEOUT_MS=15000
+XYTARA_X402_SETTLE=true
+```
+
+Confirm the facilitator settles every network you advertise, and verify the mode end to end
+against a mock facilitator with `npm run verify:x402-facilitator`. The payment a buyer signs
+is identical to the one in `services/mcp-execution-target/buyer-demo/` (an EIP-3009 USDC
+authorization in a `PAYMENT-SIGNATURE` header); only the request body differs, since the main
+runtime takes a command-execute body rather than an MCP JSON-RPC call.
+
+### Self-serve credits top-up
+
+Beyond paying per call, a buyer can convert a single x402 payment into spendable
+runtime credits with no operator grant, via `POST /x402/credits/topup`:
+
+- without a `PAYMENT-SIGNATURE`, it returns `402` advertising the same `accepts` plus
+  `credits_per_topup` (how many credit units one payment buys)
+- with a valid payment, the facilitator settles it on-chain and the runtime mints the
+  credits to the account, returning the grant, the new balance, and a `PAYMENT-RESPONSE`
+  settlement receipt
+- credits land on `account_id` from the body, falling back to the paying wallet address
+- replays are idempotent: the payment nonce keys the grant, so re-sending the same settled
+  payment never mints twice
+
+Each top-up grants `XYTARA_X402_TOPUP_UNITS` credit units (default `1000`), unless the matched
+`accepts` entry sets its own `extra.credits`. The route is live only in `x402_facilitator`
+mode with `XYTARA_X402_ACCEPTS_JSON` set, and credits persist only when runtime state
+persistence (`XYTARA_SUPABASE_*` or `XYTARA_STATE_FILE`) is configured. A runnable buyer is in
+`services/mcp-execution-target/buyer-demo/x402-credits-topup-demo.js`.
+
 ## Minimum Production-Oriented Configuration
 
 Set these environment variables:

package/RELEASE_NOTES.md

@@ -1,17 +1,16 @@
-`xytara` 3.1.1 is the synchronized security and stability release for the live runtime, payment, execution, delivery, and public first-contact line.
+`xytara` 3.1.3 makes runtime credits self-serve: a buyer can turn a single x402 payment into spendable credit with no operator grant.
 
-This release closes the authorization and payment-verification gaps found in the post-launch review while keeping the public runtime truth models, catalog, first-run path, and naxytra contract surfaces unchanged.
+This builds on the `x402_facilitator` on-chain settlement mode. Until now, credits could only be minted by an operator; a paying agent still needed someone to grant it a balance. This release closes that gap so the pay-and-use loop is fully autonomous.
 
 Highlights:
 
-- operator write surfaces now fail closed: credit minting, allocation reversal, rail-credit application, budgets, agents, economics receipts, job operator actions, participant admission, the operator-shell admin pack, and agent-account issuance all require `Authorization: Bearer` with `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN`, and return `operator_auth_not_configured` instead of opening up when the token is unset
-- credit consumption requires either the operator bearer or a valid delegated spend credential
-- bearer and credit-bridge token comparisons use constant-time comparison, and the business cockpit no longer accepts query-string tokens
-- `XYTARA_PAYMENT_VERIFICATION_MODE` now defaults to `local_signed`; `presence` must be opted into explicitly and logs a startup warning
-- the MCP execution target verifies and settles x402 payments through a facilitator before serving paid methods, returns `PAYMENT-RESPONSE` on paid responses, rejects malformed or unadvertised payment payloads, and fails closed when the facilitator is unreachable; `initialize`, `ping`, and `tools/list` stay free so MCP clients can connect
-- the credit allocation ledger is no longer truncated, so account balances derived from allocation events stay correct beyond 200 events
-- the client binds every paid quote to its account and uses collision-free payment nonces, which strict verification previously rejected as account mismatches or replayed nonces
-- `/health` reports restore status honestly and a new `/ready` route returns `503` when runtime state restore or the last snapshot flush failed
-- the service verifier now covers unauthenticated mint, wrong operator tokens, credit overdraw, forged and unsigned checkout webhooks, replayed payment nonces, forged payment signatures, unregistered wallets, and query-token rejection; the MCP executor verifier runs against a mock facilitator
-- the MCP executor publish workflow skips publishing when the registry already carries the current version
-- bundled examples configure a local demo wallet and demo operator tokens explicitly instead of relying on open defaults
+- adds `POST /x402/credits/topup`: pay once with x402 and the facilitator settles the payment on-chain, then the runtime mints the credits to the account and returns the grant, the new balance, and a `PAYMENT-RESPONSE` settlement receipt
+- without a payment the route returns a `402` advertising the same `accepts` plus `credits_per_topup`, so a buyer discovers the price and the credit it buys before paying
+- credits land on `account_id` from the request body, falling back to the paying wallet address
+- idempotent by the payment nonce: re-sending the same settled payment never mints credits twice
+- each top-up grants `XYTARA_X402_TOPUP_UNITS` credit units (default `1000`), unless the matched `accepts` entry sets its own `extra.credits`
+- live only in `x402_facilitator` mode with `accepts` configured; fails closed if the facilitator is unreachable or the payment does not settle
+- extends `npm run verify:x402-facilitator` with the unpaid-challenge, paid-mint, and replay-idempotency cases for the new route
+- adds a runnable buyer, `services/mcp-execution-target/buyer-demo/x402-credits-topup-demo.js`, and documents the route in `REAL_PAYMENT_SETUP.md`
+
+No existing path changes: the per-call x402 routes, native lanes, and operator credit grants all behave exactly as before.

package/examples/generated.carried-handoff.json

@@ -0,0 +1,30 @@
+{
+  "handoff_bundle": {
+    "ok": true,
+    "handoff_kind": "interaction_result_package",
+    "result_package_ref": "result.spine.job.commitment",
+    "source_ref": "spine.job.commitment",
+    "committed_ref": "transaction.job.commitment",
+    "precommit_pack_ref": "precommit.job.commitment.readiness",
+    "transaction_id": "txn_c3db568e78ec",
+    "receipt_id": "rcpt_fc14a1bfa4b5",
+    "proof_ref": "proof_rcpt_fc14a1bfa4b5",
+    "payment_protocol": "x402",
+    "settlement_mode": "evm_payment",
+    "treasury_destination_id": "treasury_acct_demo",
+    "task_refs": [
+      "jobs.quote",
+      "admission.preview",
+      "jobs.reserve",
+      "jobs.commit"
+    ],
+    "delivery_count": 1,
+    "payment_ledger_count": 1,
+    "economic_consequence_handoff_bundle": null,
+    "seam_layers": [
+      "execution_consequence",
+      "payment_settlement_treasury",
+      "proof_handoff"
+    ]
+  }
+}

package/lib/command_flow.js

@@ -311,9 +311,10 @@ async function executeCommandRequest(state, payload, headers, options) {
     };
   }
 
-  const paymentVerification = verifyPaymentAcceptance(state, headers || {}, requiredHeaders, quote, {
+  const paymentVerification = await verifyPaymentAcceptance(state, headers || {}, requiredHeaders, quote, {
     payment_protocol: opts.paymentProtocol || (payload && payload.payment_protocol) || null,
-    authorization_scheme: opts.authorizationScheme || null
+    authorization_scheme: opts.authorizationScheme || null,
+    resource_url: opts.resourceUrl || null
   });
   if (!paymentVerification.ok) {
     return {
@@ -321,6 +322,7 @@ async function executeCommandRequest(state, payload, headers, options) {
       payload: {
         ok: false,
         reason: paymentVerification.reason,
+        ...(paymentVerification.detail ? { detail: paymentVerification.detail } : {}),
         quote
       }
     };
@@ -345,7 +347,10 @@ async function executeCommandRequest(state, payload, headers, options) {
     payload: createCommandResult(state, payload, quote, {
       paymentVerification,
       externalExecution: externalExecutionOptions.externalExecution || null
-    })
+    }),
+    ...(paymentVerification.payment_response_base64
+      ? { paymentResponse: paymentVerification.payment_response_base64 }
+      : {})
   };
 }
 

package/lib/payment_config.js

@@ -121,6 +121,7 @@ function loadPaymentConfig() {
     verification_mode_input: verificationModeInput,
     payment_max_age_seconds: Number.isFinite(maxAgeSeconds) && maxAgeSeconds > 0 ? maxAgeSeconds : 300,
     wallet_registry: loadWalletRegistry(),
+    x402: loadX402FacilitatorConfig(),
     treasury_destination_id: String(process.env.XYTARA_TREASURY_DESTINATION_ID || "").trim() || null,
     treasury_destination_kind: String(process.env.XYTARA_TREASURY_DESTINATION_KIND || "").trim() || null,
     treasury_account_id: String(process.env.XYTARA_TREASURY_ACCOUNT_ID || "").trim() || null,
@@ -129,6 +130,54 @@ function loadPaymentConfig() {
   };
 }
 
+// Configuration for the x402_facilitator verification mode: the on-chain, trustless
+// pay-per-call path. The advertised accepts tell a buyer how to pay; the facilitator
+// verifies and settles the signed payment before any work runs.
+function loadX402FacilitatorConfig() {
+  let accepts = [];
+  const rawAccepts = String(process.env.XYTARA_X402_ACCEPTS_JSON || "").trim();
+  if (rawAccepts) {
+    try {
+      const parsed = JSON.parse(rawAccepts);
+      if (Array.isArray(parsed)) {
+        accepts = parsed
+          .map((entry) => ({
+            scheme: String((entry && entry.scheme) || "exact").trim(),
+            network: String((entry && entry.network) || "").trim(),
+            asset: String((entry && entry.asset) || "").trim(),
+            amount: String((entry && entry.amount) || "").trim(),
+            payTo: String((entry && entry.payTo) || "").trim(),
+            ...(entry && entry.extra && typeof entry.extra === "object" ? { extra: entry.extra } : {}),
+            ...(Number(entry && entry.maxTimeoutSeconds) > 0 ? { maxTimeoutSeconds: Number(entry.maxTimeoutSeconds) } : {})
+          }))
+          .filter((entry) => entry.network && entry.asset && entry.amount && entry.payTo);
+      }
+    } catch (_) {
+      accepts = [];
+    }
+  }
+  let headers = {};
+  const rawHeaders = String(process.env.XYTARA_X402_FACILITATOR_HEADERS_JSON || "").trim();
+  if (rawHeaders) {
+    try {
+      const parsed = JSON.parse(rawHeaders);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) headers = parsed;
+    } catch (_) {
+      headers = {};
+    }
+  }
+  return {
+    accepts,
+    facilitator_url: String(process.env.XYTARA_X402_FACILITATOR_URL || "https://x402.org/facilitator").trim().replace(/\/$/, ""),
+    facilitator_headers: headers,
+    facilitator_timeout_ms: Math.max(1000, Number(process.env.XYTARA_X402_FACILITATOR_TIMEOUT_MS || 15000) || 15000),
+    settle: String(process.env.XYTARA_X402_SETTLE || "true").trim().toLowerCase() !== "false",
+    // Credit units a single self-serve x402 top-up grants, unless the matched accepts
+    // entry carries its own `extra.credits`.
+    topup_units_default: Math.max(0, Number(process.env.XYTARA_X402_TOPUP_UNITS || 1000) || 0)
+  };
+}
+
 function buildConfiguredTreasuryDestination(accountId, settlementMode) {
   const config = loadPaymentConfig();
   const normalizedSettlementMode = normalizeSettlementMode(settlementMode);

package/lib/payment_verification.js

@@ -2,6 +2,12 @@
 
 const crypto = require("crypto");
 const { loadPaymentConfig } = require("./payment_config");
+const {
+  createFacilitatorClient,
+  verifyX402Payment,
+  settleX402Payment,
+  encodePaymentResponse
+} = require("./x402_facilitator");
 const { parseL402Authorization, verifyL402AccessToken } = require("./l402_payment_front");
 const { parseBoltAuthorization, verifyBoltAccessToken } = require("./bolt_payment_front");
 const { parseStripeMppAuthorization, verifyStripeMppAccessToken } = require("./stripe_mpp_payment_front");
@@ -157,10 +163,48 @@ function verifyPaymentPayloadAgainstQuote(paymentPayload, quote, walletId, maxAg
   return { ok: true, age_seconds: ageSeconds };
 }
 
-function verifyPaymentAcceptance(state, headers, requiredHeaders, quote, options) {
+async function verifyPaymentAcceptance(state, headers, requiredHeaders, quote, options) {
   const config = loadPaymentConfig();
   const required = Array.isArray(requiredHeaders) ? requiredHeaders : [];
   const opts = options || {};
+  // Trustless on-chain pay-per-call: the PAYMENT-SIGNATURE carries an x402 v2 payment,
+  // which a facilitator verifies and settles on-chain before any work runs. This path is
+  // opt-in (XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator) and fails closed if the
+  // facilitator is unreachable or the payment does not settle.
+  if (config.verification_mode === "x402_facilitator" && required.includes("payment-signature")) {
+    const h = headers || {};
+    const facilitator = createFacilitatorClient({
+      url: config.x402.facilitator_url,
+      headers: config.x402.facilitator_headers,
+      timeoutMs: config.x402.facilitator_timeout_ms
+    });
+    const auth = await verifyX402Payment({
+      paymentHeader: h["payment-signature"],
+      accepts: config.x402.accepts,
+      resourceUrl: opts.resource_url || null,
+      facilitator
+    });
+    if (!auth.ok) {
+      return { ok: false, status: auth.status || 402, reason: auth.reason, detail: auth.detail || null };
+    }
+    const settled = await settleX402Payment({ authorization: auth.authorization, facilitator, settle: config.x402.settle });
+    if (!settled.ok) {
+      return { ok: false, status: settled.status || 402, reason: settled.reason, detail: settled.detail || null };
+    }
+    return {
+      ok: true,
+      verification_mode: "x402_facilitator",
+      wallet_id: auth.authorization.payer,
+      payment_payload: {
+        x402_payer: auth.authorization.payer,
+        x402_network: auth.authorization.paymentRequirements.network,
+        x402_asset: auth.authorization.paymentRequirements.asset,
+        x402_amount: auth.authorization.paymentRequirements.amount
+      },
+      settlement: settled.settlement,
+      payment_response_base64: encodePaymentResponse(settled.settlement)
+    };
+  }
   if (required.includes("authorization")) {
     if (opts.authorization_scheme === "mpp" || opts.payment_protocol === "mpp") {
       return verifyStripeMppAccessToken(headers || {}, quote);
@@ -171,7 +215,11 @@ function verifyPaymentAcceptance(state, headers, requiredHeaders, quote, options
     return verifyL402AccessToken(headers || {}, quote);
   }
   const payment = parsePayment(headers || {}, requiredHeaders, opts);
-  if (config.verification_mode === "presence") {
+  // x402_facilitator only governs the x402 (payment-signature) routes, handled above.
+  // On the native and instant routes it falls back to local_signed, so enabling the mode
+  // adds trustless on-chain settlement without disabling the existing paid lanes.
+  const nativeMode = config.verification_mode === "x402_facilitator" ? "local_signed" : config.verification_mode;
+  if (nativeMode === "presence") {
     return {
       ok: true,
       verification_mode: "presence",
@@ -180,7 +228,7 @@ function verifyPaymentAcceptance(state, headers, requiredHeaders, quote, options
     };
   }
 
-  if (config.verification_mode !== "local_signed") {
+  if (nativeMode !== "local_signed") {
     return {
       ok: false,
       status: 400,

package/lib/x402_facilitator.js

@@ -0,0 +1,155 @@
+"use strict";
+
+// Self-contained x402 v2 facilitator client for the main runtime.
+//
+// This mirrors the proven logic in services/mcp-execution-target/server.js but takes
+// all configuration as explicit arguments so it has no dependency on any global state
+// and can be reused by any paid route. It is intentionally duplicated rather than shared
+// with the standalone MCP executor, which deploys from its own subdirectory.
+//
+// The trust model is the same one proven live: this process never verifies balances or
+// broadcasts transfers itself. It asks an x402 facilitator to verify the buyer's signed
+// EIP-3009 authorization and to settle it on-chain, and refuses to serve work unless the
+// facilitator confirms both. If the facilitator is unreachable, access fails closed.
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeAddress(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+// Decode a PAYMENT-SIGNATURE header into an x402 v2 payment payload.
+function decodePaymentSignatureHeader(value) {
+  const raw = normalizeString(value);
+  if (!raw) return null;
+  for (const encoding of ["base64url", "base64"]) {
+    try {
+      const decoded = Buffer.from(raw, encoding).toString("utf8");
+      const parsed = JSON.parse(decoded);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      if (Number(parsed.x402Version) !== 2) continue;
+      if (!parsed.accepted || typeof parsed.accepted !== "object") continue;
+      if (!parsed.payload || typeof parsed.payload !== "object") continue;
+      return parsed;
+    } catch (_) {
+      // try the next encoding
+    }
+  }
+  return null;
+}
+
+// Find the advertised requirements entry the buyer claims to be paying.
+function matchAcceptedRequirements(paymentPayload, accepts) {
+  const accepted = paymentPayload && paymentPayload.accepted ? paymentPayload.accepted : null;
+  if (!accepted || !Array.isArray(accepts)) return null;
+  return (
+    accepts.find(
+      (entry) =>
+        entry.scheme === normalizeString(accepted.scheme) &&
+        entry.network === normalizeString(accepted.network) &&
+        normalizeAddress(entry.asset) === normalizeAddress(accepted.asset) &&
+        normalizeAddress(entry.payTo) === normalizeAddress(accepted.payTo) &&
+        String(entry.amount) === String(accepted.amount)
+    ) || null
+  );
+}
+
+function createFacilitatorClient(config) {
+  const url = normalizeString(config && config.url).replace(/\/$/, "");
+  const headers = config && config.headers && typeof config.headers === "object" ? config.headers : {};
+  const timeoutMs = Math.max(1000, Number(config && config.timeoutMs) || 15000);
+
+  async function post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetch(`${url}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json", ...headers },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      const text = await response.text();
+      let json = null;
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch (_) {
+        json = null;
+      }
+      return { ok: response.ok, status: response.status, json };
+    } catch (error) {
+      return { ok: false, status: 0, json: null, error: error && error.message ? error.message : "facilitator_request_failed" };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return {
+    verify: (payload, requirements) => post("/verify", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements }),
+    settle: (payload, requirements) => post("/settle", { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements })
+  };
+}
+
+// Verify a buyer's x402 payment against the advertised requirements via the facilitator.
+// Returns { ok:true, authorization } or { ok:false, status:402, reason, detail }.
+async function verifyX402Payment({ paymentHeader, accepts, resourceUrl, facilitator }) {
+  const header = normalizeString(paymentHeader);
+  if (!header) {
+    return { ok: false, status: 402, reason: "payment_required" };
+  }
+  const paymentPayload = decodePaymentSignatureHeader(header);
+  if (!paymentPayload) {
+    return { ok: false, status: 402, reason: "payment_signature_invalid", detail: "PAYMENT-SIGNATURE must be a base64 JSON x402 v2 payment payload" };
+  }
+  const paymentRequirements = matchAcceptedRequirements(paymentPayload, accepts);
+  if (!paymentRequirements) {
+    return { ok: false, status: 402, reason: "payment_requirements_mismatch", detail: "accepted requirements do not match any advertised payment option" };
+  }
+  const requirementsForFacilitator = { ...paymentRequirements, resource: resourceUrl };
+  const verification = await facilitator.verify(paymentPayload, requirementsForFacilitator);
+  if (!verification.ok || !verification.json) {
+    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: verification.error || `facilitator verify returned HTTP ${verification.status}` };
+  }
+  if (verification.json.isValid !== true) {
+    return { ok: false, status: 402, reason: "payment_verification_failed", detail: normalizeString(verification.json.invalidReason) || "facilitator rejected the payment" };
+  }
+  return {
+    ok: true,
+    authorization: {
+      paymentPayload,
+      paymentRequirements: requirementsForFacilitator,
+      payer: normalizeString(verification.json.payer) || null
+    }
+  };
+}
+
+// Settle a verified payment on-chain via the facilitator (unless settlement is disabled).
+// Returns { ok:true, settlement } or { ok:false, status:402, reason, detail }.
+async function settleX402Payment({ authorization, facilitator, settle }) {
+  if (settle === false) {
+    return { ok: true, settlement: { success: true, skipped: true, reason: "settlement_disabled_by_operator", payer: authorization.payer } };
+  }
+  const settlement = await facilitator.settle(authorization.paymentPayload, authorization.paymentRequirements);
+  if (!settlement.ok || !settlement.json) {
+    return { ok: false, status: 402, reason: "facilitator_unreachable", detail: settlement.error || `facilitator settle returned HTTP ${settlement.status}` };
+  }
+  if (settlement.json.success !== true) {
+    return { ok: false, status: 402, reason: "payment_settlement_failed", detail: normalizeString(settlement.json.errorReason) || "facilitator could not settle the payment" };
+  }
+  return { ok: true, settlement: settlement.json };
+}
+
+function encodePaymentResponse(settlement) {
+  return Buffer.from(JSON.stringify(settlement), "utf8").toString("base64");
+}
+
+module.exports = {
+  decodePaymentSignatureHeader,
+  matchAcceptedRequirements,
+  createFacilitatorClient,
+  verifyX402Payment,
+  settleX402Payment,
+  encodePaymentResponse
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "description": "Agent-commerce runtime for quote, pay, execute, deliver, meter, and integrate.",
   "main": "index.js",
   "bin": {
@@ -99,7 +99,8 @@
     "verify:release-candidate": "node scripts/verify_release_candidate.js",
     "verify:production-readiness": "node scripts/verify_production_readiness.js",
     "verify:final-activation": "node scripts/verify_final_activation.js",
-    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_control_plane_contracts.js && node scripts/verify_control_plane_routes.js && node scripts/verify_framework_provider_promotion.js && node scripts/verify_operator_observability_boundary.js && node scripts/verify_pricing_experiment_plan.js && node scripts/verify_treasury_public_boundary.js && node scripts/verify_market_lanes.js && node scripts/verify_market_lane_depth.js && node scripts/verify_market_lane_traces.js && node scripts/verify_market_lane_promotion.js && node scripts/verify_provider_runtime_breadth.js && node scripts/verify_provider_runtime_journeys.js && node scripts/verify_lifecycle_continuity.js && node scripts/verify_first_run_conversions.js && node scripts/verify_delivery_summary.js && node scripts/verify_runtime_durability.js && node scripts/verify_revenue_launch_paths.js && node scripts/verify_full_catalog.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js",
+    "verify:x402-facilitator": "node scripts/verify_x402_facilitator.js",
+    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_control_plane_contracts.js && node scripts/verify_control_plane_routes.js && node scripts/verify_framework_provider_promotion.js && node scripts/verify_operator_observability_boundary.js && node scripts/verify_pricing_experiment_plan.js && node scripts/verify_treasury_public_boundary.js && node scripts/verify_market_lanes.js && node scripts/verify_market_lane_depth.js && node scripts/verify_market_lane_traces.js && node scripts/verify_market_lane_promotion.js && node scripts/verify_provider_runtime_breadth.js && node scripts/verify_provider_runtime_journeys.js && node scripts/verify_lifecycle_continuity.js && node scripts/verify_first_run_conversions.js && node scripts/verify_delivery_summary.js && node scripts/verify_runtime_durability.js && node scripts/verify_revenue_launch_paths.js && node scripts/verify_full_catalog.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js && node scripts/verify_x402_facilitator.js",
     "prepublishOnly": "npm run verify:release-candidate"
   }
 }

package/scripts/verify_x402_facilitator.js

@@ -0,0 +1,194 @@
+"use strict";
+
+// Verifies the x402_facilitator payment mode end to end against a mock facilitator:
+//   - an unpaid x402 execute returns 402 and advertises the configured accepts
+//   - a well-formed payment is verified and settled, the command runs, and the
+//     response carries a PAYMENT-RESPONSE settlement receipt
+//   - malformed, mismatched, facilitator-rejected, and unsettled payments all 402
+//
+// No real network or chain is used; the mock facilitator stands in for x402.org.
+
+const assert = require("assert");
+const http = require("http");
+
+const ACCEPTS = [
+  {
+    scheme: "exact",
+    network: "eip155:84532",
+    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    amount: "1000",
+    payTo: "0x7cd2E0Ed2721319B20FAac4109774d030833F84D",
+    extra: { name: "USDC", version: "2" },
+    maxTimeoutSeconds: 60
+  }
+];
+
+function startMockFacilitator() {
+  const calls = { verify: 0, settle: 0 };
+  const server = http.createServer((req, res) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      let body = {};
+      try { body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"); } catch (_) { body = {}; }
+      const sig = body && body.paymentPayload && body.paymentPayload.payload ? String(body.paymentPayload.payload.signature || "") : "";
+      const reply = (payload) => {
+        const text = JSON.stringify(payload);
+        res.writeHead(200, { "content-type": "application/json", "content-length": Buffer.byteLength(text) });
+        res.end(text);
+      };
+      if (req.method === "POST" && req.url === "/verify") {
+        calls.verify += 1;
+        if (sig === "reject-me") return reply({ isValid: false, invalidReason: "invalid_signature" });
+        return reply({ isValid: true, payer: "0x1111111111111111111111111111111111111111" });
+      }
+      if (req.method === "POST" && req.url === "/settle") {
+        calls.settle += 1;
+        if (sig === "settle-fails") return reply({ success: false, errorReason: "insufficient_funds" });
+        return reply({ success: true, transaction: "0xmocktx", network: "eip155:84532", payer: "0x1111111111111111111111111111111111111111" });
+      }
+      res.writeHead(404); res.end();
+    });
+  });
+  return new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve({ server, calls, port: server.address().port })));
+}
+
+function paymentHeader(signature, overrides = {}) {
+  const accepted = ACCEPTS[0];
+  return Buffer.from(JSON.stringify({
+    x402Version: 2,
+    accepted: { ...accepted, ...overrides.accepted },
+    payload: {
+      signature,
+      authorization: {
+        from: "0x1111111111111111111111111111111111111111",
+        to: accepted.payTo,
+        value: accepted.amount,
+        validAfter: "0",
+        validBefore: String(Math.floor(Date.now() / 1000) + 600),
+        nonce: `0x${"ab".repeat(32)}`
+      }
+    }
+  }), "utf8").toString("base64");
+}
+
+async function post(baseUrl, path, body, headers = {}) {
+  const res = await fetch(`${baseUrl}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify(body)
+  });
+  let json = null;
+  try { json = await res.json(); } catch (_) { json = null; }
+  return { status: res.status, json, headers: res.headers };
+}
+
+async function main() {
+  const facilitator = await startMockFacilitator();
+  const previous = {
+    mode: process.env.XYTARA_PAYMENT_VERIFICATION_MODE,
+    accepts: process.env.XYTARA_X402_ACCEPTS_JSON,
+    facUrl: process.env.XYTARA_X402_FACILITATOR_URL
+  };
+  process.env.XYTARA_PAYMENT_VERIFICATION_MODE = "x402_facilitator";
+  process.env.XYTARA_X402_ACCEPTS_JSON = JSON.stringify(ACCEPTS);
+  process.env.XYTARA_X402_FACILITATOR_URL = `http://127.0.0.1:${facilitator.port}`;
+
+  delete require.cache[require.resolve("../server")];
+  const { createServer } = require("../server");
+  const server = createServer();
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const baseUrl = `http://127.0.0.1:${server.address().port}`;
+  const execBody = { account_id: "acct_x402", command: "x402 facilitator demo", task_ref: "trust.verify", body: { subject_id: "s-1" } };
+
+  try {
+    // 1. Unpaid -> 402 advertising accepts.
+    const unpaid = await post(baseUrl, "/x402/commands/execute", execBody);
+    assert.strictEqual(unpaid.status, 402, "unpaid x402 execute must return 402");
+    const required = unpaid.json && unpaid.json.payment_required;
+    assert.ok(required, "402 must carry payment_required");
+    assert.strictEqual(required.x402Version, 2, "challenge must be x402 v2");
+    assert.ok(Array.isArray(required.accepts) && required.accepts.length === 1, "challenge must advertise accepts");
+    assert.strictEqual(required.accepts[0].network, "eip155:84532", "advertised network mismatch");
+    assert.strictEqual(typeof unpaid.headers.get("payment-required"), "string", "PAYMENT-REQUIRED header missing");
+
+    // 2. Bogus header -> 402 payment_signature_invalid.
+    const bogus = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": "not-a-payment" });
+    assert.strictEqual(bogus.status, 402, "bogus payment header must 402");
+    assert.strictEqual(bogus.json.reason, "payment_signature_invalid", "bogus reason mismatch");
+
+    // 3. Mismatched requirements -> 402 before the facilitator.
+    const verifyBefore = facilitator.calls.verify;
+    const mismatch = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("ok", { accepted: { amount: "9" } }) });
+    assert.strictEqual(mismatch.status, 402, "mismatched requirements must 402");
+    assert.strictEqual(mismatch.json.reason, "payment_requirements_mismatch", "mismatch reason");
+    assert.strictEqual(facilitator.calls.verify, verifyBefore, "facilitator must not be called on a requirements mismatch");
+
+    // 4. Facilitator rejects -> 402 payment_verification_failed.
+    const rejected = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("reject-me") });
+    assert.strictEqual(rejected.status, 402, "facilitator-rejected payment must 402");
+    assert.strictEqual(rejected.json.reason, "payment_verification_failed", "rejection reason");
+    assert.strictEqual(rejected.json.detail, "invalid_signature", "rejection detail");
+
+    // 5. Settlement fails -> 402, no tool output.
+    const settleFails = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("settle-fails") });
+    assert.strictEqual(settleFails.status, 402, "failed settlement must 402");
+    assert.strictEqual(settleFails.json.reason, "payment_settlement_failed", "settlement failure reason");
+
+    // 6. Verified + settled -> 200 with a result and a PAYMENT-RESPONSE receipt.
+    const settleBefore = facilitator.calls.settle;
+    const paid = await post(baseUrl, "/x402/commands/execute", execBody, { "payment-signature": paymentHeader("ok") });
+    assert.strictEqual(paid.status, 200, "verified+settled payment must 200");
+    assert.strictEqual(typeof paid.json.transaction.transaction_id, "string", "paid result missing transaction");
+    assert.strictEqual(paid.json.transaction.status, "completed", "paid transaction must be completed");
+    assert.strictEqual(paid.json.transaction.payment.verification_mode, "x402_facilitator", "verification mode not recorded");
+    assert.strictEqual(facilitator.calls.settle, settleBefore + 1, "facilitator settle must be called once");
+    const receiptHeader = paid.headers.get("payment-response");
+    assert.strictEqual(typeof receiptHeader, "string", "PAYMENT-RESPONSE header missing on a settled 200");
+    const receipt = JSON.parse(Buffer.from(receiptHeader, "base64").toString("utf8"));
+    assert.strictEqual(receipt.success, true, "settlement receipt must report success");
+    assert.strictEqual(receipt.transaction, "0xmocktx", "settlement receipt transaction mismatch");
+
+    // 7. Native routes must not be disabled by x402_facilitator: a native paid attempt
+    //    falls back to local_signed semantics, never payment_verification_mode_unsupported.
+    const nativeAttempt = await post(baseUrl, "/v1/commands/execute", execBody, {
+      "x-wallet-id": "wallet-not-registered",
+      "x-payment": "encoded",
+      "x-payment-signature": "sig"
+    });
+    assert.notStrictEqual(nativeAttempt.json && nativeAttempt.json.reason, "payment_verification_mode_unsupported", "native route must fall back to local_signed under x402_facilitator");
+
+    // 8. Self-serve credits top-up: unpaid -> 402 advertising accepts + credits_per_topup.
+    const topupUnpaid = await post(baseUrl, "/x402/credits/topup", { account_id: "acct_topup" });
+    assert.strictEqual(topupUnpaid.status, 402, "unpaid topup must 402");
+    assert.ok(Array.isArray(topupUnpaid.json.payment_required.accepts), "topup 402 must advertise accepts");
+    assert.strictEqual(typeof topupUnpaid.json.payment_required.credits_per_topup, "number", "topup 402 must state credits_per_topup");
+
+    // 9. Paid top-up -> 200, credits minted to the account, with a settlement receipt.
+    const topupPaid = await post(baseUrl, "/x402/credits/topup", { account_id: "acct_topup" }, { "payment-signature": paymentHeader("ok") });
+    assert.strictEqual(topupPaid.status, 200, "paid topup must 200");
+    assert.strictEqual(topupPaid.json.ok, true, "paid topup must be ok");
+    assert.strictEqual(typeof topupPaid.json.credit_grant, "object", "paid topup must return a credit grant");
+    const grantedUnits = Number(topupPaid.json.balance.available_units);
+    assert.ok(grantedUnits > 0, "paid topup must leave a positive credit balance");
+    assert.strictEqual(typeof topupPaid.headers.get("payment-response"), "string", "paid topup must carry a settlement receipt");
+
+    // 10. Replayed top-up (same payment nonce) is idempotent: no double-mint.
+    const topupReplay = await post(baseUrl, "/x402/credits/topup", { account_id: "acct_topup" }, { "payment-signature": paymentHeader("ok") });
+    assert.strictEqual(topupReplay.status, 200, "replayed topup must still 200");
+    assert.strictEqual(Number(topupReplay.json.balance.available_units), grantedUnits, "replayed topup must not mint credits twice");
+
+    console.log("xytara verify:x402-facilitator passed");
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+    await new Promise((resolve) => facilitator.server.close(resolve));
+    if (previous.mode === undefined) delete process.env.XYTARA_PAYMENT_VERIFICATION_MODE; else process.env.XYTARA_PAYMENT_VERIFICATION_MODE = previous.mode;
+    if (previous.accepts === undefined) delete process.env.XYTARA_X402_ACCEPTS_JSON; else process.env.XYTARA_X402_ACCEPTS_JSON = previous.accepts;
+    if (previous.facUrl === undefined) delete process.env.XYTARA_X402_FACILITATOR_URL; else process.env.XYTARA_X402_FACILITATOR_URL = previous.facUrl;
+  }
+}
+
+main().catch((error) => {
+  console.error(error && error.message ? error.message : error);
+  process.exitCode = 1;
+});

package/server.js

@@ -49,6 +49,67 @@ function buildPaymentRequiredHeaders(paymentRequiredPayload) {
     "Cache-Control": "no-store"
   };
 }
+
+const {
+  createFacilitatorClient: createX402FacilitatorClient,
+  verifyX402Payment,
+  settleX402Payment,
+  encodePaymentResponse: encodeX402PaymentResponse
+} = require("./lib/x402_facilitator");
+
+// Verify and settle an x402 payment for a standalone route (not the command flow).
+// Returns { ok:true, settlement, authorization, paymentResponse } or
+// { ok:false, status, reason, detail, challenge } where challenge means a 402 is appropriate.
+async function settleX402ForRoute(req, url) {
+  const config = loadPaymentConfig();
+  if (config.verification_mode !== "x402_facilitator") {
+    return { ok: false, status: 400, reason: "x402_facilitator_mode_not_enabled" };
+  }
+  if (!config.x402.accepts.length) {
+    return { ok: false, status: 400, reason: "x402_accepts_not_configured" };
+  }
+  const facilitator = createX402FacilitatorClient({
+    url: config.x402.facilitator_url,
+    headers: config.x402.facilitator_headers,
+    timeoutMs: config.x402.facilitator_timeout_ms
+  });
+  const auth = await verifyX402Payment({
+    paymentHeader: (req.headers || {})["payment-signature"],
+    accepts: config.x402.accepts,
+    resourceUrl: buildRequestResourceUrl(req, url),
+    facilitator
+  });
+  if (!auth.ok) {
+    return { ok: false, status: auth.status || 402, reason: auth.reason, detail: auth.detail || null, challenge: true };
+  }
+  const settled = await settleX402Payment({ authorization: auth.authorization, facilitator, settle: config.x402.settle });
+  if (!settled.ok) {
+    return { ok: false, status: settled.status || 402, reason: settled.reason, detail: settled.detail || null, challenge: true };
+  }
+  return { ok: true, settlement: settled.settlement, authorization: auth.authorization, paymentResponse: encodeX402PaymentResponse(settled.settlement) };
+}
+
+// The public resource URL of the current request, used as the x402 payment resource.
+function buildRequestResourceUrl(req, url) {
+  const headers = (req && req.headers) || {};
+  const forwardedProto = String(headers["x-forwarded-proto"] || "").split(",")[0].trim();
+  const protocol = forwardedProto || (process.env.RENDER ? "https" : "http");
+  const host = String(headers["x-forwarded-host"] || headers.host || "").split(",")[0].trim();
+  if (!host) return null;
+  return `${protocol}://${host}${url.pathname}`;
+}
+
+// Response headers for an x402 route: PAYMENT-REQUIRED on a 402 challenge, or
+// PAYMENT-RESPONSE carrying the settlement receipt on a settled 200.
+function buildX402ResponseHeaders(result) {
+  if (result && result.status === 402 && result.payload && result.payload.payment_required) {
+    return buildPaymentRequiredHeaders(result.payload.payment_required);
+  }
+  if (result && result.status === 200 && result.paymentResponse) {
+    return { "PAYMENT-RESPONSE": result.paymentResponse, "Cache-Control": "no-store" };
+  }
+  return undefined;
+}
 const {
   completePendingExecution,
   createCommandResult,
@@ -8898,24 +8959,91 @@ async function routeRequest(req, res) {
       ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
       payment_protocol: "x402"
     };
+    const x402Accepts = loadPaymentConfig().x402.accepts;
     const result = await executeCommandRequest(state, payload, req.headers, {
       requiredHeaders: ["payment-signature"],
+      resourceUrl: buildRequestResourceUrl(req, url),
       challengePayload: (quote) => ({
         ok: false,
         payment_required: {
+          x402Version: 2,
           scheme: "exact",
-          quote
+          quote,
+          ...(x402Accepts.length > 0 ? { accepts: x402Accepts } : {})
         }
       })
     });
-    sendJson(
-      res,
-      result.status,
-      result.payload,
-      result.status === 402 && result.payload && result.payload.payment_required
-        ? buildPaymentRequiredHeaders(result.payload.payment_required)
-        : undefined
-    );
+    sendJson(res, result.status, result.payload, buildX402ResponseHeaders(result));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/x402/credits/topup") {
+    // Self-serve credits: pay once with x402 and credits are minted to the account, with no
+    // operator grant. Only available when the runtime is in x402_facilitator mode with accepts set.
+    const body = await readJsonBody(req);
+    const config = loadPaymentConfig();
+    if (config.verification_mode !== "x402_facilitator") {
+      sendJson(res, 400, { ok: false, reason: "x402_facilitator_mode_not_enabled" });
+      return;
+    }
+    if (!config.x402.accepts.length) {
+      sendJson(res, 400, { ok: false, reason: "x402_accepts_not_configured" });
+      return;
+    }
+    const topupUnitsFor = (accept) => {
+      const perAccept = accept && accept.extra && Number(accept.extra.credits);
+      return Number.isFinite(perAccept) && perAccept > 0 ? perAccept : config.x402.topup_units_default;
+    };
+    const paymentSignatureHeader = ((req.headers || {})["payment-signature"] || "").trim();
+    if (!paymentSignatureHeader) {
+      const paymentRequired = {
+        x402Version: 2,
+        scheme: "exact",
+        accepts: config.x402.accepts,
+        credits_per_topup: topupUnitsFor(config.x402.accepts[0])
+      };
+      sendJson(res, 402, { ok: false, payment_required: paymentRequired }, buildPaymentRequiredHeaders(paymentRequired));
+      return;
+    }
+    const settled = await settleX402ForRoute(req, url);
+    if (!settled.ok) {
+      const payload = { ok: false, reason: settled.reason, ...(settled.detail ? { detail: settled.detail } : {}) };
+      let extraHeaders;
+      if (settled.challenge) {
+        payload.payment_required = { x402Version: 2, scheme: "exact", accepts: config.x402.accepts };
+        extraHeaders = buildPaymentRequiredHeaders(payload.payment_required);
+      }
+      sendJson(res, settled.status, payload, extraHeaders);
+      return;
+    }
+    const matched = settled.authorization.paymentRequirements;
+    const bodyAccountId = body && typeof body.account_id === "string" ? body.account_id.trim() : "";
+    const accountId = bodyAccountId || settled.authorization.payer || "acct_demo";
+    const nonce = settled.authorization.paymentPayload
+      && settled.authorization.paymentPayload.payload
+      && settled.authorization.paymentPayload.payload.authorization
+      ? settled.authorization.paymentPayload.payload.authorization.nonce
+      : null;
+    const grant = createExternalCreditGrant(state, {
+      account_id: accountId,
+      units: topupUnitsFor(matched),
+      source: "x402_settlement",
+      provider_reference: settled.settlement.transaction || null,
+      idempotency_key: nonce ? `x402:${nonce}` : null,
+      metadata: {
+        x402_payer: settled.authorization.payer,
+        x402_network: matched.network,
+        x402_asset: matched.asset,
+        x402_amount: matched.amount
+      }
+    });
+    sendJson(res, 200, {
+      ok: true,
+      account_id: accountId,
+      credit_grant: grant,
+      balance: buildCreditBalanceSummary(state, accountId),
+      settlement: settled.settlement
+    }, { "PAYMENT-RESPONSE": settled.paymentResponse, "Cache-Control": "no-store" });
     return;
   }
 
@@ -10566,24 +10694,21 @@ async function routeRequest(req, res) {
   if (req.method === "POST" && url.pathname === "/x402/mcp/tools/invoke") {
     const body = await readJsonBody(req);
     const payload = buildMcpInvokePayload(body, { paymentProtocol: "x402" });
+    const x402Accepts = loadPaymentConfig().x402.accepts;
     const result = await executeCommandRequest(state, payload, req.headers, {
       requiredHeaders: ["payment-signature"],
+      resourceUrl: buildRequestResourceUrl(req, url),
       challengePayload: (quote) => ({
         ok: false,
         payment_required: {
+          x402Version: 2,
           scheme: "exact",
-          quote
+          quote,
+          ...(x402Accepts.length > 0 ? { accepts: x402Accepts } : {})
         }
       })
     });
-    sendJson(
-      res,
-      result.status,
-      result.payload,
-      result.status === 402 && result.payload && result.payload.payment_required
-        ? buildPaymentRequiredHeaders(result.payload.payment_required)
-        : undefined
-    );
+    sendJson(res, result.status, result.payload, buildX402ResponseHeaders(result));
     return;
   }