agentpay-mcp 4.1.15 → 4.1.16

package/README.md

@@ -100,6 +100,9 @@ AgentPay MCP is built for enterprise MCP deployments where supply chain security
 - **Multi-ledger x402 receipt normalization.** Use the [multi-ledger receipt normalization proof](docs/x402-multi-ledger-receipt-normalization.md), schema, and XRPL fixture to normalize ledger labels, assets, settlement targets, `Payment-Signature`, `payment-response`, verification status, non-custodial boundaries, and unsupported-ledger refusals before signing.
 - **Wallet-action preflight profile.** Use the [wallet-action preflight profile](docs/wallet-action-preflight-profile.md) and TRON fixture to require simulation, chain/resource caps, allowlists, recipient and amount confirmation, nonce guidance, and approval copy before irreversible sends, swaps, or resource purchases.
 - **Machine-payment directory listing pack.** Use the [directory listing pack](docs/agentpay-machine-payment-directory-listing-pack.md) and [listing JSON](docs/agentpay-machine-payment-directory-listing.json) for MPP and paid-MCP directories without claiming unsupported non-EVM signing.
+- **Five-tool x402 parity proof.** Use the [five-tool parity proof](docs/agentpay-five-tool-parity-proof.md) and [machine-readable map](docs/agentpay-five-tool-parity-proof.json) to map search, check, fetch, wallet, and pay flows to AgentPay's local-signer, approval-gated controls.
+- **Escrow and reputation boundary.** Use the [escrow/reputation boundary proof](docs/agentpay-escrow-reputation-boundary.md) to keep x402 payment authorization separate from task escrow, identity, reputation, and work proof.
+- **Paid MCP proxy and discovery readiness.** Use the [paid-proxy and discovery readiness pack](docs/paid-mcp-proxy-discovery-readiness.md) plus [listing JSON](docs/agentpay-paid-proxy-discovery-listing.json) for Toolstem/Cinderwright-style proxy and directory submissions.
 - **Dynamic paid MCP manifest drift.** Use the [dynamic manifest drift proof](docs/x402-dynamic-paid-mcp-manifest-drift.md), schema, and Rug Munch fixtures to validate fresh `.well-known/x402` snapshots, stale-metadata warnings, no-trial/pricing clarity, supported networks, and directory endpoint freshness before buyer agents sign.
 - **Smithery paid MCP installation.** Use the [Smithery install proof](docs/smithery-paid-mcp-installation.md) and [`examples/smithery-paid-mcp-installation`](examples/smithery-paid-mcp-installation/) for Smithery CLI, Vercel AI SDK MCP, `@smithery/api`, approval gates, spend-limit defaults, and fresh x402 manifest checks. Do not claim live Smithery verification until the listing is verified.
 - **x402-native vs Stripe-proxy MCP.** For builders comparing AgentPay MCP with emerging Stripe-proxy MCP repos, use the [x402-native vs Stripe-proxy note](docs/x402-native-vs-stripe-proxy.md) to keep approval gates, spend caps, audit rows, and non-custodial signing separate from proxy billing claims.

package/docs/agentpay-escrow-reputation-boundary.md

@@ -0,0 +1,64 @@
+# AgentPay escrow and reputation boundary proof
+
+Execution Market packages x402 payment claims with escrow, ERC-8004 identity, A2A task execution, World ID proof, worker evidence, and reputation. That is a useful market signal: buyers will compare payment tools by trust outcomes, not only by payment headers.
+
+This proof separates the layers so buyers do not treat payment authorization as proof that work was completed.
+
+## Market signal
+
+Source: `UltravioletaDAO/execution-market` README, fetched during the May 4 market-intel cycle.
+
+Observed claims:
+
+- Task bounties can lock USDC in on-chain escrow.
+- The product exposes MCP, REST, WebSocket, and A2A paths.
+- Identity references include ERC-8004 and World ID.
+- Worker submissions, evidence, approval, cancellation, refund, and escrow-state checks sit around payment.
+- x402 is part of a broader task market, not the whole trust system.
+
+## Boundary table
+
+| Layer | What the buyer needs | AgentPay role | Boundary |
+|---|---|---|---|
+| Payment authorization | Decide whether an agent may spend a given amount to a given recipient | Enforce approval gates, hard spend caps, allowlists, x402 metadata checks, and receipt logging | Payment authorization does not prove the seller did the task. |
+| x402 settlement | Produce and verify the payment proof for a paid endpoint | Sign and retry x402 calls only after policy passes | x402 receipt is payment evidence, not work evidence. |
+| Escrow | Lock funds until task terms, evidence, and approval rules are satisfied | AgentPay has a separate `create_escrow` tool for mutual-stake escrow when a factory is configured | Escrow must be explicit. It must not be hidden inside `x402_pay`. |
+| Identity | Bind buyers, workers, agents, and policies to identities | AgentPay exposes wallet and identity/reputation utilities from the wallet stack | Identity signals can inform policy, but they are not spend approval by themselves. |
+| Reputation | Score prior behavior and outcomes | AgentPay can read reputation signals and log payment outcomes | Reputation should be an input to policy, not the only policy. |
+| Work proof | Validate evidence, fulfillment, dispute state, and release conditions | Integration boundary with task-market or verifier systems | Work proof belongs above payment execution. |
+
+## Safe buyer architecture
+
+Use AgentPay as the x402 control layer in front of any task marketplace or paid worker flow:
+
+1. Discover the task or endpoint.
+2. Read identity, reputation, escrow, and work-proof requirements.
+3. Run AgentPay policy checks for spend cap, `payTo`, asset, network, price, manifest freshness, provider health, and approval mode.
+4. If the task requires escrow, call an escrow-specific flow such as `create_escrow`; do not treat a normal x402 receipt as escrow.
+5. Release or dispute funds only through the task-market or escrow contract state machine.
+6. Persist x402 receipts, escrow transaction hashes, worker evidence IDs, and approval logs as separate audit fields.
+
+## AgentPay guarantees today
+
+AgentPay can guarantee these payment-control properties when configured correctly:
+
+- Non-custodial local signing.
+- Human approval for high-risk or high-value payments.
+- Per-transaction and daily spend caps.
+- Network, asset, recipient, and manifest checks.
+- x402 `Payment-Signature` and `payment-response` receipt handling.
+- Separate escrow creation through `create_escrow` when the wallet SDK factory is configured.
+- Fail-closed behavior for unsupported ledgers or incomplete payment metadata.
+
+AgentPay should not claim these as automatic x402 guarantees:
+
+- Worker identity verification.
+- World ID proof.
+- Task outcome verification.
+- Dispute resolution.
+- Reputation scoring accuracy.
+- Escrow release correctness.
+
+## Integration rule
+
+A task platform can integrate AgentPay safely by treating it as the buyer-side payment policy layer. The platform should keep escrow, worker evidence, reputation, identity, and dispute state in its own task protocol or contracts, then pass only verified payment intents to AgentPay for approval and signing.

package/docs/agentpay-five-tool-parity-proof.json

@@ -0,0 +1,56 @@
+{
+  "proof": "agentpay-five-tool-x402-parity",
+  "market_signal": "OpenDexter documents x402_search, x402_check, x402_fetch, x402_wallet, and x402_pay across hosted session wallets and a local signer package.",
+  "agentpay_position": "Buyer-flow parity with local signing, explicit policy checks, and fail-closed unsupported-ledger handling.",
+  "grammar": [
+    {
+      "canonical_tool": "x402_search",
+      "agentpay_equivalent": [
+        "docs/agentpay-machine-payment-directory-listing.json",
+        "docs/mcp-registry-listing-proof.md",
+        "docs/directory-introspection-readiness.md"
+      ],
+      "safety_rule": "Search metadata cannot authorize payment."
+    },
+    {
+      "canonical_tool": "x402_check",
+      "agentpay_equivalent": [
+        "check_budget",
+        "check_spend_limit",
+        "docs/x402-dynamic-paid-mcp-manifest-drift.md",
+        "docs/paid-provider-health-proof.md",
+        "docs/paid-tool-quality-thresholds.md"
+      ],
+      "safety_rule": "Fail closed when network, asset, payTo, price, manifest freshness, or quality proof is missing."
+    },
+    {
+      "canonical_tool": "x402_fetch",
+      "agentpay_equivalent": [
+        "x402_pay",
+        "x402_session_start",
+        "x402_session_fetch"
+      ],
+      "safety_rule": "No automatic payment before policy, approval, cap, receipt, and session checks pass."
+    },
+    {
+      "canonical_tool": "x402_wallet",
+      "agentpay_equivalent": [
+        "get_wallet_info",
+        "set_spend_policy",
+        "deploy_wallet",
+        "x402_session_status"
+      ],
+      "safety_rule": "Private keys remain local and are never stored in directory or proxy metadata."
+    },
+    {
+      "canonical_tool": "x402_pay",
+      "agentpay_equivalent": [
+        "x402_pay",
+        "docs/x402-multi-ledger-receipt-normalization.md",
+        "docs/wallet-action-preflight-profile.md"
+      ],
+      "safety_rule": "Sign only after network, asset, amount, recipient, policy, and approval checks."
+    }
+  ],
+  "unsupported_ledger_policy": "Non-EVM rails remain fail-closed extension points until signer, asset, receipt, refund, and settlement semantics are implemented."
+}

package/docs/agentpay-five-tool-parity-proof.md

@@ -0,0 +1,64 @@
+# AgentPay five-tool x402 parity proof
+
+OpenDexter documents a compact paid-MCP grammar: `x402_search`, `x402_check`, `x402_fetch`, `x402_wallet`, and `x402_pay`. That grammar is useful because it gives buyer agents one mental model for discovery, policy checks, fetching, wallet state, and final payment.
+
+AgentPay does not need to copy hosted session custody to be compatible with that buyer flow. The safer parity target is a mapping that lets agents run the same sequence while keeping signing local, policy explicit, and unsupported chains fail closed.
+
+## Market signal
+
+Source: `Dexter-DAO/dexter-mcp` README, fetched during the May 4 market-intel cycle.
+
+Observed claims:
+
+- Hosted sessions create one Solana address and one EVM address for the user.
+- `x402_fetch` checks balances across chains and picks the best-funded chain accepted by the endpoint.
+- Sessions persist for 30 days in PostgreSQL.
+- The local signer package exposes the same five-tool story and stores a local wallet file.
+- The local signing path is currently optimized around Solana.
+
+## AgentPay parity map
+
+| OpenDexter grammar | AgentPay equivalent | Proof surface | Buyer safety rule |
+|---|---|---|---|
+| `x402_search` | Directory/listing metadata, registry proof, and discovery docs | `docs/agentpay-machine-payment-directory-listing.json`, `docs/mcp-registry-listing-proof.md`, `docs/directory-introspection-readiness.md` | Search results are metadata only. They cannot authorize payment. |
+| `x402_check` | Budget, spend-limit, manifest, provider-health, quality, and chain checks | `check_budget`, `check_spend_limit`, `docs/x402-dynamic-paid-mcp-manifest-drift.md`, `docs/paid-provider-health-proof.md`, `docs/paid-tool-quality-thresholds.md` | Checks must fail closed when network, asset, `payTo`, price, manifest freshness, or quality proof is missing. |
+| `x402_fetch` | `x402_pay` for paid fetches, or `x402_session_fetch` for reusable paid sessions | `x402_pay`, `x402_session_start`, `x402_session_fetch`, `docs/x402-v211-paid-mcp-compatibility.md` | Fetch must not auto-pay unless policy, approval, cap, receipt, and session state pass first. |
+| `x402_wallet` | Local wallet info, policy, deployment, and session status | `get_wallet_info`, `set_spend_policy`, `deploy_wallet`, `x402_session_status` | Wallet state stays local. Directories and hosted proxies do not receive private keys. |
+| `x402_pay` | Approval-gated x402 payment execution | `x402_pay`, `docs/x402-multi-ledger-receipt-normalization.md`, `docs/wallet-action-preflight-profile.md` | Payment signs only after explicit network, asset, amount, recipient, policy, and approval checks. |
+
+## Hosted session wallet boundary
+
+Hosted session wallets can reduce onboarding friction, but they move two risks into the provider surface:
+
+1. The provider or database becomes part of the wallet trust boundary.
+2. Chain auto-selection can hide which ledger, asset, and settlement target the buyer is about to use.
+
+AgentPay's default posture is different:
+
+- Signing stays local to the buyer runtime.
+- Policy approval happens before payment, not after a provider selects a chain.
+- The buyer sees `payTo`, network, asset, amount, session, receipt, and unsupported-ledger refusal copy before signing.
+- Directory and proxy metadata can help the buyer discover endpoints, but metadata alone never grants spend authority.
+
+## Multi-chain selection guardrails
+
+If a paid MCP endpoint supports more than one network, AgentPay should preserve these guardrails before any future auto-selection flow:
+
+- Require an allowlist for network and asset.
+- Require non-zero and verified `payTo`.
+- Prefer a deterministic buyer policy over provider-selected best balance.
+- Log why a chain was selected.
+- Refuse Solana, XRPL, TRON, TVM, or other non-EVM payments until signer, asset, receipt, refund, and settlement semantics are implemented for that rail.
+- Show the final chain and asset in approval copy.
+
+## Acceptance proof
+
+A buyer agent can follow the five-step grammar today without handing custody to AgentPay or a hosted directory:
+
+1. Search: read AgentPay listing metadata and proof docs.
+2. Check: validate price, manifest, chain, provider health, quality, budget, and approval policy.
+3. Fetch: use `x402_pay` or `x402_session_fetch` only after checks pass.
+4. Wallet: inspect local wallet and active sessions without exposing private keys.
+5. Pay: sign a capped x402 payment and persist the receipt/audit trail.
+
+This is five-tool parity at the buyer-flow layer, with local signer safety instead of hidden hosted-session custody.

package/docs/agentpay-paid-proxy-discovery-listing.json

@@ -0,0 +1,42 @@
+{
+  "name": "agentpay-mcp",
+  "title": "AgentPay MCP",
+  "role": "buyer-side x402 payment-control layer for paid MCP tools",
+  "package": "agentpay-mcp",
+  "mcp_name": "io.github.up2itnow0822/agentpay",
+  "repository": "https://github.com/up2itnow0822/agentpay-mcp",
+  "npm": "https://www.npmjs.com/package/agentpay-mcp",
+  "install": {
+    "command": "npx",
+    "args": ["agentpay-mcp"],
+    "required_env": ["AGENT_PRIVATE_KEY", "AGENT_WALLET_ADDRESS", "CHAIN_ID", "RPC_URL"]
+  },
+  "supports": [
+    "MCP",
+    "x402 payment execution",
+    "human approval",
+    "per-transaction spend caps",
+    "daily spend caps",
+    "receipt logging",
+    "manifest freshness checks",
+    "provider-health checks",
+    "quality-threshold checks"
+  ],
+  "does_not_provide": [
+    "managed custody",
+    "pooled SaaS token custody",
+    "automatic non-EVM signing",
+    "task outcome verification",
+    "reputation scoring as payment approval"
+  ],
+  "proofs": [
+    "docs/agentpay-five-tool-parity-proof.md",
+    "docs/agentpay-escrow-reputation-boundary.md",
+    "docs/paid-mcp-proxy-discovery-readiness.md",
+    "docs/agentpay-machine-payment-directory-listing.json",
+    "docs/x402-dynamic-paid-mcp-manifest-drift.md",
+    "docs/paid-provider-health-proof.md",
+    "docs/paid-tool-quality-thresholds.md"
+  ],
+  "settlement_wording": "Buyer-side x402 payment controls with local non-custodial signing. Base/USDC-oriented production signing; unsupported non-EVM rails fail closed until signer, asset, receipt, refund, and settlement semantics are implemented."
+}

package/docs/paid-mcp-proxy-discovery-readiness.md

@@ -0,0 +1,70 @@
+# Paid MCP proxy and discovery readiness pack
+
+Toolstem and Cinderwright show the next buyer channel for paid tools: proxies that convert existing SaaS tools into x402-paid MCP endpoints, plus directories that compare paid services across x402, MPP, and L402.
+
+AgentPay should be easy for those surfaces to list without giving them custody, overstating ledger support, or hiding buyer policy.
+
+## Market signal
+
+Sources fetched during the May 4 market-intel cycle:
+
+- `toolstem/toolstem-proxy` describes an x402-paid proxy for Apify-backed MCP tools without Apify signup.
+- `cinderwright-ai/cinderwright-api` describes discovery data across x402, MPP, and L402, with 1,551 services and paid market-intelligence endpoints.
+
+## Paid-proxy recipe for tool authors
+
+Use this pattern when wrapping an existing API, actor, or MCP server with x402:
+
+1. Keep the upstream service token on the provider side. Do not ask buyer agents to hold pooled SaaS credentials.
+2. Publish a fresh `.well-known/x402` offer with price, asset, network, `payTo`, terms, and refund policy.
+3. Return typed 402 errors for unpaid, underpaid, wrong-network, stale-receipt, quota, and provider-health failures.
+4. Charge only after the request is valid enough to execute. Validation failures should not bill.
+5. Expose provider-health and quality fields before payment.
+6. Include idempotency keys so retries do not double charge.
+7. Make directory metadata crawlable without a private key.
+8. Let buyers bring AgentPay for approval gates, caps, allowlists, and x402 receipt logging.
+
+## AgentPay listing metadata
+
+Directories can list AgentPay with these fields:
+
+```json
+{
+  "name": "agentpay-mcp",
+  "role": "buyer-side x402 payment-control layer",
+  "package": "agentpay-mcp",
+  "mcp_name": "io.github.up2itnow0822/agentpay",
+  "settlement": "x402 with local non-custodial signing",
+  "supports": ["MCP", "x402", "human approval", "spend caps", "receipt logging"],
+  "does_not_provide": ["managed custody", "pooled SaaS token custody", "automatic non-EVM signing"],
+  "install": "npx agentpay-mcp",
+  "proofs": [
+    "docs/agentpay-five-tool-parity-proof.md",
+    "docs/agentpay-escrow-reputation-boundary.md",
+    "docs/agentpay-machine-payment-directory-listing.json",
+    "docs/x402-dynamic-paid-mcp-manifest-drift.md",
+    "docs/paid-provider-health-proof.md"
+  ]
+}
+```
+
+## Discovery insertion checklist
+
+Before submitting AgentPay to a paid-MCP or machine-payment directory, verify:
+
+- npm package name and current version.
+- GitHub repository URL.
+- MCP package identity.
+- Install command and required environment variables.
+- No private key required for `initialize` or `tools/list`.
+- x402-only wording is present.
+- Base/USDC production signing is not broadened into unsupported non-EVM claims.
+- Proof docs are linked for five-tool parity, manifest drift, provider health, quality gates, receipt normalization, and escrow boundary.
+
+## Outreach posture
+
+For Toolstem-style proxies, propose buyer-side approval and receipt guidance, not a partnership claim.
+
+For Cinderwright-style directories, propose adding AgentPay as a buyer-control tool with exact metadata and proof links.
+
+For Dexter-style five-tool flows, propose interoperability language: AgentPay can satisfy the same buyer sequence with local signing and explicit policy checks, while hosted session wallets remain a different trust model.

package/llms.txt

@@ -19,3 +19,7 @@ Important docs:
 - `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
+
+- `docs/agentpay-five-tool-parity-proof.md` and `docs/agentpay-five-tool-parity-proof.json` for search/check/fetch/wallet/pay buyer-flow parity without hosted-session custody
+- `docs/agentpay-escrow-reputation-boundary.md` for separating x402 payment authorization from escrow, identity, reputation, and work proof
+- `docs/paid-mcp-proxy-discovery-readiness.md` and `docs/agentpay-paid-proxy-discovery-listing.json` for paid-proxy and directory listing submissions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentpay-mcp",
-  "version": "4.1.15",
+  "version": "4.1.16",
   "mcpName": "io.github.up2itnow0822/agentpay",
   "description": "AgentPay MCP Server - Non-custodial x402 payment layer for AI agents. Multi-chain wallets, spending limits, and machine-to-machine payments. Patent Pending.",
   "main": "dist/index.js",