agentpay-mcp 4.1.1 → 4.1.4

package/docs/x402-chain-drift-compatibility.md

@@ -0,0 +1,63 @@
+# x402 chain-drift compatibility note and test plan
+
+x402 paywall templates are moving faster than static client examples. The risk is simple: a paid-agent demo assumes yesterday's chain list, then a PaymentWrapper or paywall update emits payment metadata for a chain the client does not recognize.
+
+AgentPay MCP must not silently coerce unknown x402 chains to Base. The package now depends on `viem` `^2.47.12`, matching or exceeding the x402 Foundation paywall-template baseline that added Mezo, MegaETH, Stable, and Radius chain definitions.
+
+## Current boundary
+
+AgentPay MCP `4.1.4` supports Base Mainnet and Base Sepolia for the core configured wallet client. Other tools in the repo support broader token, bridge, and swap surfaces, but x402 payment execution should treat unsupported chains as a fail-closed condition until the chain is explicitly mapped, tested, and funded.
+
+This is safer than guessing. A failed payment is recoverable. A wrong-chain signature is not.
+
+## Chains to watch
+
+Track x402 Foundation paywall and PaymentWrapper changes for these chain definitions:
+
+- Mezo
+- MegaETH
+- Stable
+- Radius
+- Any new `viem/chains` entry that appears in x402 paywall templates before AgentPay MCP docs or tests mention it
+
+## Compatibility requirements
+
+- Parse the chain or network value from x402 payment metadata without assuming Base.
+- Match known networks to explicit AgentPay MCP chain configuration.
+- Reject unknown networks with a clear error that names the unsupported chain.
+- Never fall back to `8453` when the server requested a different chain.
+- Keep docs, tests, and package examples aligned with the current x402 Foundation template set.
+
+## Test coverage
+
+`tests/chain-drift.test.ts` is the current smoke gate. It verifies that the installed `viem/chains` baseline exposes Mezo, MegaETH, Stable, and Radius, then verifies that AgentPay MCP still rejects those chain IDs instead of routing them through Base.
+
+Future fixture-driven tests for x402 payment metadata should use this shape:
+
+```ts
+const paymentRequirements = [
+  { network: "base", chainId: 8453, shouldPay: true },
+  { network: "base-sepolia", chainId: 84532, shouldPay: true },
+  { network: "mezo", shouldPay: false },
+  { network: "megaeth", shouldPay: false },
+  { network: "stable", shouldPay: false },
+  { network: "radius", shouldPay: false },
+];
+```
+
+Expected results:
+
+- `base` and `base-sepolia` route only when the configured wallet, token registry, RPC URL, and policy allow them.
+- Mezo, MegaETH, Stable, and Radius return `Unsupported x402 network` until explicit support lands.
+- The error includes the requested network and the configured network.
+- Tests assert that the signing function is not called for unsupported networks.
+
+## Release gate
+
+Before any future AgentPay MCP release claiming new x402 chain support:
+
+1. Update the chain map and explorer map.
+2. Add payment metadata fixtures from the current x402 Foundation paywall templates.
+3. Run unit tests for accept, deny, cancel, cap exceeded, and unknown chain paths.
+4. Run `npm run typecheck`, `npm test`, `npm run build`, and `npm pack --dry-run`.
+5. Update this document with the supported network set and validation date.

package/docs/x402-mcp-funding-ux-benchmark.md

@@ -0,0 +1,36 @@
+# x402 MCP funding UX benchmark
+
+A new public repo, `yayashuxue/agent-marketplace-mcp`, is testing an x402-paid MCP server with hosted funding UX, local hot-wallet generation, optional Coinbase-managed mode, and Smithery hosting metadata. As of 2026-05-01 04:48 CT, `npm view agent-marketplace-mcp` returned 404, so this benchmark treats it as a public repo signal, not as a live npm package.
+
+The signal matters because paid MCP builders are moving funding into the product pitch. AgentPay MCP should make the tradeoff clear: fast top-up is useful, but production agents need approval gates, daily caps, auditability, and a non-custodial posture before they can spend real budgets.
+
+## Comparison
+
+| Area | AgentPay MCP | agent-marketplace-mcp signal |
+|------|--------------|------------------------------|
+| Funding model | Bring a funded non-custodial Agent Wallet. Funding can happen through any wallet workflow the operator approves. | Public README describes a hosted fund link and optional managed wallet mode. |
+| Approval gates | Payment tools are designed to sit behind human approval, policy checks, and per-call caps before signing. | The repo emphasizes easier funding. Approval gating is not the main product claim in the observed public metadata. |
+| Daily caps | AgentPay MCP exposes spend limits and budget checks as first-class controls before paid tool use. | Funding UX may reduce onboarding friction, but a funded wallet still needs enforceable spend caps. |
+| Auditability | AgentPay MCP records payment amount, recipient, network, transaction hash, and history through wallet activity tools. | Hosted top-up can help users fund faster, but operators still need agent-level audit rows for every paid call. |
+| Custody posture | Non-custodial by default. The agent signs with its configured wallet key and policy layer. | Optional Coinbase-managed mode may be easier for onboarding, but it changes custody and operational risk assumptions. |
+| Failure mode | Unsupported chains and unsupported x402 requirements fail closed. | Hosted funding does not remove the need to reject unsupported networks, assets, payees, and settlement paths. |
+
+## Safe funding UX for AgentPay MCP
+
+AgentPay MCP should keep funding easy without weakening spend controls:
+
+1. Show wallet funding status before a paid tool call.
+2. Link to operator-approved funding instructions, not an automatic top-up that bypasses review.
+3. Require an approval gate before the first payment to a new service or payee.
+4. Enforce per-call and daily caps before signing.
+5. Log each payment with service, URL, amount, asset, recipient, network, transaction hash, and policy version.
+6. Fail closed for unsupported networks, including TVM/TON exact-payment offers.
+7. Keep managed-wallet mode as an explicit integration choice, not a silent default.
+
+## Buyer guidance
+
+Pick hosted funding when the goal is a fast demo and the budget is small.
+
+Pick AgentPay MCP when a production agent needs to prove who approved the spend, how much it can spend per call, what daily ceiling applies, which wallet signed, and where the receipt lives.
+
+Funding UX gets the wallet ready. Spend governance decides whether the agent is allowed to use it.

package/docs/x402-multi-sdk-batch-settlement-parity.md

@@ -0,0 +1,167 @@
+# x402 multi-SDK batch-settlement parity for AgentPay MCP
+
+x402 Foundation PR #2164 extends the batch-settlement work from the TypeScript branch into Go client, server, facilitator, and e2e paths. That changes the AgentPay MCP compatibility bar. Paid MCP providers should not prove batch-settlement safety with one SDK only.
+
+The minimum proof now needs TypeScript and Go clients to produce the same channel-state evidence for deposits, vouchers, recovery, refunds, claims, and final settlement.
+
+## Compatibility target
+
+AgentPay MCP should treat multi-SDK batch settlement as one shared channel lifecycle with SDK-specific implementations.
+
+A provider is compatible only when a TypeScript client and a Go client can both show:
+
+- the same `channelId` derivation inputs for payer, `payerAuthorizer`, receiver, `receiverAuthorizer`, token, network, withdraw delay, and salt,
+- the same policy approval gate before deposit or top-up,
+- the same cumulative voucher cap checks before every voucher signature,
+- the same recovery behavior after a corrective 402,
+- the same refund and claim audit rows,
+- the same proof bundle shape for paid MCP operators.
+
+If one SDK emits less state than another, use the stricter shape. Do not let a Go integration skip an audit row that the TypeScript path already records, or vice versa.
+
+## Cross-SDK channel identity
+
+PR #2164 adds Go batch-settlement examples and e2e wiring around `CHANNEL_SALT`. AgentPay MCP should use the salt as part of the channel identity record, not as a test-only detail.
+
+Store this channel identity before signing any voucher:
+
+```json
+{
+  "event_type": "x402_batch_sdk_parity_channel",
+  "sdk": "go",
+  "sdk_version": "pr-2164-head",
+  "channel_id": "0xchannel",
+  "network": "eip155:84532",
+  "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+  "payer_hash": "sha256:...",
+  "payer_authorizer_hash": "sha256:...",
+  "receiver_hash": "sha256:...",
+  "receiver_authorizer_hash": "sha256:...",
+  "withdraw_delay_seconds": 86400,
+  "channel_salt_hash": "sha256:...",
+  "channel_config_hash": "sha256:...",
+  "policy_version": "agentpay-policy-2026-04-30"
+}
+```
+
+The `channel_config_hash` must be computed from the normalized config fields, not from a raw SDK struct dump. Field order and JSON tags differ across languages.
+
+## Phased e2e proof
+
+PR #2164 adds fixed batch-settlement phases for e2e clients:
+
+- `initial`: deposit plus first voucher,
+- `recovery-refund`: corrective recovery voucher plus cooperative refund,
+- `full`: deposit, voucher, and refund in one flow.
+
+AgentPay MCP test evidence should preserve the same phase names. Each phase needs one proof row per SDK:
+
+```json
+{
+  "event_type": "x402_batch_sdk_parity_phase",
+  "phase": "recovery-refund",
+  "sdk": "go",
+  "mcp_tool": "agentpay.x402_pay",
+  "channel_id": "0xchannel",
+  "deposit_tx": "0x...",
+  "voucher_signature_hash": "sha256:...",
+  "recovery_error_code": "batch_settlement_cumulative_amount_mismatch",
+  "refund_tx": "0x...",
+  "storage_version_before": "42",
+  "storage_version_after": "43",
+  "result": "passed"
+}
+```
+
+A provider can run more phases, but it should not rename these three. Stable phase names make cross-SDK failures searchable in CI and production incident logs.
+
+## Voucher signer separation
+
+The Go client path adds optional `EVM_VOUCHER_SIGNER_PRIVATE_KEY`, matching the TypeScript direction where the payer key and voucher signer can be separated.
+
+AgentPay MCP should record signer separation as a first-class policy fact:
+
+- payer key signs deposits and channel funding authorizations,
+- voucher signer signs repeat-call vouchers as `payerAuthorizer`,
+- receiver authorizer signs claim and refund settlement actions,
+- facilitator wallet submits on-chain settlement transactions.
+
+A dedicated voucher signer is allowed only when policy records the delegated signer address and its scope. It must not inherit all payer permissions by accident.
+
+Fail closed when:
+
+- `payerAuthorizer` changes without a fresh approval,
+- `EVM_VOUCHER_SIGNER_PRIVATE_KEY` appears in a provider runtime where voucher delegation is not expected,
+- a voucher signer can also move funds directly from the payer wallet,
+- the SDK reports a payer authorizer address that does not match the approved delegation.
+
+## Facilitator and receiver authorizer expectations
+
+Go examples add facilitator and server authorizer paths. AgentPay MCP should distinguish three operational roles:
+
+1. Receiver: the payee address used for the channel.
+2. Receiver authorizer: the key that signs claim and refund payloads.
+3. Facilitator signer: the key that submits or sponsors on-chain settlement actions.
+
+For production paid MCP providers, the safest path is a self-managed receiver authorizer controlled by the provider, with facilitator rotation treated as operational infrastructure. Delegating receiver authorization to a facilitator is acceptable for demos, but it should be logged as higher operational risk.
+
+Audit rows must include hashed receiver authorizer and facilitator identity fields. A matching receiver address is not enough proof.
+
+## Refund and recovery visibility
+
+The Go e2e path makes recovery and refund behavior explicit. AgentPay MCP should expose the same visibility in provider logs:
+
+- corrective 402 code,
+- server-reported cumulative charge,
+- client-local cumulative charge before recovery,
+- recovered voucher hash,
+- refund amount requested,
+- outstanding signed max claimable before refund,
+- claim-before-refund decision,
+- refund transaction or pending status.
+
+A refund that hides outstanding voucher state is not production-safe. The operator needs to know whether the server claimed first, refunded the unclaimed remainder, retried, or failed.
+
+## Cross-SDK proof bundle
+
+Before enabling batch-settlement for a paid MCP provider, require a proof bundle with this shape:
+
+```json
+{
+  "provider": "paid-mcp-provider.example",
+  "x402_pr_reference": "https://github.com/x402-foundation/x402/pull/2164",
+  "agentpay_doc_reference": "docs/x402-multi-sdk-batch-settlement-parity.md",
+  "sdk_matrix": [
+    {
+      "sdk": "typescript",
+      "phases": ["initial", "recovery-refund", "full"],
+      "voucher_signer_separation": true,
+      "receiver_authorizer_pinned": true,
+      "cas_storage_proven": true,
+      "refund_recovery_rows_present": true
+    },
+    {
+      "sdk": "go",
+      "phases": ["initial", "recovery-refund", "full"],
+      "voucher_signer_separation": true,
+      "receiver_authorizer_pinned": true,
+      "cas_storage_proven": true,
+      "refund_recovery_rows_present": true
+    }
+  ],
+  "acceptance": "passed"
+}
+```
+
+The proof should link to CI output or a local validation artifact. Screenshots are not enough.
+
+## Acceptance checklist
+
+- [ ] TypeScript and Go runs use the same normalized channel identity fields.
+- [ ] `CHANNEL_SALT` is recorded in hashed form and tied to the `channelId` proof.
+- [ ] `initial`, `recovery-refund`, and `full` phase results are logged per SDK.
+- [ ] `EVM_VOUCHER_SIGNER_PRIVATE_KEY` or equivalent delegation is recorded as `payerAuthorizer` scope, not broad payer authority.
+- [ ] Receiver authorizer and facilitator signer roles are logged separately.
+- [ ] Corrective 402 recovery rows include before and after cumulative state.
+- [ ] Refund rows include outstanding signed max claimable and claim-before-refund behavior.
+- [ ] The provider can hand operators one proof bundle that compares TypeScript and Go results side by side.

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.1",
+  "version": "4.1.4",
   "mcpName": "io.github.up2itnow0822/agentpay",
-  "description": "AgentPay MCP Server — 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",