agentpay-mcp 4.1.7 → 4.1.10

package/docs/hosted-x402-proxy-verification.md

@@ -0,0 +1,79 @@
+# Hosted x402 proxy buyer verification checklist
+
+Hosted paid-MCP gateways are useful. They let an agent hit a no-signup endpoint, receive HTTP 402, pay, and keep moving.
+
+That speed is also the risk. Before an agent signs, the buyer needs proof that the 402 challenge points to the expected recipient, chain, asset, amount, and proxy model.
+
+## Verified market signal
+
+On 2026-05-01, Toolstem moved from a minimal proxy README to public Cloudflare Worker code for x402-protected `/mcp/finance` and `/mcp/sec` endpoints. The Intelligence scan verified:
+
+- `https://mcp.toolstem.com/` returned HTTP 200
+- `https://mcp.toolstem.com/health` returned HTTP 200
+- `POST /mcp/finance` returned HTTP 402 with x402 payment-required details
+- the payment challenge used Base Sepolia USDC during the 16:03 CT check
+
+That is a live gateway signal. It is not a claim about production maturity, custody quality, downstream data quality, or spend-control depth.
+
+A follow-up check from this implementation run also returned a `payment-required` header where `payTo` decoded to the zero address. Treat that as preflight evidence, not a broad verdict on Toolstem. It is exactly why a buyer-side verifier should fail closed before signing.
+
+## The buyer checklist
+
+Do not let an agent pay a hosted x402 MCP proxy until these checks pass:
+
+1. **Payment-required header exists.** Require `payment-required` or `x-payment-required` on the HTTP 402 response. Body-only metadata is too easy for scanners and buyers to miss.
+2. **`payTo` is present and non-zero.** Reject missing recipients, malformed addresses, and `0x0000000000000000000000000000000000000000`.
+3. **Network is allowlisted.** For AgentPay MCP today, that usually means Base mainnet or Base Sepolia, depending on the wallet config and test path.
+4. **Asset is allowlisted.** Treat "USDC-like" as insufficient. Match the exact asset address or known native-asset encoding.
+5. **Amount is under the spend cap.** Validate `amount` or `maxAmountRequired` before signing. The cap check must happen before `x402_pay` sends a proof.
+6. **Approval gate is satisfied.** If the policy requires human approval, the current state must be `approved`, not merely requested.
+7. **Audit log is ready.** Record endpoint, tool call, recipient, amount, network, asset, approval state, policy version, and receipt.
+8. **Pooled-token lock-in is explicit.** If the proxy uses operator-held upstream credentials, the buyer must accept that model on purpose. Unknown is not accepted by default.
+
+## Test path in AgentPay MCP
+
+`src/utils/hosted-proxy-verification.ts` adds a buyer-side verification helper. It validates the remote 402 challenge and the local buyer controls before payment.
+
+Minimal use:
+
+```ts
+import { verifyHostedProxyPaymentRequirement } from 'agentpay-mcp/dist/utils/hosted-proxy-verification.js';
+
+const result = verifyHostedProxyPaymentRequirement({
+  status: 402,
+  headers: { 'payment-required': paymentRequiredHeader },
+  allowedNetworks: ['base-sepolia'],
+  allowedAssets: ['0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'],
+  maxAmountRequired: '25000',
+  approvalGate: { required: true, state: 'approved' },
+  auditLog: { required: true, destination: 'otel', correlationId: 'tool-call-123' },
+  upstreamCredentialMode: 'buyer-owned',
+});
+
+if (!result.ok) {
+  throw new Error(result.failures.join('\n'));
+}
+```
+
+The tests cover the failure cases buyers care about:
+
+- missing or body-only payment-required metadata
+- zero or malformed `payTo`
+- network drift
+- asset mismatch
+- amount over the spend cap
+- pending approval
+- missing audit correlation
+- unresolved operator-pooled upstream tokens
+
+Run:
+
+```bash
+npm test -- --run tests/hosted-proxy-verification.test.ts
+```
+
+## AgentPay position
+
+AgentPay MCP is not trying to be every hosted data proxy. It is the buyer-side payment-control layer: verify the 402, enforce policy, gate approval, sign locally, and write the audit row.
+
+Use hosted proxies when they save setup time. Keep spend authority in AgentPay before the signature exists.

package/docs/mcp-registry-listing-proof.md

@@ -0,0 +1,62 @@
+# AgentPay MCP directory-grade metadata proof
+
+Paid MCP buyers are starting discovery in catalogs before they read a repository. AgentPay MCP therefore keeps a directory-grade metadata bundle in the repo and npm package.
+
+## Registry and listing surfaces
+
+- npm package: `agentpay-mcp`
+- MCP package identity: `io.github.up2itnow0822/agentpay`
+- Repository: `https://github.com/up2itnow0822/agentpay-mcp`
+- Glama listing: `https://glama.ai/mcp/servers/up2itnow0822/claw-pay-mcp`
+- Glama metadata file: `glama.json`
+- Smithery-compatible install metadata: `smithery.yaml`
+- Directory install proof: `docs/directory-introspection-readiness.md`
+- LLM crawler summary: `llms.txt`
+- Registry-ready JSON: `docs/mcp-registry-listing.json`
+
+The Glama listing slug still reflects the older `claw-pay-mcp` crawl identity. That is the valid current listing proof. Do not create a fake claim file for a directory that has not issued one. Use `glama.json`, the live Glama URL, npm identity, and repository metadata as the current claim artifacts.
+
+## Install-readiness checks
+
+A directory crawler can verify AgentPay MCP without custodying user funds:
+
+```bash
+npm pack --dry-run --json
+npm exec --yes agentpay-mcp -- --help
+```
+
+For MCP introspection, initialize before `tools/list`:
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"registry-check","version":"0.0.1"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | \
+  AGENT_WALLET_ADDRESS=0x0000000000000000000000000000000000000000 npx -y agentpay-mcp
+```
+
+Expected result: `initialize` returns `agentpay-mcp`, then `tools/list` returns the payment and budget tools. The package must not generate a wallet, ask for hosted custody, or sign any payment during listing introspection.
+
+## Tool description standard
+
+Directory-facing paid tools should tell buyers when to use the tool and when not to use it.
+
+- `x402_pay`: use for one capped paid HTTP request; do not use for unknown networks, missing spend caps, or uninitialized Streamable HTTP MCP sessions.
+- `x402_session_start`: use for a reusable paid entitlement; do not use if the provider lacks session semantics or if the buyer cannot store the returned session ID.
+- `x402_session_fetch`: use after a valid session exists; do not use as a payment bypass or before `x402_session_start`.
+- Budget tools: use for local policy enforcement before signing; do not treat catalog metadata as approval.
+
+Every input field on paid tools must explain units, defaults, and failure behavior. Amount caps should name ETH-equivalent units. Network fields should name Base mainnet `8453` and Base Sepolia `84532` where relevant.
+
+## Buyer safety language
+
+AgentPay MCP metadata must preserve these claims:
+
+- non-custodial local signing
+- operator-supplied wallet configuration
+- Base mainnet and Base Sepolia x402 exact-payment support
+- fail-closed unsupported networks
+- spend caps before signing
+- receipt/audit trail requirements
+
+Directory metadata rule: do not claim directory hosting, managed wallets, or verified listings that are not live.

package/docs/mcp-registry-listing.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": "2026-05-03.agentpay-mcp.directory-proof.v1",
+  "name": "AgentPay MCP",
+  "package": "agentpay-mcp",
+  "mcp_name": "io.github.up2itnow0822/agentpay",
+  "repository": "https://github.com/up2itnow0822/agentpay-mcp",
+  "homepage": "https://github.com/up2itnow0822/agentpay-mcp#readme",
+  "description": "Non-custodial x402 payment, budget, and receipt tools for MCP clients.",
+  "install": {
+    "npx": {
+      "command": "npx",
+      "args": ["-y", "agentpay-mcp"]
+    },
+    "docker": {
+      "build": "docker build -t agentpay-mcp:registry-check .",
+      "run": "docker run --rm -i -e AGENT_WALLET_ADDRESS=0x0000000000000000000000000000000000000000 agentpay-mcp:registry-check"
+    }
+  },
+  "metadata_files": [
+    "glama.json",
+    "smithery.yaml",
+    "llms.txt",
+    "docs/directory-introspection-readiness.md",
+    "docs/mcp-registry-listing-proof.md"
+  ],
+  "listing_proofs": {
+    "glama": "https://glama.ai/mcp/servers/up2itnow0822/claw-pay-mcp",
+    "npm": "https://www.npmjs.com/package/agentpay-mcp"
+  },
+  "custody_model": "operator_supplied_non_custodial_wallet",
+  "supported_x402_networks": [
+    { "chain_id": 8453, "network": "base", "purpose": "production" },
+    { "chain_id": 84532, "network": "base-sepolia", "purpose": "test" }
+  ],
+  "do_not_use_when": [
+    "The buyer expects the MCP directory to custody private keys.",
+    "The paid endpoint offers only unsupported networks.",
+    "The buyer cannot enforce a spend cap before signing."
+  ]
+}

package/docs/paid-mcp-gateway-hardening.md

@@ -0,0 +1,121 @@
+# Paid MCP gateway hardening checklist
+
+`create-mcpay@0.7.1` makes Cloudflare Worker paid-agent gateways look easy to scaffold. Its README claims x402-compatible signup, hashed bearer keys, Durable Object atomic charging, validate-before-charge behavior, default-deny scopes, no admin CORS, and 36 attack-scenario coverage.
+
+That raises the bar for AgentPay MCP docs. Builders will compare paid MCP gateways on security defaults, not just on whether an HTTP 402 handshake exists.
+
+## Hardening checks
+
+A paid MCP gateway should pass these checks before public use:
+
+### Signup and challenge parsing
+
+- `/v1/signup` or equivalent returns HTTP 402 before a payment credential exists.
+- The challenge is visible in a payment-aware header, not only in a JSON body.
+- Network, asset, amount, decimals, and recipient are parsed before any key is minted.
+- Body-only payment metadata fails closed for buyer verification.
+
+### Key minting
+
+- Raw bearer token is visible only at mint time.
+- Stored token material is hashed with `sha256`, `bcrypt`, or `argon2`.
+- Admin key comparison is timing safe.
+- Minting has a maximum balance ceiling.
+
+### Atomic billing
+
+- Debit is atomic.
+- A real concurrency guard is present, such as Durable Object `blockConcurrencyWhile`, a transaction, or a lock.
+- Malformed requests do not charge the buyer.
+- Provider failure refund policy is documented before production use.
+
+### Scope defaults and browser surface
+
+- A key with no explicit scopes cannot call paid endpoints.
+- Endpoint to scope mapping has one source of truth.
+- Admin routes do not expose browser CORS.
+- Request body reads are bounded, with 16 KB as the preferred default.
+
+### Buyer audit trail
+
+Each paid call needs an audit row with:
+
+- buyer or key identity,
+- endpoint or tool name,
+- charged amount,
+- payment receipt or transaction reference,
+- idempotency key,
+- balance before and after charge.
+
+## Test fixture response
+
+The helper added in this response is `src/utils/paid-mcp-gateway-hardening.ts`. It scores a gateway fixture and fails closed when a scaffold skips any required control.
+
+```ts
+import { verifyPaidMcpGatewayHardening } from './src/utils/paid-mcp-gateway-hardening.js';
+
+const result = verifyPaidMcpGatewayHardening({
+  signup: {
+    enabled: true,
+    challengeStatus: 402,
+    challengeHeader: 'Payment realm="signup", protocol="x402"',
+    validatesBeforeKeyMint: true,
+  },
+  challengeParsing: {
+    validatesNetwork: true,
+    validatesAsset: true,
+    validatesAmount: true,
+    validatesRecipient: true,
+    rejectsBodyOnlyChallenge: true,
+  },
+  keyMinting: {
+    rawTokenVisibleOnlyAtMint: true,
+    tokenHashAlgorithm: 'sha256',
+    adminKeyTimingSafe: true,
+    maxMintCeiling: true,
+  },
+  billing: {
+    atomicDebit: true,
+    concurrencyGuard: 'durable-object-blockConcurrencyWhile',
+    noChargeOnValidationFailure: true,
+    refundPolicyForProviderFailure: true,
+  },
+  scopes: {
+    defaultDeny: true,
+    endpointScopeMapSingleSource: true,
+  },
+  browserSurface: {
+    adminCorsDisabled: true,
+    bodyReadLimitBytes: 16384,
+  },
+  buyerAudit: {
+    recordsBuyer: true,
+    recordsEndpoint: true,
+    recordsAmount: true,
+    recordsPaymentReceipt: true,
+    recordsIdempotencyKey: true,
+    recordsBalanceBeforeAfter: true,
+  },
+});
+
+if (!result.ok) throw new Error(result.failures.join('\n'));
+```
+
+## create-mcpay response map
+
+| Template claim | AgentPay hardening response |
+|---|---|
+| x402-compatible signup | Require HTTP 402 signup challenge and receipt validation before key minting |
+| Hashed bearer keys | Require raw token only at mint time and hashed storage |
+| Durable Object charging | Require atomic debit plus a named concurrency guard |
+| Validate-before-charge | Require no-charge validation failures in tests |
+| Default-deny scopes | Require explicit scopes and one endpoint-scope source of truth |
+| No admin CORS | Require admin routes to stay outside browser CORS |
+| Security posture claims | Convert claims into fixture checks and audit proof |
+
+## Validation proof
+
+- Helper: `src/utils/paid-mcp-gateway-hardening.ts`
+- Tests: `tests/paid-mcp-gateway-hardening.test.ts`
+- README link: `README.md`
+- Validation command: `npm test -- --run tests/paid-mcp-gateway-hardening.test.ts`

package/docs/paid-provider-health-proof.md

@@ -0,0 +1,71 @@
+# Paid-provider health proof checklist
+
+A paid agent should not route work because a marketplace status page says the base service is up. It needs a machine-readable proof that answers a narrower question: which provider can receive paid work now, and what evidence says the payment path is safe?
+
+Voidly Pay's public `pay-health/latest.json` is the right direction. On May 2, 2026, the feed reported base `health.ok: true`, but top-level `ok: false`: 5 providers probed, 2 ok, 3 failing, and `success_rate: 0.4`. Its `pay-health/stale.json` also showed stale failure streaks of 207, 207, and 312 for the failing capabilities. That is exactly why buyer agents need provider-level gates before paying.
+
+AgentPay's buyer rule is fail closed. A provider is routable only when the health proof, receipt state, stale counter, and x402 payment metadata all pass policy.
+
+## Required fields
+
+Use [`paid-provider-health-proof.schema.json`](paid-provider-health-proof.schema.json) for a portable proof shape and [`fixtures/paid-provider-health-proof-voidly-2026-05-02.json`](fixtures/paid-provider-health-proof-voidly-2026-05-02.json) for a concrete failure fixture.
+
+The proof must include:
+
+- `generated_at` and `source` so buyers can reject stale or unauthenticated feeds.
+- `health.ok` and top-level `ok` as separate values. Base service health does not prove provider routability.
+- `summary.providers_probed`, `providers_ok`, `providers_failing`, and `success_rate`.
+- Per-provider `status`, `stale_streak`, `receipt_state`, `receipt_id`, `verified`, and latency.
+- Per-provider `x402_payment` metadata with `network`, `asset`, `payTo`, and amount fields.
+- `routing.fail_closed: true` plus an explicit `decision` and reasons.
+
+## Buyer routing policy
+
+Before signing, the buyer should verify:
+
+1. The proof is fresh enough for the task's risk level.
+2. `summary.success_rate` meets the buyer's minimum.
+3. `providers_ok + providers_failing` matches `providers_probed`.
+4. Every selected provider has `status: ok`, `stale_streak` at or below policy, and a verified receipt state.
+5. The x402 offer uses an allowed `network`, allowed `asset`, non-zero allowlisted `payTo`, and a positive amount.
+6. `routing.fail_closed` is true. If the proof is missing or inconsistent, do not pay.
+
+## TypeScript verification
+
+```ts
+import { verifyPaidProviderHealthProof } from 'agentpay-mcp/dist/utils/paid-provider-health-proof.js';
+import proof from './paid-provider-health-proof-voidly-2026-05-02.json' assert { type: 'json' };
+
+const result = verifyPaidProviderHealthProof(proof, {
+  minimumSuccessRate: 0.95,
+  maxProofAgeMs: 15 * 60 * 1000,
+  maxProviderStaleStreak: 2,
+  allowedNetworks: ['base-sepolia'],
+  allowedAssets: ['0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'],
+  allowedPayTo: [
+    '0x1111111111111111111111111111111111111111',
+    '0x2222222222222222222222222222222222222222'
+  ],
+  requireVerifiedReceipt: true,
+  requireX402PaymentMetadata: true
+});
+
+if (!result.ok) {
+  // Fail closed: do not sign x402 payment yet.
+  console.error(result.failures);
+}
+```
+
+The May 2 Voidly-derived fixture is expected to fail with a strict production policy because success rate is 0.4 and three providers are stale. The two ok providers still show how a buyer validates receipt and x402 metadata once the network-level proof is healthy.
+
+## Fail-closed routing guidance
+
+Use these defaults for paid provider selection:
+
+- Treat missing health proof as `deny`.
+- Treat stale `generated_at` as `deny` unless a human explicitly approves degraded mode.
+- Treat `health.ok: true` plus `ok: false` as `deny` for new paid work.
+- Treat missing `x402_payment.network`, `asset`, or `payTo` as `deny`.
+- Treat mismatched network, asset, or recipient as `deny` even if the provider's last receipt was verified.
+- Log the proof hash, selected provider ID, receipt ID, x402 network, asset, payTo, amount, policy version, and approval ID before signing.
+

package/docs/paid-provider-health-proof.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/up2itnow0822/agentpay-mcp/blob/main/docs/paid-provider-health-proof.schema.json",
+  "title": "AgentPay paid-provider health proof",
+  "type": "object",
+  "required": ["schema", "generated_at", "source", "health", "ok", "summary", "providers", "routing"],
+  "properties": {
+    "schema": { "const": "agentpay-paid-provider-health-proof/v1" },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "source": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "url": { "type": "string", "format": "uri" },
+        "commit": { "type": "string", "minLength": 7 },
+        "raw_schema": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "health": {
+      "type": "object",
+      "required": ["ok"],
+      "properties": {
+        "ok": { "type": "boolean" },
+        "latency_ms": { "type": "number", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "ok": { "type": "boolean" },
+    "summary": {
+      "type": "object",
+      "required": ["providers_probed", "providers_ok", "providers_failing", "success_rate"],
+      "properties": {
+        "providers_probed": { "type": "integer", "minimum": 0 },
+        "providers_ok": { "type": "integer", "minimum": 0 },
+        "providers_failing": { "type": "integer", "minimum": 0 },
+        "success_rate": { "type": "number", "minimum": 0, "maximum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "providers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["provider_id", "status", "stale_streak", "receipt_state", "verified"],
+        "properties": {
+          "provider_id": { "type": "string", "minLength": 1 },
+          "capability": { "type": "string", "minLength": 1 },
+          "capability_id": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["ok", "failed", "stale", "unknown"] },
+          "stale_streak": { "type": "integer", "minimum": 0 },
+          "receipt_state": { "enum": ["verified", "pending_acceptance_verified", "missing", "invalid", "unverified"] },
+          "receipt_id": { "type": "string", "minLength": 1 },
+          "verified": { "type": "boolean" },
+          "latency_ms": { "type": "number", "minimum": 0 },
+          "error": { "type": "string", "minLength": 1 },
+          "x402_payment": {
+            "type": "object",
+            "required": ["scheme", "network", "asset", "payTo"],
+            "properties": {
+              "scheme": { "const": "exact" },
+              "network": { "type": "string", "minLength": 1 },
+              "asset": { "type": "string", "minLength": 1 },
+              "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
+              "amountRequired": { "type": "string", "pattern": "^[1-9][0-9]*$" },
+              "maxAmountRequired": { "type": "string", "pattern": "^[1-9][0-9]*$" },
+              "resource": { "type": "string", "format": "uri" },
+              "facilitator": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "routing": {
+      "type": "object",
+      "required": ["fail_closed", "decision", "reason"],
+      "properties": {
+        "fail_closed": { "const": true },
+        "decision": { "enum": ["allow", "deny", "degraded"] },
+        "reason": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/docs/settlegrid-paid-mcp-discovery-response.md

@@ -0,0 +1,61 @@
+# Paid MCP discovery and budget response
+
+SettleGrid is useful market validation for paid MCP. It shows that discovery, metering, budget checks, remote MCP endpoints, and protocol routing are becoming part of the buyer's comparison set.
+
+AgentPay MCP should answer that shift directly: discovery helps an agent find a paid tool, but it must not become payment authorization.
+
+## Verified SettleGrid signal
+
+On 2026-05-01, the Intelligence cycle verified these public SettleGrid claims and endpoints:
+
+- `@settlegrid/mcp` on npm at version `0.1.1`
+- `@settlegrid/discovery` on npm at version `1.0.1`
+- repo commits at 2026-05-02T00:47:42Z and 2026-05-02T00:55:11Z, including a Stripe-only rail cutover playbook
+- README claims for 14 payment protocols, built-in discovery, agent identity, budget enforcement, an HTTP MCP endpoint, an MCP discovery server, and 1,017 billing-ready templates
+- `https://settlegrid.ai/api/openapi.json` returning paths including `/api/sdk/validate-key`, `/api/sdk/meter`, `/api/sessions`, `/api/agents`, and `/api/x402/verify`
+- `https://settlegrid.ai/api/v1/discover` returning active monetized tool records with per-method pricing
+
+Those are real platform signals. They do not remove the buyer's need to verify before payment.
+
+## AgentPay's answer
+
+AgentPay MCP wins by keeping spend authority at the buyer edge.
+
+A paid MCP directory can tell an agent where a tool is. AgentPay decides whether the agent is allowed to pay for it.
+
+Before signing an x402 payment, AgentPay should verify:
+
+1. The response is HTTP 402 with a parseable `payment-required` or `x-payment-required` header.
+2. `payTo` is present, valid, expected, and non-zero.
+3. The requested network is on the wallet policy allowlist.
+4. The requested asset matches an allowed asset exactly.
+5. The amount is positive and under the per-call or session cap.
+6. Required human approval is already `approved`.
+7. The audit row can record endpoint, tool call, recipient, network, asset, amount, policy version, approval state, and receipt.
+8. Any hosted proxy or operator-pooled upstream credential path is explicitly accepted by policy.
+
+## What to copy and what not to copy
+
+Copy the buyer-visible parts:
+
+- clean directory metadata
+- simple install paths
+- live discovery endpoints
+- per-tool pricing fields
+- clear metering and budget language
+
+Do not copy hosted lock-in as the default:
+
+- do not require platform-held buyer funds by default
+- do not hide recipient or asset fields behind a dashboard
+- do not treat directory discovery as spend approval
+- do not let platform-side budget checks replace wallet-edge caps
+
+## Recommended AgentPay ship path
+
+1. Keep the hosted proxy verifier documented and packaged.
+2. Add a discovery plus budget FAQ to the README that separates directory search from x402 authorization.
+3. Add a docs test that fails if the required buyer controls disappear from this guide.
+4. Add a scanner fixture that proves a discovered paid MCP endpoint still fails closed until approval and spend caps pass.
+
+AgentPay's posture is simple: discover widely, verify locally, cap before signing, approve intentionally, and audit every paid call.

package/docs/x402-ecosystem-submission.md

@@ -0,0 +1,22 @@
+# x402 Ecosystem Submission Notes
+
+This document tracks the public ecosystem listing request for `agentpay-mcp` in the x402 Foundation website repository.
+
+- **Upstream PR:** `x402-foundation/x402` PR #1562
+- **Title:** `feat(ecosystem): add agentpay-mcp to client-side integrations`
+- **Proposed category:** Client-Side Integrations
+- **Package:** [`agentpay-mcp` on npm](https://www.npmjs.com/package/agentpay-mcp)
+
+## Why this integration matters
+
+`agentpay-mcp` is focused on the payer/client side of x402 workflows. It allows autonomous agents to detect `402 Payment Required` responses, execute the payment flow, and retry requests with policy controls.
+
+## Merge blockers called out in the upstream PR
+
+At the time these notes were captured, the upstream PR reported:
+
+1. missing required reviewer approval from a maintainer with write access;
+2. unsigned or unverified commit signature requirement not yet satisfied; and
+3. a Vercel authorization gate for deployment preview.
+
+These blockers are in the upstream repository and are not controlled by this repository's CI.

package/docs/x402-native-vs-stripe-proxy.md

@@ -40,7 +40,7 @@ That is different from routing every paid call through a proxy that owns the dow
 AgentPay MCP currently has public discovery and package proof:
 
 - Glama listing: https://glama.ai/mcp/servers/up2itnow0822/claw-pay-mcp
-- npm package: `agentpay-mcp@4.1.6` or newer
+- npm package: `agentpay-mcp@4.1.8` or newer
 - Packaged catalog metadata: `glama.json` and `smithery.yaml`
 - Packaged install paths: `npx` and Docker
 - Introspection proof: 27 MCP tools, including `x402_pay`, `check_budget`, `set_spend_policy`, and `otel_evaluate_spend`

package/docs/x402-v211-paid-mcp-compatibility.md

@@ -0,0 +1,75 @@
+# AgentPay MCP x402 v2.11 paid MCP compatibility proof
+
+Toolstem's May 3 paid MCP updates made a subtle problem visible: a payment can settle and the MCP call can still fail if the client, gateway, or browser uses the wrong header contract.
+
+AgentPay MCP treats the following as the v2.11 paid MCP baseline for buyer agents and hosted gateways.
+
+## Header contract
+
+- Payment request header from client to gateway: `Payment-Signature`
+- Deprecated header: `X-Payment`
+- Receipt header from gateway to client: `payment-response`
+- MCP session continuity header from gateway to client: `mcp-session-id`
+- Browser-readable CORS expose value: `payment-response, mcp-session-id`
+
+Do not accept `X-Payment` as the primary path in new paid MCP integrations. Keep it only as a migration alias when a legacy upstream requires it, and log that downgrade as compatibility debt.
+
+## Browser and Streamable HTTP gateway rule
+
+If a paid MCP gateway serves browser-based clients, set this response header on initialize and paid tool responses:
+
+```http
+Access-Control-Expose-Headers: payment-response, mcp-session-id
+```
+
+Without it, browser clients may pay successfully and still be unable to read the receipt or session identifier. That breaks audit trails, retries, and follow-up `tools/call` requests.
+
+## Streamable HTTP initialize sequence
+
+Paid Streamable HTTP clients should use this order:
+
+1. Send MCP `initialize` first. If the gateway charges for initialize, sign the request with `Payment-Signature`.
+2. Read `payment-response` and `mcp-session-id` from exposed response headers.
+3. Send `notifications/initialized` only after initialize succeeds.
+4. Call `tools/list` after the initialized notification is accepted.
+5. Call `tools/call` with `mcp-session-id` when the gateway requires session continuity.
+
+Do not call `tools/call` before initialize. Do not hide receipt or session headers behind browser CORS. Do not let a model retry a paid call when initialize failed or the session header is missing.
+
+## AgentPay MCP client behavior
+
+`x402_pay` remains the direct paid-fetch tool for one-off x402 endpoints. Use it when the buyer already has a target URL, a spend cap, and no reusable session requirement.
+
+`x402_session_start` is the better choice when the paid endpoint supports session semantics or the buyer expects repeated calls under one paid entitlement.
+
+Do not use either tool when the offered network is outside the configured Base mainnet or Base Sepolia x402 policy. AgentPay MCP fails closed instead of guessing a rail.
+
+## Network-aware receipt links
+
+AgentPay MCP uses the configured `CHAIN_ID` to turn transaction hashes into the right receipt link:
+
+| Chain ID | Network | Receipt base URL |
+|----------|---------|------------------|
+| `84532` | Base Sepolia | `https://sepolia.basescan.org/tx/<txHash>` |
+| `8453` | Base mainnet | `https://basescan.org/tx/<txHash>` |
+
+A receipt proof must store the chain ID with the transaction hash. A hash without network context is not enough for buyer auditability.
+
+## Base Sepolia to Base mainnet cutover checklist
+
+Use this checklist before moving a paid MCP gateway from testnet to Base mainnet:
+
+1. Change `CHAIN_ID` from `84532` to `8453`.
+2. Change `RPC_URL` from `https://sepolia.base.org` or a Sepolia provider endpoint to a Base mainnet endpoint.
+3. Replace testnet USDC or test payment assets with the production Base asset address accepted by the gateway.
+4. Confirm `payTo` is the production recipient and not a test wallet.
+5. Keep `Payment-Signature` as the signing header. Do not revert to `X-Payment` during cutover.
+6. Expose `payment-response` and `mcp-session-id` through CORS for browser clients.
+7. Run initialize, `notifications/initialized`, `tools/list`, and one capped `tools/call` on mainnet with a small spend cap.
+8. Store receipt links with `chainId=8453` and verify the links point to `basescan.org`, not `sepolia.basescan.org`.
+9. Update README, registry metadata, and any directory listing notes from Base Sepolia examples to Base mainnet production status.
+10. Keep a rollback note that returns the gateway to `84532` only for test traffic.
+
+## Verification artifact
+
+The constants and receipt-link helper live in `src/utils/x402-v211-compatibility.ts`. Tests in `tests/x402-v211-compatibility.test.ts` assert the header names, CORS exposure value, Streamable HTTP sequence, and Base Sepolia/Base mainnet receipt links.

package/llms.txt

@@ -0,0 +1,21 @@
+# AgentPay MCP
+
+AgentPay MCP is a non-custodial MCP server for x402 payment, budget, receipt, and wallet operations. It is published as `agentpay-mcp` and uses the MCP package identity `io.github.up2itnow0822/agentpay`.
+
+Repository: https://github.com/up2itnow0822/agentpay-mcp
+npm: https://www.npmjs.com/package/agentpay-mcp
+Glama listing: https://glama.ai/mcp/servers/up2itnow0822/claw-pay-mcp
+
+Use AgentPay MCP when an agent needs to pay x402-protected HTTP or MCP endpoints with local wallet control, spend caps, and receipt auditability. Use `x402_pay` for one capped paid request. Use `x402_session_start` and `x402_session_fetch` when a provider supports reusable paid sessions.
+
+Do not use AgentPay MCP as a managed-wallet custody service. Do not ask a directory or hosted catalog to store `AGENT_PRIVATE_KEY`. Do not sign payments for unsupported networks or endpoints that do not expose enough payment metadata to verify `payTo`, network, asset, amount, receipt, and session state.
+
+Required environment variables for paid calls: `AGENT_PRIVATE_KEY`, `AGENT_WALLET_ADDRESS`, `CHAIN_ID`, and `RPC_URL`. Directory introspection can list tools with a placeholder wallet address and no private key because no payment is signed during `initialize` or `tools/list`.
+
+Important docs:
+
+- `README.md` for user setup and tool list
+- `docs/x402-v211-paid-mcp-compatibility.md` for `Payment-Signature`, `payment-response`, `mcp-session-id`, CORS, Streamable HTTP initialize order, receipt links, and Base Sepolia to Base mainnet cutover
+- `docs/mcp-registry-listing-proof.md` for registry, Glama, Smithery, and install-readiness proof
+- `docs/directory-introspection-readiness.md` for npx and Docker introspection
+- `docs/dependency-pin-policy.md` for payment-critical dependency pinning