xytara 3.1.3 → 3.1.4

package/REAL_PAYMENT_SETUP.md

@@ -65,6 +65,29 @@ mode with `XYTARA_X402_ACCEPTS_JSON` set, and credits persist only when runtime
 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,16 +1,9 @@
-`xytara` 3.1.3 makes runtime credits self-serve: a buyer can turn a single x402 payment into spendable credit with no operator grant.
+`xytara` 3.1.4 makes the self-serve credits capability discoverable and documents the path to Base mainnet.
 
-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.
+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 `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.
+- 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_c3db568e78ec",
-    "receipt_id": "rcpt_fc14a1bfa4b5",
-    "proof_ref": "proof_rcpt_fc14a1bfa4b5",
+    "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/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.3",
+  "version": "3.1.4",
   "description": "Agent-commerce runtime for quote, pay, execute, deliver, meter, and integrate.",
   "main": "index.js",
   "bin": {