agentpay-mcp 4.1.0 → 4.1.4

package/docs/x402-scanner-readiness.md

@@ -0,0 +1,110 @@
+# x402 scanner-readiness recipe for AgentPay MCP
+
+External scanners now need a cheap way to answer one question before they spend engineering time on a paid endpoint: does this service speak x402, and where is the protected endpoint?
+
+This recipe makes that answer machine-readable without giving agents unlimited spending authority.
+
+## What to expose
+
+A scanner-ready AgentPay MCP demo should expose a dedicated, clean 402 probe route first:
+
+1. `/api/x402/demo` returns `402 Payment Required` with `PAYMENT-REQUIRED` and x402 payment metadata. This is the scanner target.
+2. `X-X402-Supported: true` on the service home page or docs landing page points humans and crawlers to x402 support.
+3. A `sitemap.xml`, docs page, or `Link` header lists `/api/x402/demo` so crawlers do not have to guess paths.
+
+Do not rely on headers, sitemap entries, or Link headers alone. The x402 Foundation scanner path changed after `/protected`, sitemap discovery, `Link` headers, and `X-X402-Supported` did not give isitagentready.com a stable pass. A clean API-style 402 route is now the recommended readiness signal.
+
+The scanner route is not the payment control. It is a discovery layer. AgentPay MCP still owns approval, policy checks, spend caps, wallet signing, settlement audit rows, and fail-closed behavior.
+
+## Minimal HTTP pattern
+
+```ts
+import http from "node:http";
+
+const demoUrl = "https://agentpay.example.com/api/x402/demo";
+
+http.createServer((request, response) => {
+  response.setHeader("X-X402-Supported", "true");
+
+  if (request.url === "/sitemap.xml") {
+    response.setHeader("Content-Type", "application/xml");
+    response.end(`<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>${demoUrl}</loc></url>
+</urlset>`);
+    return;
+  }
+
+  if (request.url === "/api/x402/demo") {
+    response.writeHead(402, {
+      "Content-Type": "application/json",
+      "X-X402-Supported": "true",
+    });
+    response.end(JSON.stringify({
+      error: "Payment Required",
+      x402Version: "2",
+      accepts: [{
+        scheme: "exact",
+        network: "base",
+        amount: "10000",
+        asset: "USDC",
+        resource: demoUrl,
+      }],
+    }));
+    return;
+  }
+
+  response.writeHead(200, { "Content-Type": "text/plain" });
+  response.end("AgentPay MCP demo. See /sitemap.xml and /api/x402/demo.\n");
+}).listen(8787);
+```
+
+## Runnable demo
+
+A minimal Node route lives at `examples/x402-clean-demo/server.mjs`. It is intentionally small so teams can copy the scanner contract without copying wallet logic into the demo endpoint.
+
+```bash
+node examples/x402-clean-demo/server.mjs
+curl -si http://127.0.0.1:8787/api/x402/demo | head -n 12
+```
+
+Expected result: HTTP `402`, `PAYMENT-REQUIRED: true`, `X-X402-Supported: true`, and a JSON body with x402 payment metadata.
+
+## AgentPay MCP payment flow
+
+1. Scanner calls `/api/x402/demo` and receives `402 Payment Required` plus x402 payment metadata.
+2. Human readers and crawlers can also see `X-X402-Supported: true` on `/`.
+3. Sitemap or `Link` metadata can point to `/api/x402/demo`, but the clean 402 route is the source of truth.
+4. The agent calls AgentPay MCP `x402_pay` with the protected URL.
+5. AgentPay MCP checks policy before signing: daily cap, task cap, recipient allowlist, approval mode, and kill switch.
+6. Only after approval does AgentPay MCP sign and retry the request.
+7. The transaction history records URL, amount, chain, token, approval status, and settlement reference.
+
+## Curl verification checklist
+
+Run these commands against the demo or deployment:
+
+```bash
+$ curl -si https://agentpay.example.com/ | grep -i '^x-x402-supported:'
+X-X402-Supported: true
+
+$ curl -s https://agentpay.example.com/sitemap.xml | grep '/api/x402/demo'
+  <url><loc>https://agentpay.example.com/api/x402/demo</loc></url>
+
+$ curl -si https://agentpay.example.com/api/x402/demo | head -n 8
+HTTP/2 402
+content-type: application/json
+x-x402-supported: true
+payment-required: true
+```
+
+A scanner pass means discovery works. A production pass means discovery plus AgentPay MCP policy gates both work.
+
+## Acceptance criteria
+
+- `/api/x402/demo` returns HTTP 402 before payment.
+- The 402 response includes `PAYMENT-REQUIRED` and x402 payment metadata.
+- Home or docs route returns `X-X402-Supported: true`.
+- Sitemap, docs, or `Link` metadata points to `/api/x402/demo`, but verification does not depend on metadata alone.
+- `x402_pay` cannot sign until AgentPay MCP policy approves the request.
+- Audit output includes resource URL, amount, chain, approval decision, and settlement reference.

package/docs/x402-tvm-readiness.md

@@ -0,0 +1,53 @@
+# x402 TVM exact-payment readiness
+
+x402 Foundation PR #1944 is adding Python exact-payment support for TVM and TON-style flows. AgentPay MCP treats that as a watch signal, not as production support.
+
+AgentPay MCP currently signs x402 exact payments only on the configured Base network. If a paid endpoint returns a TVM requirement such as `network: "tvm:-3"`, AgentPay MCP fails closed. It does not coerce the payment to Base, it does not attempt a best-effort jetton transfer, and it returns guidance that TVM support must be added deliberately before signing.
+
+## Support matrix
+
+| Rail | AgentPay MCP status | Current behavior |
+|------|---------------------|------------------|
+| Base EVM exact payment | Supported | `x402_pay` signs only the configured Base network, applies per-call caps, and records payment details. |
+| Base Sepolia exact payment | Supported for test flows | Same signing path as Base mainnet when `CHAIN_ID=84532`. |
+| Other EVM x402 networks | Watch state | The SDK baseline can see more chains, but AgentPay MCP restricts signing to the configured Base network until each chain has explicit wallet, asset, and audit support. |
+| Solana x402 | Watch state | No AgentPay signing path is enabled. Requests must fail closed until a Solana wallet, token, receipt, and spend-policy path exists. |
+| x402 batch settlement | Documentation and audit recipe | Batch deposit, voucher, refund, claim, recovery, and multi-SDK parity requirements are documented in `x402-batch-settlement-channels.md` and `x402-multi-sdk-batch-settlement-parity.md`. |
+| TVM/TON exact payment | Watch state | Unsupported TVM requirements fail closed with guidance. No TVM signing, account deployment, faucet, gas, jetton, or facilitator settlement path is enabled. |
+
+## Fail-closed invariant
+
+AgentPay MCP must never silently treat an unsupported x402 network as compatible.
+
+Required behavior:
+
+1. Restrict `createX402Client` to the configured AgentPay network instead of accepting the SDK default network list.
+2. Return an error when a `402 Payment Required` response has only unsupported payment options.
+3. Include the offered network list and the supported AgentPay network list in the error.
+4. For TVM/TON offers, say that TVM is watch-only until signing, account deployment, gas, jettons, settlement, and audit rows are implemented.
+5. Do not call wallet signing or token transfer code for unsupported networks.
+
+## Current implementation proof
+
+The `x402_pay` tool now passes `supportedNetworks` to the x402 client based on `CHAIN_ID`:
+
+- `CHAIN_ID=8453` allows only `base:8453`.
+- `CHAIN_ID=84532` allows only `base-sepolia:84532`.
+- `CHAIN_ID=tvm:-3` is rejected during config load with TVM-specific fail-closed guidance.
+
+If a server returns HTTP 402 with only `tvm:-3`, the tool returns `Unsupported x402 Payment Requirement - Failed Closed` and includes the offered network.
+
+## What must ship before TVM support turns on
+
+TVM support should not be enabled by adding a string to a network list. It needs a complete payment path:
+
+- TVM signer support with local key handling.
+- Account deployment and funding checks.
+- Gas and faucet handling for test networks.
+- Jetton asset mapping and decimals.
+- Facilitator verification and settlement-cache handling.
+- Spend-policy checks before signing.
+- Audit rows that record network, asset, amount, payee, facilitator, settlement result, and receipt.
+- Tests for accept, decline, cap exceeded, bad asset, bad payee, settlement failure, and retry behavior.
+
+Until those exist, TVM exact-payment requests stay blocked by design.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "agentpay-mcp",
-  "version": "4.1.0",
+  "version": "4.1.4",
   "mcpName": "io.github.up2itnow0822/agentpay",
-  "description": "AgentPay MCP Server \u2014 Non-custodial x402 payment layer for AI agents. Multi-chain wallets, spending limits, and machine-to-machine payments. Patent Pending.",
+  "description": "AgentPay MCP Server - Non-custodial x402 payment layer for AI agents. Multi-chain wallets, spending limits, and machine-to-machine payments. Patent Pending.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
@@ -12,7 +12,8 @@
     "dist",
     "README.md",
     "claude_desktop_config.json",
-    ".env.example"
+    ".env.example",
+    "docs/*.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -54,11 +55,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
     "agentwallet-sdk": "^6.1.0",
-    "viem": "2.46.0",
+    "viem": "^2.47.12",
     "zod": "^3.22.4"
   },
   "overrides": {
-    "viem": "2.46.0"
+    "viem": "^2.47.12"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",