agentpay-mcp 4.1.1 → 4.1.4

package/docs/vercel-deployment-hardening.md

@@ -0,0 +1,115 @@
+# Vercel deployment hardening for AgentPay MCP
+
+Vercel's April 2026 security bulletin changed the threat model for agent teams. The incident started through a compromised third-party AI tool OAuth grant, then moved into Google Workspace and Vercel systems. Vercel reported that a limited set of non-sensitive environment variables were enumerated and decrypted, and it told affected customers to rotate readable env vars, review activity and deployments, and move secrets into sensitive environment variables.
+
+AgentPay MCP should be deployed as if the host can leak readable configuration. Keep payment authority isolated, make every paid tool fail closed, and treat OAuth app grants as production access.
+
+## 10-minute incident response checklist
+
+Use this first if you deployed AgentPay MCP or any x402-capable agent on Vercel before April 24, 2026.
+
+1. Rotate every readable Vercel environment variable that can reach money, data, or infrastructure. Include `AGENT_PRIVATE_KEY`, `AGENT_WALLET_ADDRESS`, `RPC_URL`, model provider keys, database URLs, OAuth client secrets, webhook secrets, and any internal API tokens.
+2. Move secrets into Vercel sensitive environment variables. Anything that signs, pays, authenticates, deploys, or reads private data should not be readable from the dashboard or API after creation.
+3. Audit Google Workspace OAuth grants for AI tools. Remove any app you don't recognize or can't tie to an owner. Vercel published the OAuth app ID `110671459871-30f1spbu0hptbs60cb4vsmv79i7bbvqj.apps.googleusercontent.com` as an indicator of compromise.
+4. Review Vercel activity logs for environment variable reads, token changes, project setting changes, team membership changes, and unusual API access.
+5. Review recent deployments. Delete deployments you didn't initiate, don't recognize, or can't explain from a linked commit and CI run.
+6. Rotate Deployment Protection bypass tokens if they exist. Treat them like exposed credentials.
+7. Verify Deployment Protection is at least Standard for every production project.
+8. Re-deploy from a known clean commit after rotation. Don't trust a deployment that was built with stale credentials.
+9. Re-run AgentPay MCP approval validation before reconnecting agents to paid tools.
+10. Keep the old credentials disabled. Don't keep them as fallback values in preview or development projects.
+
+## Vercel environment variable policy
+
+Classify AgentPay MCP configuration by blast radius:
+
+| Variable | Classification | Vercel setting | Rotation trigger |
+| --- | --- | --- | --- |
+| `AGENT_PRIVATE_KEY` | x402 signing key | Sensitive env var only | Any host, OAuth, CI, or dashboard compromise |
+| `AGENT_WALLET_ADDRESS` | Public identifier | Readable allowed | Wallet migration or key rotation |
+| `RPC_URL` with provider key | Paid infrastructure credential | Sensitive env var only | Any provider, Vercel, or CI exposure |
+| `AGENTPAY_MCP_TOKEN` | MCP transport auth | Sensitive env var only | Any agent, app, or host compromise |
+| Model provider API keys | Paid tool and data access | Sensitive env var only | Any env var read or OAuth compromise |
+| Database URLs | Production data access | Sensitive env var only | Any env var read, deployment anomaly, or DB alert |
+
+Rules:
+
+- Don't store owner keys in Vercel. AgentPay MCP should use an agent hot wallet with on-chain spend limits, not the owner's treasury key.
+- Don't put signing keys in client-side env vars. In Vercel, avoid any `NEXT_PUBLIC_` prefix for payment, API, OAuth, or database secrets.
+- Don't copy production secrets into preview projects unless the preview deployment is protected and tied to the same incident response process.
+- Use separate keys for development, preview, and production. A preview leak shouldn't become a production payment incident.
+
+## x402 signing key isolation
+
+AgentPay MCP is safest when the Vercel app does not hold unrestricted signing authority.
+
+Recommended pattern:
+
+1. Deploy AgentPay MCP as a separate service behind HTTPS with an auth token or mTLS-equivalent gateway.
+2. Give the Vercel AI app only an `AGENTPAY_MCP_TOKEN` and MCP endpoint URL.
+3. Keep `AGENT_PRIVATE_KEY` in the AgentPay MCP service, a KMS, or an HSM-backed signer. If it must run on Vercel, mark it as a sensitive environment variable and bind it to the smallest possible project scope.
+4. Use an agent hot wallet with on-chain spend caps, recipient allowlists, and daily limits.
+5. Keep owner or treasury keys outside the Vercel runtime entirely.
+6. Log every signing attempt with `agent_id`, `task_id`, `tool_call_id`, amount, recipient, policy version, approval ID, and x402 receipt ID.
+
+The invariant is simple: a leaked model key can burn credits; a leaked signing key can move funds. Treat them differently.
+
+## Fail-closed paid tools with Vercel AI SDK approvals
+
+The Vercel AI SDK approval flow is the correct place to stop paid tools before x402 signing. Use `needsApproval: true` or a dynamic `needsApproval` function for any tool that can spend money, change billing state, or call a paid API.
+
+AgentPay MCP v4.1.3 already documents the native AI SDK approval bridge. Preserve this signing rule in production:
+
+- `tool-approval-response` with `approved: true`: allow policy checks, then signing
+- denied response: block signing
+- missing response: block signing
+- approval engine error: block signing
+- policy engine error: block signing
+- amount, recipient, chain, or payment header mismatch: block signing
+
+Never let a model retry a denied paid tool until a human creates a new approval. Add a system instruction such as: `When a tool execution is not approved, do not retry the same paid call.`
+
+Run the existing approval-validation test before deploy:
+
+```bash
+npm install
+npm test -- tests/payments.test.ts
+```
+
+This test suite covers approval queue behavior and must remain fail-closed: decline, cancel, missing approval, and incomplete approval paths must not reach signing.
+
+## Activity and deployment review
+
+After a Vercel security event, review these records before turning agents back on:
+
+- Vercel account activity log for env var reads, project changes, team changes, token changes, and unusual API access
+- deployment list for unexpected deploys, build sources, commit SHAs, domains, and aliases
+- GitHub repository audit log for OAuth app grants, webhooks, deploy keys, and branch protection edits
+- Google Workspace connected apps and OAuth grants for AI tools
+- npm publish history if the deployment consumes internal packages
+- AgentPay MCP transaction history for unexpected x402 attempts, blocked approvals, and policy denials
+
+If the app paid anything during the exposure window, reconcile the x402 receipt IDs against approval IDs and policy versions. Any payment without an approval record should be treated as an incident until disproven.
+
+## Pre-deploy gate
+
+Do not ship a Vercel-hosted agent with paid tools until all of these pass:
+
+- every secret value is sensitive, scoped by environment, and rotated after any exposure
+- owner keys are absent from Vercel
+- agent signing key is isolated to AgentPay MCP or a dedicated signer
+- Vercel Deployment Protection is enabled for production
+- Google Workspace OAuth grants have an owner and a business reason
+- activity logs and deployment logs were reviewed after the last rotation
+- AI SDK paid tools require approval before execution
+- AgentPay MCP validation proves x402 signing is blocked until approval
+- spend caps, recipient allowlists, daily limits, and kill switches are active
+- audit records join approval ID, tool call ID, policy version, and x402 receipt ID
+
+## References
+
+- Vercel April 2026 security incident bulletin: https://vercel.com/kb/bulletin/vercel-april-2026-security-incident
+- Vercel sensitive environment variables: https://vercel.com/docs/environment-variables/sensitive-environment-variables
+- Vercel activity logs: https://vercel.com/docs/cli/activity
+- Vercel AI SDK tool execution approval: https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling#tool-execution-approval
+- AgentPay MCP approval validation tests: ../tests/payments.test.ts

package/docs/whatsapp-smb-agent-controls.md

@@ -0,0 +1,130 @@
+# WhatsApp and SMB paid-agent controls with AgentPay MCP
+
+WhatsApp agent management changes the buyer question. The problem is no longer only "can this gateway call a paid API?" It is "can a shop owner approve spend from the same channel where the agent works?"
+
+AgentPay MCP should sit between the channel agent and the x402 or USDC endpoint.
+
+## Reference flow
+
+```text
+Customer or operator in WhatsApp
+  -> WhatsApp agent runtime
+  -> paid action requested
+  -> AgentPay MCP policy check
+  -> approval card or decline path
+  -> x402 or USDC payment only after approval
+  -> audit row returned to the operator
+```
+
+## Control points
+
+1. The WhatsApp agent asks to call a paid API, book a service, buy data, or trigger a USDC payment.
+2. AgentPay MCP computes the spend decision before any wallet signature exists.
+3. If the request needs approval, the channel shows a concise card:
+   - merchant or endpoint,
+   - amount,
+   - token and chain,
+   - reason the agent gave,
+   - daily cap remaining,
+   - approve, deny, or lower cap.
+4. AgentPay MCP signs only after an approved decision.
+5. The operator gets a receipt with transaction hash, URL, amount, policy version, and agent task ID.
+
+## Policy shape
+
+```json
+{
+  "agent_id": "whatsapp-agent-42",
+  "channel": "whatsapp",
+  "daily_cap_usdc": "25.00",
+  "per_call_cap_usdc": "2.00",
+  "approval_required_above_usdc": "0.50",
+  "allowed_recipients": ["api.vendor.example"],
+  "allowed_chains": ["base", "base-sepolia"],
+  "audit_tags": ["smb", "whatsapp", "x402"]
+}
+```
+
+## Example approval card text
+
+```text
+Approve paid agent action?
+
+Agent: Inventory assistant
+Endpoint: api.supplier.example/restock-check
+Cost: 0.18 USDC on Base
+Daily cap left: 14.72 USDC
+Reason: Check supplier stock before replying to customer
+
+[Approve once] [Deny] [Lower cap]
+```
+
+## Failure behavior
+
+- If the user denies, return a normal agent message and do not sign.
+- If the cap is exceeded, fail closed and ask for a cap update.
+- If the payment metadata is missing or malformed, do not guess.
+- If the chain is unknown, route to the chain-drift watchlist before enabling payment.
+- If the WhatsApp session expires, require a fresh approval.
+
+## Audit row
+
+```json
+{
+  "timestamp": "2026-04-28T05:20:00Z",
+  "agent_id": "whatsapp-agent-42",
+  "task_id": "restock-check-1902",
+  "channel": "whatsapp",
+  "resource": "https://api.supplier.example/restock-check",
+  "amount_usdc": "0.18",
+  "chain": "base",
+  "approval_decision": "approved_once",
+  "policy_version": "2026-04-28.whatsapp-smb.v1",
+  "settlement_reference": "0x..."
+}
+```
+
+## Acceptance criteria
+
+- No channel agent can produce a wallet signature before AgentPay MCP returns an approved decision.
+- Operators can set daily and per-call caps per WhatsApp agent.
+- Every paid call joins channel context, payment metadata, policy version, and settlement reference.
+- Deny, cancel, expired session, cap exceeded, and unknown chain paths all fail closed.
+
+## Persona creation approval gate
+
+Axon-style vertical personas make the first spend decision happen before the first paid API call. When a shop owner creates an inventory assistant, booking assistant, legal intake assistant, or support persona, AgentPay MCP should attach payment authority at creation time instead of waiting for the first x402 challenge.
+
+Recommended creation flow:
+
+1. Operator creates or edits a persona in the channel agent dashboard.
+2. The dashboard asks AgentPay MCP for a spend profile before enabling paid tools.
+3. AgentPay MCP returns default caps, chain allowlist, recipient allowlist, and approval threshold.
+4. The operator approves the persona's payment authority in WhatsApp or the admin UI.
+5. The runtime stores the persona ID, policy version, cap, approver, and allowed tool set.
+6. Every later x402 or USDC call must reference the persona policy before signing.
+
+Minimal policy attachment:
+
+```json
+{
+  "persona_id": "inventory-assistant-ptbr",
+  "persona_vertical": "retail_inventory",
+  "created_by": "operator:shop-owner-17",
+  "approval_surface": "whatsapp",
+  "policy_version": "2026-04-29.persona-controls.v1",
+  "daily_cap_usdc": "10.00",
+  "per_call_cap_usdc": "0.25",
+  "approval_required_above_usdc": "0.05",
+  "allowed_tools": ["supplier_stock_lookup", "delivery_quote"],
+  "allowed_recipients": ["api.supplier.example", "api.delivery.example"],
+  "allowed_chains": ["base", "base-sepolia"]
+}
+```
+
+Acceptance additions:
+
+- Persona creation cannot enable paid tools without an attached AgentPay MCP policy.
+- Persona edits that raise spend caps, add recipients, add chains, or add paid tools require fresh approval.
+- WhatsApp receipts include both `agent_id` and `persona_id` so the owner can see which persona spent money.
+- Revoking a persona immediately disables its payment authority, even if the agent runtime still has an active session.

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.