xytara 3.1.2 → 3.1.4

package/.env.example

@@ -10,6 +10,9 @@ 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/REAL_PAYMENT_SETUP.md

@@ -45,6 +45,49 @@ is identical to the one in `services/mcp-execution-target/buyer-demo/` (an EIP-3
 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`.
+
+### Going to Base mainnet (real USDC)
+
+Base Sepolia uses test USDC. To accept real value, advertise a Base mainnet profile and
+settle it through a mainnet-capable facilitator.
+
+Important: the default `https://x402.org/facilitator` settles **Base Sepolia only** (its
+`/supported` list has no `eip155:8453`). Pointing a mainnet `accepts` entry at it fails
+closed and the route is unpayable. For mainnet you need a mainnet-capable facilitator, such
+as Coinbase CDP (`https://api.cdp.coinbase.com/platform/v2/x402`), which requires a CDP API
+key passed as auth:
+
+```env
+# advertise mainnet (real USDC on Base); you can keep a Sepolia entry in the array too
+XYTARA_X402_ACCEPTS_JSON=[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"10000","payTo":"<your-evm-address>","extra":{"name":"USDC","version":"2"},"maxTimeoutSeconds":60}]
+# a mainnet-capable facilitator (CDP shown) and its auth header:
+XYTARA_X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
+XYTARA_X402_FACILITATOR_HEADERS_JSON={"Authorization":"Bearer <cdp-access-token>"}
+```
+
+`amount` is in the asset's base units (USDC has 6 decimals, so `10000` = 0.01 USDC). Confirm
+your facilitator lists `eip155:8453` in its `/supported` response before advertising it, and
+remember that once mainnet is live, buyers spend real USDC.
+
 ## Minimum Production-Oriented Configuration
 
 Set these environment variables:

package/RELEASE_NOTES.md

@@ -1,14 +1,9 @@
-`xytara` 3.1.2 adds trustless, on-chain, pay-per-call settlement to the main runtime.
+`xytara` 3.1.4 makes the self-serve credits capability discoverable and documents the path to Base mainnet.
 
-This release brings the facilitator verify-and-settle mechanism already proven on the public MCP executor to the runtime itself, so every x402 route can settle a real payment on-chain before any work runs, not just the standalone tool server.
+This is a discovery and documentation release on top of the self-serve credits shipped earlier in the line. No existing behavior changes.
 
 Highlights:
 
-- adds a third payment-acceptance mode, `x402_facilitator`, enabled with `XYTARA_PAYMENT_VERIFICATION_MODE=x402_facilitator`
-- when enabled, `/x402/commands/execute` and `/x402/mcp/tools/invoke` return a `402` that advertises the configured `accepts` (network, asset, amount, payTo) in the `PAYMENT-REQUIRED` header
-- a buyer signs a gasless USDC authorization (EIP-3009); on the paid retry a facilitator verifies and settles it on-chain before any work runs, and the response carries a `PAYMENT-RESPONSE` settlement receipt
-- fails closed: if the facilitator is unreachable or the payment does not settle, nothing runs and no result is returned
-- the mode governs only the x402 routes; native and instant lanes fall back to `local_signed`, so no existing paid path is disabled
-- keeps `local_signed` as the default and `presence` as the local-development opt-in
-- adds `npm run verify:x402-facilitator`, an end-to-end check against a mock facilitator covering the advertised challenge, malformed and mismatched payments, facilitator rejection, failed settlement, and a settled success with receipt
-- documents the mode and its environment in `REAL_PAYMENT_SETUP.md` and the architecture in `ARCHITECTURE.md`
+- the x402 lane summary (`/v1/x402/summary`) and lane pack now advertise `credits_topup_ref` (`/x402/credits/topup`) and a `self_serve_credits` first-run flow, so agents discovering the runtime see the pay-once-get-credits path alongside direct command execution and paid MCP tooling
+- documents going to Base mainnet in `REAL_PAYMENT_SETUP.md`: the mainnet `accepts` profile (real USDC on `eip155:8453`) and the requirement for a mainnet-capable facilitator, since the default `x402.org` facilitator settles Base Sepolia only
+- no change to payment verification, settlement, the credits ledger, or any existing route

package/examples/generated.carried-handoff.json

@@ -6,9 +6,9 @@
     "source_ref": "spine.job.commitment",
     "committed_ref": "transaction.job.commitment",
     "precommit_pack_ref": "precommit.job.commitment.readiness",
-    "transaction_id": "txn_7f5d7cd15658",
-    "receipt_id": "rcpt_2684569e5241",
-    "proof_ref": "proof_rcpt_2684569e5241",
+    "transaction_id": "txn_01b29e65db7d",
+    "receipt_id": "rcpt_b40aa20be45e",
+    "proof_ref": "proof_rcpt_b40aa20be45e",
     "payment_protocol": "x402",
     "settlement_mode": "evm_payment",
     "treasury_destination_id": "treasury_acct_demo",

package/lib/payment_config.js

@@ -171,7 +171,10 @@ function loadX402FacilitatorConfig() {
     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"
+    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)
   };
 }
 

package/lib/x402_lane_contract.js

@@ -36,6 +36,7 @@ function buildX402LanePack() {
       quote_detail_ref_template: "/v1/payment-quotes/:quote_id",
       command_execute_ref: "/x402/commands/execute",
       mcp_paid_invoke_ref: "/x402/mcp/tools/invoke",
+      credits_topup_ref: "/x402/credits/topup",
       payment_ledger_ref: "/v1/payment-ledger",
       native_settlement_ref: "/v1/settlement/bsv-teranode",
       native_settlement_readiness_ref: "/v1/settlement/bsv-teranode/readiness",
@@ -74,6 +75,21 @@ function buildX402LanePack() {
           paid_invoke_ref: "/x402/mcp/tools/invoke",
           settlement_ref: "/v1/settlement/bsv-teranode"
         }
+      },
+      {
+        flow_ref: "x402.self_serve_credits",
+        recommended_reason: "pay once with x402 and receive spendable runtime credits, with no operator grant",
+        sequence: [
+          "request_topup_without_payment",
+          "receive_x402_challenge_with_credits_per_topup",
+          "pay_and_mint_credits",
+          "spend_credits_on_subsequent_calls"
+        ],
+        example_surfaces: {
+          credits_topup_ref: "/x402/credits/topup",
+          command_execute_ref: "/x402/commands/execute",
+          payment_ledger_ref: "/v1/payment-ledger"
+        }
       }
     ],
     settlement_posture: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "3.1.2",
+  "version": "3.1.4",
   "description": "Agent-commerce runtime for quote, pay, execute, deliver, meter, and integrate.",
   "main": "index.js",
   "bin": {

package/scripts/verify_x402_facilitator.js

@@ -158,6 +158,26 @@ async function main() {
     });
     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));

package/server.js

@@ -50,6 +50,45 @@ function buildPaymentRequiredHeaders(paymentRequiredPayload) {
   };
 }
 
+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) || {};
@@ -8938,6 +8977,76 @@ async function routeRequest(req, res) {
     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;
+  }
+
   if (req.method === "POST" && url.pathname === "/l402/commands/execute") {
     const body = await readJsonBody(req);
     const payload = {