agentpay-mcp 4.1.0 → 4.1.4

package/docs/hitl-reference-architecture.md

@@ -0,0 +1,140 @@
+# AgentPay MCP: HITL Reference Architecture for Payment Authorization
+
+> The reference implementation for human-in-the-loop payment workflows in MCP-compatible agents.
+
+## Why HITL Matters
+
+McKinsey's 2026 AI Trust Maturity Survey found that only **14.4% of enterprises formally approve AI agents before deployment**, while **88% report at least one agent security incident**. For payment operations specifically, just **18% of enterprises are confident in their agent IAM**.
+
+The implication is clear: autonomous agent payments without human oversight are a non-starter for enterprise adoption. The question isn't whether HITL is needed — it's how to implement it without destroying the autonomy that makes agents valuable.
+
+## The Pattern: Suggest → Approve → Execute
+
+AgentPay MCP implements a three-phase payment authorization pattern:
+
+```
+Phase 1: SUGGEST
+  Agent encounters a paid API (HTTP 402)
+  AgentPay MCP evaluates spending policy
+  If amount > human_approval_threshold:
+    → Payment is BLOCKED (not executed)
+    → Human receives approval request
+
+Phase 2: APPROVE
+  Human reviews: merchant, amount, context
+  Human decides: approve or reject
+  Decision is logged with timestamp
+
+Phase 3: EXECUTE
+  If approved → payment executes on-chain
+  If rejected → agent receives rejection, adapts
+  Full audit trail recorded regardless
+```
+
+### Code Example: Human-Approval Payment Flow
+
+```python
+from smolagents import CodeAgent, InferenceClientModel
+from smolagents.x402_payment_tool import X402PaymentTool, SpendingPolicy, PaymentMode
+
+# Configure HITL: auto-approve under $1, require human approval above
+payment_tool = X402PaymentTool(
+    spending_policy=SpendingPolicy(
+        mode=PaymentMode.LIVE,
+        max_per_transaction=10.00,
+        rolling_cap=100.00,
+        require_human_approval=True,
+        human_approval_threshold=1.00,
+        merchant_allowlist=["api.example.com", "data.provider.io"],
+    )
+)
+
+agent = CodeAgent(
+    tools=[payment_tool],
+    model=InferenceClientModel(),
+)
+
+# Agent workflow:
+# 1. Agent calls api.example.com → gets HTTP 402 for $0.50
+#    → Auto-approved (under $1 threshold) → paid → data returned
+#
+# 2. Agent calls data.provider.io → gets HTTP 402 for $3.50
+#    → BLOCKED → human sees:
+#      "Agent wants to pay $3.50 to data.provider.io — approve? [y/n]"
+#    → Human approves → paid → data returned
+#    → OR human rejects → agent receives error, tries alternative
+```
+
+### MCP Server Configuration
+
+```json
+{
+  "mcpServers": {
+    "agentpay": {
+      "command": "npx",
+      "args": ["agentpay-mcp"],
+      "env": {
+        "AGENT_PRIVATE_KEY": "0x...",
+        "AGENT_WALLET_ADDRESS": "0x..."
+      }
+    }
+  }
+}
+```
+
+The HITL behavior is configured via `set_spend_policy` tool:
+
+```json
+{
+  "tool": "set_spend_policy",
+  "arguments": {
+    "perTxCapEth": "0.004",
+    "dailyLimitEth": "0.04",
+    "requireHumanApproval": true,
+    "humanApprovalThreshold": "0.0004",
+    "allowedRecipients": ["0x..."]
+  }
+}
+```
+
+## Why This Architecture Works
+
+### 1. Graduated Autonomy
+
+Not every payment needs human review. The threshold model lets agents handle routine micropayments autonomously while escalating significant transactions. This preserves agent utility without sacrificing oversight.
+
+### 2. On-Chain Enforcement
+
+The spending caps aren't in application code — they're in the AgentAccountV2 smart contract. Even if the agent, the MCP server, or the host application is compromised, the on-chain limits hold. The human-approval gate is the last line of defense, not the only one.
+
+### 3. Audit Trail for Compliance
+
+Every payment attempt (approved, rejected, or auto-approved) is logged with:
+- Merchant/recipient address
+- Amount requested
+- Policy evaluation result
+- Human decision (if applicable)
+- On-chain transaction hash (if executed)
+
+This gives compliance teams the artifact trail they need for SOC 2, financial audits, and regulatory reporting.
+
+## MCP 2026 Roadmap Alignment
+
+The MCP specification is evolving toward mandatory security controls for financial operations:
+
+- **CoSAI T9 (Financial Fraud):** AgentPay MCP's HITL pattern directly addresses this threat category
+- **OAuth 2.1 + PKCE:** Enterprise authentication for MCP server access (see [security-posture.md](security-posture.md))
+- **Standardized approval UX:** The `queue_approval` tool provides a consistent interface that MCP clients (Claude Desktop, Cursor, etc.) can render as native approval dialogs
+
+## Production Reference
+
+This HITL payment architecture is already in production:
+
+- **[NVIDIA NeMo Agent Toolkit Examples PR #17](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17)** — x402 payment tool merged into NVIDIA's official agent toolkit catalog
+- **[smolagents PR #2123](https://github.com/huggingface/smolagents/pull/2123)** — Native x402 payment tool with HITL support, addressing community request [#2112](https://github.com/huggingface/smolagents/issues/2112) for human-in-the-loop payment authorization
+
+## Related Documentation
+
+- [Security Posture](security-posture.md) — CoSAI alignment and OAuth 2.1 compliance
+- [README](../README.md) — Full AgentPay MCP documentation
+- [SECURITY.md](../SECURITY.md) — Responsible disclosure process

package/docs/security-posture.md

@@ -0,0 +1,74 @@
+# AgentPay MCP — Security Posture
+
+> Last updated: 2026-03-26
+
+This document maps AgentPay MCP's security controls to the CoSAI (Coalition for Secure AI) threat taxonomy and MCP 2026 authentication requirements. It is intended for enterprise security teams evaluating MCP servers for production deployment.
+
+## CoSAI Threat Alignment
+
+### T9 — Financial Fraud
+
+**Threat:** An AI agent is manipulated (via prompt injection, tool poisoning, or logic error) into making unauthorized payments.
+
+**Mitigations in AgentPay MCP:**
+
+| Control | Implementation | Bypass Resistance |
+|---------|---------------|-------------------|
+| Per-transaction spending cap | `set_spend_policy` enforced by AgentAccountV2 smart contract | On-chain — cannot be overridden by application code or the agent |
+| Rolling period limits | Daily/weekly caps enforced on-chain | Same — smart contract enforcement |
+| Merchant allowlist | Only pre-approved recipient addresses can receive funds | On-chain enforcement |
+| Human-approval gate | Transactions above configurable threshold queue for human review | Cannot be bypassed — `queue_approval` requires explicit human action |
+| Fail-closed policy engine | Any error in policy evaluation → transaction rejected | Default-deny; no silent pass-through |
+| Full audit trail | Every payment attempt logged: merchant, amount, timestamp, approval status, tx hash | Immutable on-chain record |
+
+### T10 — Identity Spoofing
+
+**Threat:** A malicious agent impersonates a legitimate agent to gain access to payment infrastructure or services.
+
+**Mitigations in AgentPay MCP:**
+
+| Control | Implementation |
+|---------|---------------|
+| ERC-8004 identity verification | `verify_agent_identity` tool validates on-chain agent identity NFTs |
+| Non-custodial key management | Agent private key stored locally; never transmitted to any server |
+| On-chain reputation | `get_reputation` provides verifiable transaction history and trust score |
+| Session token verification | x402 session tokens are ECDSA-signed; any verifier can independently validate |
+
+## OAuth 2.1 + PKCE Compliance
+
+MCP 2026 roadmap requires OAuth 2.1 with PKCE for server authentication in enterprise environments.
+
+**Current status:**
+
+- AgentPay MCP supports configuration via environment variables (`AGENT_PRIVATE_KEY`, `AGENT_WALLET_ADDRESS`) for direct deployment
+- For enterprise SSO: Azure AD and Okta can broker OAuth 2.1 tokens that gate access to the MCP server process
+- PKCE flow: supported when deployed behind an OAuth 2.1-compliant reverse proxy (e.g., Azure API Management, Auth0)
+- The MCP server itself authenticates agents via their on-chain identity (ERC-8004) and wallet signature, which provides cryptographic authentication independent of OAuth
+
+**Roadmap:**
+
+- Native OAuth 2.1 token validation in the MCP server transport layer (aligned with MCP spec evolution)
+- Mutual TLS option for server-to-server deployments
+
+## MCP Audit Logging
+
+Every tool invocation is logged with:
+
+- Timestamp (ISO 8601)
+- Tool name and parameters
+- Outcome (success/failure/queued)
+- Transaction hash (for on-chain operations)
+- Policy evaluation result (approved/rejected/queued with reason)
+
+Logs are available via `get_transaction_history` tool and can be exported to enterprise SIEM systems.
+
+## Dependency Security
+
+- **Zero LiteLLM dependency** — no exposure to the March 2026 PyPI supply chain compromise
+- **Minimal npm dependency tree** — `viem`, `@modelcontextprotocol/sdk`, and auditable packages only
+- **No Python runtime required** — eliminates PyPI supply chain attack surface entirely
+- **NVIDIA-validated** — security posture reviewed as part of [NVIDIA NeMo Agent Toolkit Examples PR #17](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17) merge process
+
+## Contact
+
+Security issues: see [SECURITY.md](../SECURITY.md) for responsible disclosure process.

package/docs/trust-architecture.md

@@ -0,0 +1,127 @@
+# AgentPay MCP Trust Architecture
+
+**Simulation Mode · Spend Caps · Human-in-the-Loop · Transaction Explainability**
+
+---
+
+## The Problem: Agent Autonomy Without Trust Infrastructure
+
+Autonomous agents that handle money need more than API keys and wallet addresses. They need a trust architecture — a layered system of controls that lets operators grant autonomy incrementally, verify behavior continuously, and intervene instantly when something goes wrong.
+
+Enterprise solutions like Visa's Visa Intelligent Commerce (VIC) platform address this for traditional payment flows: pre-authorization, fraud scoring, velocity checks, chargeback handling. But VIC is built for card networks and merchant acquirers. It doesn't speak MCP. It doesn't run locally. It doesn't give developers control over the trust model.
+
+AgentPay MCP provides the same trust primitives — simulation, spend controls, human approval, and explainability — in an open-source, developer-native package that runs wherever your agent runs.
+
+---
+
+## Trust Layers
+
+### Layer 1: Simulation Mode
+
+Before any real funds move, agents can dry-run a transaction to preview:
+
+- **Recipient address** and whether it's on the allowlist
+- **Estimated cost** in the payment token (USDC, ETH)
+- **Gas estimate** for the target chain
+- **Policy evaluation result** — would this transaction be auto-approved, queued, or rejected?
+
+Simulation mode gives operators confidence before enabling auto-approve. It's also the right tool for testing new integrations: point your agent at a paid API, see what it would cost, and decide whether to add it to the allowlist — all without spending a cent.
+
+**Comparison:** Visa VIC performs pre-authorization checks server-side through the card network. AgentPay performs simulation locally, with results visible to the agent and operator before any network call.
+
+### Layer 2: Per-Call Spend Caps
+
+Every transaction is evaluated against on-chain spending policy before execution:
+
+- **Per-transaction maximum** — no single call can exceed this amount, regardless of what the agent requests
+- **Enforced by smart contract** — the AgentAccountV2 contract rejects over-cap transactions at the EVM level. Application-layer bugs or agent prompt injection cannot bypass this.
+
+This is the most critical trust boundary. Even if an agent is compromised, jailbroken, or simply wrong about what it's buying, the per-call cap limits blast radius to a known, acceptable amount.
+
+**Comparison:** Visa VIC enforces transaction limits through issuer-configured velocity rules in the card network. AgentPay enforces them on-chain — no intermediary required, publicly auditable, and immutable once set.
+
+### Layer 3: Daily Aggregate Caps
+
+Per-call caps prevent single large losses. Daily caps prevent death by a thousand cuts:
+
+- **Rolling daily limit** — total spend across all transactions resets on a configurable period
+- **On-chain enforcement** — same smart contract, same immutability guarantees
+- **Budget visibility** — agents can call `check_budget` to see remaining allowance before starting expensive workflows
+
+An agent running a 50-item enrichment loop at $0.10 each hits $5.00 total. If the daily cap is $10, the agent knows it has $5 left. If the loop was supposed to be 500 items due to a bug, the cap stops it at 100.
+
+**Comparison:** VIC uses velocity checks (transaction count and amount per time window) configured at the issuer level. AgentPay's daily caps serve the same function, configured by the wallet owner.
+
+### Layer 4: Human-in-the-Loop Approval
+
+Not every transaction should be automatic. AgentPay's HITL system queues transactions that exceed the auto-approve threshold:
+
+- **Threshold-based routing** — under threshold: auto-approved and executed. Over threshold: queued for human review.
+- **Queue inspection** — operators see pending transactions with full context (merchant, amount, tool that triggered it, agent reasoning)
+- **Approve or reject** — explicit human decision. Rejection returns a structured error to the agent, which can adapt (use cached data, try a cheaper source, ask the user).
+- **Fail-closed** — if the approval system errors, the default is rejection. Never approval.
+
+HITL is the default mode. Operators opt *into* automation by raising thresholds, not opt *out* of oversight by lowering them. Trust is earned incrementally.
+
+**Comparison:** Visa VIC routes high-risk transactions to manual review queues via issuer fraud teams. AgentPay routes them to the operator directly — no intermediary, no SLA dependency on a third-party fraud team.
+
+### Layer 5: Transaction Explainability
+
+Every transaction — approved, rejected, queued, or simulated — produces a structured audit record:
+
+- **Timestamp** (block time + local time)
+- **Merchant/recipient** address and resolved name (if available)
+- **Amount** in payment token and USD equivalent
+- **Policy evaluation** — which rule triggered (auto-approve, cap exceeded, allowlist miss)
+- **Approval path** — auto-approved, human-approved, or rejected (with reason)
+- **On-chain transaction hash** — independently verifiable on any block explorer
+
+This isn't just logging. It's the artifact that security teams, compliance officers, and auditors need to answer: "What did this agent spend money on, why, and who approved it?"
+
+**Comparison:** Visa VIC generates transaction records through the card network's settlement process. AgentPay generates them on-chain — immutable, publicly verifiable, and available in real-time (not T+1 or T+2 settlement).
+
+---
+
+## Trust Model Comparison
+
+| Trust Primitive | Visa VIC (Enterprise) | AgentPay MCP (Open Source) |
+|---|---|---|
+| Pre-transaction simulation | Pre-authorization via card network | Local simulation mode, no network call |
+| Per-transaction limits | Issuer-configured velocity rules | On-chain smart contract enforcement |
+| Aggregate spend caps | Velocity checks per time window | On-chain daily caps, agent-queryable |
+| Human review routing | Issuer fraud team queues | Direct operator HITL, fail-closed |
+| Transaction audit trail | Card network settlement records (T+1/T+2) | On-chain, real-time, publicly verifiable |
+| Integration model | Enterprise API + card network onboarding | `npm install` + MCP config |
+| Source availability | Proprietary | MIT open source |
+| Protocol native | Card networks (ISO 8583) | MCP + x402 (HTTP 402) |
+| Agent-native controls | No (designed for human cardholders) | Yes (agents query budget, adapt to rejections) |
+
+---
+
+## Deployment Progression
+
+Trust should be granted incrementally. Here's the recommended progression:
+
+1. **Simulation only** — Agent runs, simulates all payments, logs what it would spend. Zero risk.
+2. **HITL with low threshold** — Auto-approve micro-payments ($0.10), queue everything else. Operator reviews daily.
+3. **HITL with raised threshold** — After reviewing transaction patterns, raise auto-approve to $1-$5. Queue large transactions.
+4. **Full auto with daily cap** — High-confidence workflows get full auto-approve with a daily ceiling. Operator reviews weekly.
+5. **Multi-agent with per-agent caps** — Each agent gets its own wallet with independent caps. Blast radius is isolated per agent.
+
+At no point does the operator lose the ability to intervene. Every stage is reversible by lowering thresholds or enabling simulation mode.
+
+---
+
+## For Enterprise Security Teams
+
+If you're evaluating agent payment infrastructure:
+
+- **Smart contract source** is verified and auditable on-chain
+- **Dependency tree** is minimal — zero LiteLLM, zero Python runtime, auditable with `npm ls`
+- **NVIDIA validation** — integrated into [NVIDIA NeMo Agent Toolkit Examples](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17) (PR #17, merged)
+- **CoSAI alignment** — addresses T9 (Financial Fraud) and T10 (Identity Spoofing) threat categories
+- **Security posture doc** — see [`security-posture.md`](security-posture.md) for the full compliance matrix
+
+---
+
+*AgentPay MCP is MIT licensed. Built by [AI Agent Economy](https://ai-agent-economy.com).*

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.