agentpay-mcp 4.1.0 → 4.1.4

package/docs/x402-batch-settlement-channels.md

@@ -0,0 +1,199 @@
+# x402 batch-settlement channel compatibility for AgentPay MCP
+
+x402 Foundation PR #2061 moves the TypeScript SDK toward batch-settlement channels for repeat paid calls. Instead of one paid request mapping to one immediate facilitator settle call, the client deposits once, signs cumulative vouchers off-chain, and lets the server claim or refund later.
+
+That is good for low-latency paid MCP tools. It also changes the control surface. AgentPay MCP integrations must audit channel state, voucher caps, storage atomicity, corrective 402 recovery, and delayed settlement evidence before relying on batch-settlement for production tool calls.
+
+## Compatibility goal
+
+AgentPay MCP should treat batch-settlement as a channel lifecycle, not a single payment event.
+
+A production integration is compatible only when it records and enforces these checkpoints:
+
+1. Deposit created or topped up before the first paid call in the channel.
+2. Voucher signed for each paid request with a cumulative maximum claimable amount.
+3. Server verify path checks the voucher without settling every request.
+4. Refund path closes unused channel balance with outstanding vouchers accounted for.
+5. Claim path proves which cumulative voucher amount was claimed before final settle.
+6. Storage uses an atomic compare-and-set or transaction boundary per `channelId`.
+7. Corrective 402 recovery resyncs the client when cumulative state diverges.
+8. Audit logs preserve off-chain voucher state and eventual on-chain settlement proof.
+
+## Channel state AgentPay must persist
+
+Batch-settlement adds durable per-channel state on both sides of the request.
+
+AgentPay MCP should store a sanitized record keyed by `channelId`, `payer`, `receiver`, `token`, and `network`:
+
+```json
+{
+  "event_type": "x402_batch_channel_state",
+  "agent_id": "agent_123",
+  "task_id": "task_456",
+  "mcp_tool": "agentpay.x402_pay",
+  "channel_id": "0xchannel",
+  "network": "eip155:84532",
+  "token": "USDC",
+  "payer_hash": "sha256:...",
+  "payer_authorizer_hash": "sha256:...",
+  "receiver_hash": "sha256:...",
+  "receiver_authorizer_hash": "sha256:...",
+  "deposit_amount": "500000",
+  "charged_cumulative_amount": "200000",
+  "signed_max_claimable": "250000",
+  "total_claimed": "0",
+  "refund_nonce": "0",
+  "storage_version": "42",
+  "policy_version": "agentpay-policy-2026-04-30",
+  "created_at": "2026-04-30T13:20:00Z"
+}
+```
+
+Public logs should hash payer, receiver, payer authorizer, and receiver authorizer addresses. Internal reconciliation can retain raw addresses in encrypted storage.
+
+## Deposit gate
+
+A deposit is not a policy approval. It is a funding action that creates channel capacity.
+
+Before any deposit or top-up, AgentPay MCP should check:
+
+- the deposit amount is under the agent's per-channel deposit cap,
+- the token and network are allowlisted,
+- the receiver and server-owned `receiverAuthorizer` are expected for the paid MCP provider,
+- the deposit multiplier or custom deposit strategy cannot exceed the daily budget,
+- human approval is present when policy requires it.
+
+The policy row should say whether the deposit was approved, declined, or skipped. Never infer approval from the x402 SDK choosing a default deposit amount.
+
+## Voucher cap checks
+
+Batch-settlement vouchers are cumulative. The important value is not only the current request price. It is the new `signedMaxClaimable` amount compared with policy.
+
+Before signing a voucher, AgentPay MCP should compute:
+
+```ts
+const nextSignedMaxClaimable = currentSignedMaxClaimable + requestCharge;
+
+if (nextSignedMaxClaimable > policy.perChannelVoucherCap) {
+  throw new Error("voucher cap exceeded");
+}
+
+if (nextSignedMaxClaimable > approvedChannelBudget) {
+  throw new Error("approved channel budget exceeded");
+}
+```
+
+Required checks:
+
+- per-request price is under `maxAmountRequired`,
+- cumulative voucher amount is under the channel voucher cap,
+- cumulative voucher amount is under the human-approved channel budget,
+- channel balance covers the voucher or a policy-approved top-up is required,
+- voucher signer delegation is recorded when `payerAuthorizer` differs from the payer.
+
+If any check fails, signing must fail closed. A skipped facilitator settle call must never skip AgentPay policy.
+
+## Atomic storage requirement
+
+A batch channel can receive overlapping paid calls. Application-level `get` then `set` is not enough because two requests can sign from the same base cumulative amount.
+
+AgentPay MCP should require compare-and-set semantics per channel:
+
+```ts
+await storage.updateChannel(channelId, current => {
+  if (!current) return createInitialChannel();
+  if (current.storageVersion !== expectedVersion) return current;
+
+  return {
+    ...current,
+    chargedCumulativeAmount: nextChargedCumulativeAmount,
+    signedMaxClaimable: nextSignedMaxClaimable,
+    storageVersion: current.storageVersion + 1,
+    lastRequestTimestamp: Date.now()
+  };
+});
+```
+
+Acceptable production backends:
+
+- Redis or Valkey with Lua or `WATCH` / `MULTI` / `EXEC`,
+- SQL transaction with `SELECT ... FOR UPDATE` or optimistic version checks,
+- Cloudflare Durable Objects when a single object owns one channel,
+- any backend that gives atomic conditional mutation for all app instances sharing the channel.
+
+In-memory storage is acceptable only for a single-process demo.
+
+## Corrective 402 recovery
+
+PR #2061 adds corrective 402 recovery for cumulative mismatches. AgentPay MCP should log recovery as a first-class payment event because it means client and server channel state diverged.
+
+Recovery handling should verify and record:
+
+- corrective error code, such as `batch_settlement_cumulative_amount_mismatch`,
+- server-provided `chargedCumulativeAmount`,
+- server-provided `signedMaxClaimable`,
+- voucher signature used to prove the server snapshot,
+- whether recovery came from server signature or on-chain state,
+- local storage version before and after resync,
+- whether the original request was retried.
+
+If recovery cannot verify the signature, channel config, or on-chain state, AgentPay MCP should mark the channel `recovery_failed` and block more voucher signing until a human or operator reconciles it.
+
+## Refund and claim audit path
+
+Refund and claim are delayed settlement operations. They need different audit rows from a normal one-shot x402 payment.
+
+For refunds, record:
+
+- requested refund amount or full refund flag,
+- outstanding signed max claimable amount,
+- server claim action before refund if any,
+- refund transaction hash or pending status,
+- remaining channel balance after refund.
+
+For claims, record:
+
+- claimed channel IDs,
+- claimed cumulative amount per channel,
+- claim transaction hash,
+- settle transaction hash if funds are swept separately,
+- receiver and receiver authorizer hashes,
+- failed, partial, or retried claims.
+
+A paid MCP provider should be able to answer: which tool call increased the voucher, which cumulative voucher got claimed, and which on-chain transaction settled it.
+
+## Server-owned receiver authorizer
+
+The batch-settlement scheme includes `receiverAuthorizer` in channel config. For AgentPay MCP, this is part of provider identity.
+
+AgentPay MCP should pin or allowlist expected receiver authorizers per paid MCP provider. If the receiver authorizer changes, the integration should require one of these outcomes:
+
+- a signed provider rotation notice,
+- a fresh human approval,
+- or fail-closed rejection.
+
+Do not treat a matching receiver address as enough. The receiver authorizer can become the operational key that approves server-side settlement behavior.
+
+## Off-chain settlement audit checklist
+
+Before enabling batch-settlement for a paid MCP tool, require:
+
+- `channel_id` in every payment attempt row,
+- `deposit_amount`, `charged_cumulative_amount`, and `signed_max_claimable` in channel rows,
+- policy approval ID attached to deposit and voucher signing,
+- CAS or transaction proof for channel storage mutations,
+- corrective 402 recovery rows,
+- refund and claim rows with transaction hashes when available,
+- hashed payer, receiver, payer authorizer, and receiver authorizer fields,
+- failure rows for skipped deposits, voucher cap rejection, recovery failure, refund failure, and claim failure.
+
+## Acceptance checklist
+
+- [ ] Deposit policy enforces per-channel and daily caps before channel funding.
+- [ ] Voucher signing checks cumulative voucher caps, not only per-request price.
+- [ ] Server-owned `receiverAuthorizer` is pinned or routed through approval.
+- [ ] Channel storage uses atomic compare-and-set or transaction semantics.
+- [ ] Corrective 402 recovery is logged and fails closed when verification fails.
+- [ ] Refund flows account for outstanding signed vouchers before returning balance.
+- [ ] Claim flows log cumulative claimed amount and settlement transaction proof.
+- [ ] Audit rows connect MCP tool name, policy version, channel ID, voucher state, and on-chain settlement.

package/docs/x402-bazaar-observability.md

@@ -0,0 +1,209 @@
+# x402 Bazaar observability for paid MCP tools
+
+x402 Bazaar is moving from passive discovery metadata to searchable catalog behavior. AgentPay MCP should treat that as a production contract: paid MCP tools need searchable metadata, shared facilitator auth, and visible extension outcomes after verify and settle.
+
+This recipe tracks the x402 Foundation Apr 29 signal: WithBazaar SDK wrappers now support search, unified auth, and Python parity, and PR #2161 adds EXTENSION-RESPONSES header readback for verify and settle.
+
+## Production goal
+
+A paid MCP tool is Bazaar-ready only when all four checks pass:
+
+1. The 402 response carries a `bazaar` extension with MCP search metadata.
+2. The facilitator client can list and search Bazaar resources with the same auth provider used for `verify`, `settle`, and `supported`.
+3. The client reads `EXTENSION-RESPONSES` from verify and settle responses.
+4. AgentPay MCP writes sanitized audit rows for catalog status, policy approval, and settlement.
+
+If any check fails, AgentPay MCP should still fail closed for payment signing. Discovery failure must not become silent spend authority.
+
+## Bazaar metadata for MCP tools
+
+For each paid MCP tool, the 402 response should include a `bazaar` extension under `extensions`.
+
+```json
+{
+  "extensions": {
+    "bazaar": {
+      "info": {
+        "input": {
+          "type": "mcp",
+          "tool": "agentpay.x402_pay",
+          "description": "Pay an x402-protected API after AgentPay MCP policy approval",
+          "transport": "streamable-http",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "resource": { "type": "string" },
+              "maxAmountRequired": { "type": "string" },
+              "network": { "type": "string" },
+              "payTo": { "type": "string" }
+            },
+            "required": ["resource", "maxAmountRequired", "network", "payTo"]
+          },
+          "example": {
+            "resource": "https://api.example.com/research/report",
+            "maxAmountRequired": "100000",
+            "network": "eip155:8453",
+            "payTo": "0x0000000000000000000000000000000000000000"
+          }
+        },
+        "output": {
+          "type": "json",
+          "example": {
+            "approved": true,
+            "transaction": "0x...",
+            "policy_version": "agentpay-policy-2026-04-30"
+          }
+        }
+      },
+      "schema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "required": ["input"],
+        "properties": {
+          "input": {
+            "type": "object",
+            "required": ["type", "tool", "inputSchema"],
+            "properties": {
+              "type": { "const": "mcp" },
+              "tool": { "type": "string" },
+              "description": { "type": "string" },
+              "transport": { "enum": ["streamable-http", "sse"] },
+              "inputSchema": { "type": "object" },
+              "example": { "type": "object" }
+            },
+            "additionalProperties": false
+          },
+          "output": { "type": "object" }
+        }
+      }
+    }
+  }
+}
+```
+
+Required AgentPay fields:
+
+- `input.type`: `mcp`
+- `input.tool`: MCP tool name passed to `tools/call`
+- `input.description`: one sentence with the paid action and policy boundary
+- `input.transport`: `streamable-http` by default, `sse` only when the server uses SSE
+- `input.inputSchema`: the same schema the MCP tool advertises
+- `input.example`: a safe example that does not include a real private key, API token, wallet secret, or customer identifier
+- `output.example.policy_version`: the policy revision attached to the approval decision
+
+For MCP resources, the catalog key is the tuple `resource.url` plus `input.tool`. Do not assume one MCP endpoint maps to one paid capability.
+
+## Search checks with WithBazaar
+
+AgentPay MCP should be discoverable by a Bazaar search query, not only by a raw list call.
+
+```ts
+import { HTTPFacilitatorClient } from "@x402/core/http";
+import { withBazaar } from "@x402/extensions";
+
+const facilitator = new HTTPFacilitatorClient({
+  url: process.env.X402_FACILITATOR_URL,
+  createAuthHeaders: async () => ({
+    verify: { Authorization: `Bearer ${process.env.X402_FACILITATOR_TOKEN}` },
+    settle: { Authorization: `Bearer ${process.env.X402_FACILITATOR_TOKEN}` },
+    supported: { Authorization: `Bearer ${process.env.X402_FACILITATOR_TOKEN}` },
+    bazaar: { Authorization: `Bearer ${process.env.X402_FACILITATOR_TOKEN}` }
+  })
+});
+
+const client = withBazaar(facilitator);
+
+const matches = await client.extensions.bazaar.search({
+  query: "approval gated x402 MCP payment tool",
+  type: "mcp",
+  network: "eip155:8453",
+  scheme: "exact",
+  extensions: "bazaar",
+  limit: 10
+});
+```
+
+The `bazaar` auth header must use the same auth source as `verify`, `settle`, and `supported`. Divergent auth is a bad production signal because the agent may be able to pay but not prove catalog status.
+
+## EXTENSION-RESPONSES readback
+
+Facilitators may return an `EXTENSION-RESPONSES` header from `verify` or `settle`. The value is base64-encoded JSON keyed by extension name.
+
+Example decoded value:
+
+```json
+{
+  "bazaar": {
+    "status": "success"
+  }
+}
+```
+
+Rejected example:
+
+```json
+{
+  "bazaar": {
+    "status": "rejected",
+    "rejectedReason": "info failed schema validation"
+  }
+}
+```
+
+AgentPay MCP should parse the header, keep only allowlisted fields, and write the result into the payment audit row. Never log full request bodies, auth headers, private keys, payment signatures, or customer contact data.
+
+Allowlisted fields:
+
+- `status`
+- `rejectedReason`
+- `reason`
+- `code`
+
+## Audit row shape
+
+Paid MCP tool audit rows should include enough state to debug Bazaar cataloging without leaking secrets.
+
+```json
+{
+  "event_type": "x402_paid_mcp_tool_settled",
+  "agent_id": "agent_123",
+  "task_id": "task_456",
+  "mcp_tool": "agentpay.x402_pay",
+  "resource": "https://api.example.com/research/report",
+  "network": "eip155:8453",
+  "asset": "USDC",
+  "max_amount_required": "100000",
+  "pay_to_hash": "sha256:...",
+  "policy_version": "agentpay-policy-2026-04-30",
+  "approval_id": "approval_789",
+  "verify_extension_responses": {
+    "bazaar": { "status": "processing" }
+  },
+  "settle_extension_responses": {
+    "bazaar": { "status": "success" }
+  },
+  "settlement_tx": "0x...",
+  "created_at": "2026-04-30T05:14:00Z"
+}
+```
+
+`pay_to_hash` is preferred for public logs. Internal systems can keep the raw address in encrypted storage when reconciliation needs it.
+
+## Failure handling
+
+- Missing Bazaar search result: payment can proceed only if the normal AgentPay policy approves it, but write `bazaar_catalog_status: missing`.
+- Missing `EXTENSION-RESPONSES`: write `extension_response_status: absent`, not `success`.
+- Malformed `EXTENSION-RESPONSES`: ignore the raw header, write `extension_response_status: malformed`, and keep the payment state separate.
+- `bazaar.status: rejected`: surface the rejection reason to the operator and flag the MCP metadata for repair.
+- Auth failure on Bazaar search: do not downgrade verify or settle auth. Fix the `bazaar` auth header path.
+
+## Acceptance checklist
+
+- [ ] 402 response includes `extensions.bazaar.info.input.type = "mcp"`.
+- [ ] `input.tool` matches the MCP `tools/call` name.
+- [ ] `input.inputSchema` matches the MCP tool schema.
+- [ ] `withBazaar(...).search({ type: "mcp", extensions: "bazaar" })` returns the paid tool or a clear miss.
+- [ ] `createAuthHeaders` includes `verify`, `settle`, `supported`, and `bazaar` entries.
+- [ ] Verify and settle read `EXTENSION-RESPONSES` when present.
+- [ ] Logs keep only `status`, `rejectedReason`, `reason`, and `code` from extension response payloads.
+- [ ] Payment signing remains gated by AgentPay policy approval even when Bazaar metadata is valid.

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.