agentpay-mcp 3.1.0 → 4.0.1

package/README.md

@@ -1,58 +1,104 @@
 # AgentPay MCP
 
-> _Formerly ClawPay MCP_ — Non-custodial x402 payment layer for AI agents. Base (live), Etherlink, Polygon, and Stellar (coming Q2 2026).
-
-[![npm version](https://img.shields.io/npm/v/agentpay-mcp)](https://www.npmjs.com/package/agentpay-mcp)
+[![npm version](https://img.shields.io/npm/v/agentpay-mcp.svg)](https://www.npmjs.com/package/agentpay-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io)
+[![Tests](https://img.shields.io/badge/tests-149%20passing-brightgreen.svg)](tests/)
+[![Patent Pending](https://img.shields.io/badge/patent-pending-orange.svg)](https://uspto.gov)
 
-> **Migration notice:** The npm package has been renamed from `clawpay-mcp` to `agentpay-mcp`. Install with `npm install -g agentpay-mcp`. The old package name will continue to redirect but receives no further updates.
+**The MCP server that lets your agent pay for APIs safely.**
 
----
+When your agent hits HTTP 402 Payment Required, it needs to pay and retry — with your approval, within limits you set. AgentPay MCP is a Model Context Protocol server that gives Claude, Cursor, and any MCP-compatible agent a payment wallet with hard spend caps, human-approval mode, and a full on-chain audit trail.
+
+Payment infrastructure integrated into **[NVIDIA's official NeMo Agent Toolkit Examples](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17)**.
+
+## Why Trust Matters
+
+McKinsey's 2026 AI Trust Maturity Survey quantifies what builders already feel: agent capability has outpaced agent governance.
 
-## What is AgentPay MCP?
+| Finding | Stat |
+|---------|------|
+| Enterprises that formally approve agents before deployment | **14.4%** |
+| Enterprises reporting at least one agent security incident | **88%** |
+| Enterprises confident in agent IAM for payments | **18%** |
 
-AgentPay MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that wraps the [Agent Wallet SDK (`agentwallet-sdk`)](https://www.npmjs.com/package/agentwallet-sdk) — enabling any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, etc.) to make on-chain payments with built-in spend limit enforcement.
+The trust gap is the deployment gap. Enterprises aren't saying agents don't work — they're saying the oversight infrastructure (approval workflows, spending guardrails, identity verification, audit trails) hasn't kept pace.
 
-**Key properties:**
+AgentPay MCP addresses this directly:
 
-- 🔐 **Non-custodial** — You hold your keys. The wallet is a smart contract you own via NFT.
-- 💸 **Spend-limited** — On-chain limits cap what agents can spend per-tx and per-period. Over-limit transactions queue for your approval.
-- ⚡ **x402-native** — Automatic HTTP 402 payment handling (pay-per-API-call, pay-per-token, etc.)
-- 🌐 **Multi-chain** — Base (live), Etherlink, Polygon, Stellar (coming Q2 2026)
+- **Human-approval mode** — transactions above your threshold require explicit human confirmation before executing
+- **On-chain spend caps** — enforced by smart contract, not application code. The agent cannot override them.
+- **Full audit trail** — every payment attempt logged with merchant, amount, timestamp, approval status
+- **Fail-closed** — any policy engine error produces rejection, never approval
+- **Non-custodial** — private keys never leave the local machine
 
-**Part of the [Agent Wallet](https://github.com/up2itnow0822/agent-wallet-sdk) ecosystem.**
+When 88% of enterprises have had an agent security incident, "trust by default" is not a viable architecture. AgentPay MCP is built for "verify, then trust" — which is the only model that scales.
 
 ---
 
-## x402 Multi-Chain Support
+## Security & Dependencies
 
-x402 is live on multiple chains, and AgentPay MCP is designed to be the abstraction layer so your agent doesn't need chain-specific payment code.
+AgentPay MCP is built for enterprise MCP deployments where supply chain security matters.
 
-| Chain | Status | Settlement | Notes |
-|-------|--------|------------|-------|
-| **Base** (Coinbase L2) | ✅ Live | USDC native | Primary chain. Production-ready. |
-| **Etherlink** (Tezos L2) | 🔜 Coming | USDC via bridge | Live on Etherlink since Mar 9, 2026. AgentPay integration in progress. |
-| **Polygon** | 🔜 Coming | USDC native | Agent CLI support live since Mar 8, 2026. AgentPay integration in progress. |
-| **Stellar** | 🔜 Coming | USDC native | x402 support live ~Mar 10, 2026. AgentPay integration in progress. |
-| **Circle Testnet** | 🧪 Testing | USDC (12 chains) | Multi-chain CCTP testnet for cross-chain USDC settlement. |
+- **Zero LiteLLM dependency.** No direct or transitive dependency on LiteLLM or any heavyweight LLM routing layer. When LiteLLM versions 1.82.7-1.82.8 were [compromised on PyPI](https://github.com/berriai/litellm/issues) (March 2026), AgentPay MCP users were unaffected.
+- **Auditable, minimal dependency tree.** The server runs on `viem`, `@modelcontextprotocol/sdk`, and a small set of auditable npm packages. No PyPI. No Python runtime required.
+- **Enterprise trust signal.** Integrated into [NVIDIA's official NeMo Agent Toolkit Examples](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17) (PR #17, merged). NVIDIA's review process validated the security posture before merge.
+- **Non-custodial architecture.** Private keys never leave the local machine. On-chain spend caps enforce limits even if the agent or its key is compromised.
 
-**How multi-chain works with AgentPay MCP:**
+If your security team is auditing MCP server dependencies after the LiteLLM incident, `npm ls` on agentpay-mcp gives you a short, reviewable tree with zero Python supply chain exposure.
 
-Your agent calls `x402_pay` with a URL. The MCP server detects the x402 payment requirements from the HTTP 402 response - including which chain the provider expects payment on. As we add chain support, the agent's integration stays the same: one tool call, automatic chain routing.
+---
 
-```bash
-# Your agent code doesn't change when new chains are added
-x402_pay({ url: "https://api.example.com/data", max_payment_eth: "0.001" })
+## AI Agent Discovery
+
+AgentPay MCP is designed to be discovered and used by AI agents. Compatible with:
+
+- **[claude-mem](https://github.com/thedotmack/claude-mem)** - Payment state (transaction history, budgets, session tokens) persists as agent memory across sessions via claude-mem's observation layer
+- **[AgentSkills](https://agentskills.io)** - Installable as a cross-framework skill in any AgentSkills-compatible harness (Claude Code, Cursor, Gemini CLI, Antigravity)
+- **[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)** - Pairs as the payment layer for browser-native agents
+
+### Install as a Skill
+
+Add to any MCP-compatible harness config:
+
+```json
+{
+  "mcpServers": {
+    "agentpay": {
+      "command": "npx",
+      "args": ["agentpay-mcp"],
+      "env": {
+        "AGENT_PRIVATE_KEY": "0x...",
+        "AGENT_WALLET_ADDRESS": "0x..."
+      }
+    }
+  }
+}
 ```
 
-**Multi-chain roadmap:**
-1. Base - live now
-2. Etherlink - Q2 2026
-3. Polygon - Q2 2026
-4. Stellar - Q2 2026
+Works with Claude Code, Cursor, Gemini CLI, OpenClaw, Windsurf, and any MCP client.
 
-Want a specific chain prioritized? [Open an issue](https://github.com/up2itnow0822/agentpay-mcp/issues).
+---
+
+## The 402 Flow — What This Actually Does
+
+```
+Agent calls a paid API
+        │
+        ▼
+   HTTP 402 ←── "Payment required: 0.50 USDC on Base"
+        │
+        ▼
+AgentPay MCP evaluates your policy:
+  • Is 0.50 USDC under your per-tx cap?  ($5 limit → ✅)
+  • Is this recipient allowlisted?        (api.example.com → ✅)
+  • Require human approval?              (under $1 threshold → auto)
+        │
+        ▼
+  Payment sent → API retried with payment proof → 200 OK
+        │
+        ▼
+Agent gets the data. Full tx on basescan.org.
+```
 
 ---
 
@@ -64,31 +110,36 @@ Want a specific chain prioritized? [Open an issue](https://github.com/up2itnow08
 npm install -g agentpay-mcp
 ```
 
-### 2. Configure environment
-
-Create a `.env` file (or set env vars for your MCP client):
+### 2. Configure Claude Desktop
 
-```bash
-# Required
-AGENT_PRIVATE_KEY=0x...     # Agent hot wallet private key
-AGENT_WALLET_ADDRESS=0x...  # Your deployed AgentAccountV2 address
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
-# Optional (defaults shown)
-CHAIN_ID=8453               # 8453 = Base Mainnet, 84532 = Base Sepolia
-RPC_URL=https://mainnet.base.org
+```json
+{
+  "mcpServers": {
+    "agentpay": {
+      "command": "npx",
+      "args": ["agentpay-mcp"],
+      "env": {
+        "AGENT_PRIVATE_KEY": "0x...",
+        "AGENT_WALLET_ADDRESS": "0x...",
+        "CHAIN_ID": "8453"
+      }
+    }
+  }
+}
 ```
 
-> **Security note:** `AGENT_PRIVATE_KEY` is the agent's *hot wallet* signing key — not the owner key. On-chain spend limits protect your funds. Even if the key is compromised, the agent can only spend within your configured limits.
+### 3. Configure Cursor
 
-### 3. Add to Claude Desktop
-
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "agentpay": {
-      "command": "agentpay-mcp",
+      "command": "npx",
+      "args": ["agentpay-mcp"],
       "env": {
         "AGENT_PRIVATE_KEY": "0x...",
         "AGENT_WALLET_ADDRESS": "0x...",
@@ -99,305 +150,403 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-Then restart Claude Desktop. You'll see the 🔧 AgentPay tools available in your conversation.
-
----
-
-## Tools Reference
+### 4. Set Spend Caps
 
-### 1. `deploy_wallet`
+Once running, tell your agent:
 
-Deploy a new AgentAccountV2 wallet via the factory contract.
+```
+Set my spend policy: $1 per transaction, $10 per day, only send to allowlisted addresses.
+```
 
-**Input:**
+Or call `set_spend_policy` directly:
 
 ```json
 {
-  "token_id": "1",
-  "factory_address": "0x...",
-  "nft_contract_address": "0x..."
+  "tool": "set_spend_policy",
+  "arguments": {
+    "perTxCapEth": "0.0004",
+    "dailyLimitEth": "0.004",
+    "allowedRecipients": ["0xapi-provider-address..."]
+  }
 }
 ```
 
-**Output:**
+Now your agent can pay for APIs — and can't spend more than $1 at a time or $10 in a day, regardless of what it's instructed to do.
 
-```text
-✅ Agent Wallet deployed successfully!
+---
 
-📍 Wallet Address: 0xabc...
-🔗 Explorer: https://basescan.org/address/0xabc...
+## Human-Approval Mode (the Default)
 
-📋 Transaction: 0xdef...
-🔑 Owner NFT: 0xnft... #1
-🌐 Chain: Base Mainnet
+By default, transactions above your auto-approve threshold queue for human review. The agent cannot bypass this.
 
-ℹ️  Next steps:
-  1. Set AGENT_WALLET_ADDRESS=0xabc... in your .env
-  2. Use set_spend_policy to configure spending limits
-  3. Fund the wallet with ETH or USDC
+```
+$0.50 USDC request → under $1 threshold → auto-approved → paid → result returned
+$5.00 USDC request → over $1 threshold → queued → you get notified → approve or reject
 ```
 
----
-
-### 2. `get_wallet_info`
+To approve a queued payment:
 
-Get wallet address, balance, spend limits, and remaining allowance.
+```json
+{
+  "tool": "queue_approval",
+  "arguments": {
+    "action": "approve",
+    "tx_id": "0x..."
+  }
+}
+```
 
-**Input:**
+To reject it:
 
 ```json
 {
-  "token": "0x0000000000000000000000000000000000000000"
+  "tool": "queue_approval",
+  "arguments": {
+    "action": "cancel",
+    "tx_id": "0x..."
+  }
 }
 ```
 
-*`token` is optional — omit for native ETH.*
+The agent sees the outcome and decides what to do next (use cached data, ask user, abort).
 
-**Output:**
+---
+
+## Value Packs — Three Production Workflow Patterns
+
+### 1. Paid API Agent
+
+**What it does:** Finds the right paid API for a data need, pays once, caches the result.
 
-```text
-📊 Agent Wallet Info
+**When to use it:** Your agent needs data (market data, enrichment, geocoding) and you want it to handle payment automatically rather than failing with a 402.
 
-📍 Address: 0xabc...
-🌐 Chain: Base Mainnet
-💰 ETH Balance: 0.5 ETH
+```
+Agent: "I need current options flow data for AAPL"
+  │
+  ├─ Tries free sources → insufficient data
+  ├─ Finds paid API → gets 402 for $0.25 USDC
+  ├─ Checks: $0.25 < $1 cap → auto-approved
+  ├─ Pays with x402_pay → gets data
+  ├─ Caches result at ~/.clawpowers/state/market:AAPL:options
+  └─ Returns data + payment receipt
+```
 
-📈 Spend Limits (ETH)
-  Per-tx limit:  0.01 ETH
-  Period limit:  0.1 ETH
-  Period spent:  0.03 ETH
-  Remaining:     0.07 ETH
-  Utilization:   30% 🟢 Healthy
-  Period length: 24h
-  Resets in:     18h 22m
+**Tools used:** `x402_pay`, `check_spend_limit`, `get_transaction_history`
+
+**Example exchange:**
+```
+User: Get me the options flow for AAPL for the last 7 days.
+
+Agent: Checking free sources... insufficient. Found paid API at data.example.com.
+Cost: $0.25 USDC (under your $1 auto-approve cap). Paying now.
+[x402_pay → 200 OK, paid 0.25 USDC, tx: 0xabc...]
+Here's the options flow data: [results]
+Total cost today: $0.25 of your $10 daily budget.
 ```
 
 ---
 
-### 3. `send_payment`
+### 2. Research Agent
 
-Send ETH or ERC20 tokens within spend limits.
+**What it does:** Gathers from free sources first, fills gaps with paid data, compiles a structured output.
 
-**Input:**
+**When to use it:** You need a comprehensive research report and want the agent to spend money only where free data is genuinely insufficient.
 
-```json
-{
-  "to": "0xrecipient...",
-  "amount_eth": "0.001",
-  "memo": "Payment for API access"
-}
+```
+Agent: "Research competitive landscape for real-time flight tracking APIs"
+  │
+  ├─ Scrapes free sources (GitHub, HN, docs) → baseline data
+  ├─ Identifies gaps: pricing data, SLA guarantees, enterprise contacts
+  ├─ Proposes paid lookups totaling $2.75 USDC → presents for approval
+  ├─ Human approves
+  ├─ Pays for Apollo contact enrichment ($1.50) + Crunchbase data ($1.25)
+  └─ Compiles: free data + paid data → structured report
 ```
 
-For ERC20 (e.g. USDC):
+**Tools used:** `x402_pay`, `x402_session_start`, `x402_session_fetch`, `check_budget`
 
-```json
-{
-  "to": "0xrecipient...",
-  "amount_eth": "5.00",
-  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-  "token_decimals": 6
-}
+**Example exchange:**
 ```
+User: Research the real-time flight tracking API market. Budget up to $5.
 
-**Output:**
+Agent: Starting with free sources... [scrapes 12 sources, builds baseline]
+Gaps identified:
+  - Vendor pricing (not public for 3 of 5 vendors)
+  - Contact info for enterprise sales at FlightAware
+  - Recent funding data for two startups
 
-```text
-✅ Payment Sent
+To fill these I'd spend ~$2.75 USDC:
+  - Apollo contact enrichment: $1.50
+  - Crunchbase firmographics: $1.25
 
-  To:      0xrecipient...
-  Amount:  0.001 ETH
-  Network: Base Mainnet
-  TX Hash: 0xabc...
-  🔗 https://basescan.org/tx/0xabc...
-  📝 Memo: Payment for API access
-```
+Approve? (y/n)
 
-> If the payment exceeds spend limits, it's automatically queued for your approval. Use `queue_approval` to manage the queue.
+User: y
+
+Agent: [pays, fetches, compiles]
+Report ready. Spent $2.75 of your $5 budget. [structured report attached]
+```
 
 ---
 
-### 4. `check_spend_limit`
+### 3. Automation Agent
 
-Check if a proposed payment is within autonomous limits before sending.
+**What it does:** Completes real tasks end-to-end, paying for whatever services are needed along the way.
 
-**Input:**
+**When to use it:** You want an agent that can actually finish work — book a call, run an enrichment pipeline, deploy something — not just research it.
 
-```json
-{
-  "amount_eth": "0.005"
-}
+```
+Agent: "Enrich this list of 50 leads and add to CRM"
+  │
+  ├─ Processes first 10 free (from existing data)
+  ├─ Remaining 40 need enrichment → $0.10/contact = $4.00 USDC
+  ├─ Presents plan: 40 contacts × $0.10 = $4.00 total → user approves
+  ├─ Runs enrichment in batches of 10 (staying under per-tx cap)
+  ├─ Writes enriched data to CRM via API
+  └─ Reports: 50 leads enriched, $4.00 spent, 47 successful
 ```
 
-**Output:**
-
-```text
-🔍 Spend Limit Check
-
-  Token:            ETH
-  Amount:           0.005 ETH
+**Tools used:** `x402_pay`, `x402_session_start`, `set_spend_policy`, `get_transaction_history`
 
-  Per-tx limit:     0.01 ETH
-  Within per-tx:    ✅ Yes
+---
 
-  Remaining period: 0.07 ETH
-  Within period:    ✅ Yes
-  Resets in:        18h 22m
+## Environment Variables
 
-✅ APPROVED — This payment can execute autonomously.
+```bash
+# Required
+AGENT_PRIVATE_KEY=0x...          # Agent hot wallet key (0x-prefixed hex)
+AGENT_WALLET_ADDRESS=0x...       # Deployed AgentAccountV2 contract address
+
+# Optional
+CHAIN_ID=8453                    # 8453 = Base Mainnet (default, recommended)
+RPC_URL=https://mainnet.base.org # Custom RPC (Alchemy/Infura recommended for production)
+SESSION_TTL_SECONDS=3600         # x402 session lifetime (default: 1 hour)
+FACTORY_ADDRESS=0x...            # For deploy_wallet and create_escrow
+NFT_CONTRACT_ADDRESS=0x...       # For deploy_wallet
 ```
 
 ---
 
-### 5. `queue_approval`
+## All 23 Tools
 
-Manage over-limit transactions queued for owner review.
+### Payments & 402 Flow
 
-**List pending:**
+| Tool | What It Does |
+|------|-------------|
+| `x402_pay` | Fetch a URL, automatically pay 402, retry — the core use case |
+| `x402_session_start` | Pay once, get reusable session token for a base URL |
+| `x402_session_fetch` | Make calls within an active session (no new payment) |
+| `x402_session_status` | Inspect active sessions and TTL |
+| `x402_session_end` | Explicitly close a session |
 
-```json
-{ "action": "list" }
-```
+### Wallet & Spend Control
 
-**Approve:**
+| Tool | What It Does |
+|------|-------------|
+| `get_wallet_info` | Address, balances, spend limits, queue depth |
+| `send_payment` | Send ETH or ERC-20 via the AgentAccountV2 contract |
+| `check_spend_limit` | Remaining spend limit for current period |
+| `set_spend_policy` | Configure daily limits, per-tx caps, recipient allowlists |
+| `check_budget` | Query on-chain remaining budget |
+| `queue_approval` | Approve or cancel a queued transaction |
+| `get_transaction_history` | On-chain event logs with filtering |
+| `deploy_wallet` | Deploy a new AgentAccountV2 smart contract wallet |
 
-```json
-{ "action": "approve", "tx_id": "0" }
-```
+### Token Operations
 
-**Cancel:**
+| Tool | What It Does |
+|------|-------------|
+| `lookup_token` | Token address + decimals by symbol and chain |
+| `add_custom_token` | Register a custom ERC-20 in the token registry |
+| `list_chain_tokens` | All registered tokens for a chain |
+| `send_token` | Send any registry token (resolves address + decimals automatically) |
+| `get_balances` | Token balances across one or more tokens |
 
-```json
-{ "action": "cancel", "tx_id": "0" }
-```
+### DeFi
 
----
+| Tool | What It Does |
+|------|-------------|
+| `swap_tokens` | Uniswap V3 swap on Base, Arbitrum, Optimism, or Polygon |
+| `bridge_usdc` | CCTP V2 cross-chain USDC bridge (10 EVM chains, ~12s) |
 
-### 6. `x402_pay`
+### Identity & Trust
 
-Fetch a URL and automatically handle HTTP 402 Payment Required responses.
+| Tool | What It Does |
+|------|-------------|
+| `verify_agent_identity` | ERC-8004 on-chain identity verification |
+| `get_reputation` | On-chain reputation score and history |
+| `create_escrow` | Mutual-stake USDC escrow — both parties lock collateral |
 
-**Input:**
+---
+
+## Key Tool Examples
+
+### `x402_pay` — The Core Tool
 
 ```json
+// Request
 {
-  "url": "https://api.example.com/premium-data",
-  "max_payment_eth": "0.001",
-  "timeout_ms": 15000
+  "tool": "x402_pay",
+  "arguments": {
+    "url": "https://api.example.com/premium-data",
+    "max_payment_eth": "0.0002"
+  }
 }
+
+// Response
+{ "status": 200, "body": "{ ... }" }
 ```
 
----
+If the cost exceeds `max_payment_eth`, the tool returns an error before paying — no surprise charges.
 
-### 7. `get_transaction_history`
+### `x402_session_start` — Pay Once for Multiple Calls
 
-Retrieve on-chain transaction history from event logs.
+```json
+// Request
+{
+  "tool": "x402_session_start",
+  "arguments": {
+    "endpoint": "https://api.example.com/",
+    "ttl_seconds": 3600,
+    "label": "market-data-session"
+  }
+}
 
-**Input:**
+// Response
+{ "session_id": "sess_abc123", "token": "eyJ...", "expires_at": 1741000000 }
+```
 
 ```json
+// Subsequent calls — no new payment
 {
-  "limit": 10,
-  "event_type": "execution"
+  "tool": "x402_session_fetch",
+  "arguments": {
+    "url": "https://api.example.com/stocks/AAPL",
+    "session_id": "sess_abc123"
+  }
 }
 ```
 
----
+### `check_budget` — Know Before You Loop
 
-## Security Model
+```json
+// Request — check before starting an expensive loop
+{ "tool": "check_budget", "arguments": {} }
 
-### Non-Custodial Architecture
+// Response
+{
+  "remaining": "7.50 USDC",
+  "spent": "2.50 USDC",
+  "limit": "10.00 USDC",
+  "periodEnds": "2026-03-24T00:00:00Z"
+}
+```
+
+---
 
-AgentPay MCP wraps **AgentAccountV2** — a smart contract wallet that you own via an NFT. The security model:
+## Supported Chains
 
-1. **You own the NFT** → You own the wallet. If you transfer the NFT, the new holder controls the wallet.
-2. **Agent hot key** → `AGENT_PRIVATE_KEY` is a *limited* operator key. It can execute transactions only within the on-chain spend limits you set.
-3. **On-chain spend limits** → Set via `setSpendPolicy`. Caps per-transaction and per-period spending. Even if the agent key is compromised, the attacker is limited to your configured spend limits.
-4. **Approval queue** → Over-limit transactions are queued on-chain for your explicit approval. The agent cannot bypass this.
+| Chain | Chain ID | Recommended For |
+|-------|----------|----------------|
+| Base Mainnet | 8453 | Everything — lowest gas, most x402 activity |
+| Arbitrum One | 42161 | High-throughput swaps |
+| Optimism | 10 | Low-cost transfers |
+| Polygon | 137 | High-frequency micro-payments |
+| Ethereum Mainnet | 1 | Identity, large settlements |
+| Avalanche | 43114 | Bridge, transfers |
+| Linea / Unichain / Sonic / Worldchain | various | Bridge, transfers |
+| Base Sepolia | 84532 | Testing |
 
-### Threat Model
+---
 
-| Threat | Mitigation |
-|--------|------------|
-| Compromised agent private key | On-chain spend limits cap exposure |
-| Runaway agent (infinite payment loop) | Period limits + queue-on-exceed |
-| x402 price manipulation | `max_payment_eth` cap parameter |
-| Over-spending a single service | x402 per-service budget controls |
-| Lost private key | Owner (NFT holder) remains in control |
+## Security Model
 
-### Isolation Architecture — Why ContextCrush-Style Attacks Don't Apply
+**Non-custodial:** The agent signs all transactions locally with its private key. No third party holds or validates keys.
 
-In March 2026, Noma Security disclosed "ContextCrush" (CVE-2026-31841): MCP servers delivering poisoned documentation into AI coding assistants (Claude Desktop, Cursor, Windsurf, VS Code). The attack injects malicious instructions via the context window, causing the AI to execute destructive commands — including deleting local files.
+**On-chain enforcement:**
+- Per-transaction caps — over-cap transactions queue for human approval via `queue_approval`
+- Daily period limits — aggregate spending enforced by the AgentAccountV2 smart contract
+- Recipient allowlists — restrict which addresses the agent can send to
 
-AgentPay MCP is architecturally immune to this class of attack. Here's why.
+**Role separation:**  
+The agent's signing key (`AGENT_PRIVATE_KEY`) can only transact within limits set by the wallet owner. Even if the agent's key is leaked or the agent is compromised, an attacker can only spend up to the configured cap before the next reset.
 
-**ContextCrush attack vector:**
-- A malicious MCP server (e.g. a documentation provider like Context7) returns poisoned content when the AI queries it
-- That content contains hidden instructions injected into the AI's context window
-- The AI, following what looks like legitimate documentation, executes the attacker's commands
+**x402 sessions:**  
+Session tokens are ECDSA-signed claims. Any x402 V2 server can independently verify them — no central session store required.
 
-**Why AgentPay MCP doesn't have this surface:**
+**Minimal dependency footprint:**  
+AgentPay MCP has **zero LiteLLM dependency**. The entire server runs on `viem` (Ethereum client), `@modelcontextprotocol/sdk`, and a handful of auditable packages — no heavyweight LLM routing layers in the dependency tree. This matters: on March 24, 2026, LiteLLM versions 1.82.7 and 1.82.8 on PyPI were [confirmed compromised](https://github.com/berriai/litellm/issues) in a supply chain attack targeting AI agent infrastructure. Any MCP server that depends on LiteLLM (directly or transitively) was exposed. AgentPay MCP was not — because payment infrastructure should have the smallest possible attack surface.
 
-1. **Payment-only tool surface** — AgentPay MCP exposes exactly 7 tools: `deploy_wallet`, `get_wallet_info`, `send_payment`, `check_spend_limit`, `queue_approval`, `x402_pay`, `get_transaction_history`. It does not fetch or return arbitrary content from external URLs. There is no documentation retrieval pathway, no web browsing tool, no file system access. The attack surface is bounded by the payment domain.
+---
 
-2. **No content pass-through** — ContextCrush works because the compromised MCP server passes external content (poisoned docs) directly into the AI's context. AgentPay MCP only returns structured JSON objects describing payment state and transaction results. It cannot inject arbitrary text into the AI's reasoning context.
+## MCP 2026 Compliance
 
-3. **On-chain enforcement independent of context** — Even if an attacker somehow caused the AI to issue a malicious `send_payment` call, the on-chain spend limits enforce the authorization policy regardless of what the AI believes it's doing. The smart contract validates against the configured `SpendingPolicy` — it doesn't trust the AI's interpretation of the situation.
+AgentPay MCP aligns with the emerging MCP security standards for 2026, including CoSAI (Coalition for Secure AI) threat categories and OAuth 2.1 requirements.
 
-4. **Process isolation** — AgentPay MCP runs as a separate process (`npx agentpay-mcp`). It communicates with the AI client via stdio, not shared memory. It cannot read or write files in your project directory, cannot access your clipboard, cannot execute shell commands. The process has no filesystem permissions beyond reading its own `.env` configuration.
+**Security posture documentation:** See [`docs/security-posture.md`](docs/security-posture.md) for the full compliance matrix covering:
 
-5. **No naming collisions** — CVE-2026-30856 (Tencent WeKnora) exploited tool naming collisions between MCP servers. AgentPay MCP's tool names are payment-specific and unlikely to collide with documentation or utility tools in legitimate agent setups.
+- **CoSAI T9 (Financial Fraud)** — On-chain spend caps, merchant allowlists, and human-approval gates mitigate unauthorized agent spending
+- **CoSAI T10 (Identity Spoofing)** — ERC-8004 agent identity verification + non-custodial key management prevent identity-based attacks
+- **OAuth 2.1 + PKCE** — MCP server authentication supports OAuth 2.1 with PKCE for enterprise SSO integration (Azure AD, Okta)
+- **MCP Audit Logging** — Every tool invocation logged with timestamp, parameters, outcome, and transaction hash (where applicable)
 
-**Summary:** AgentPay MCP cannot be weaponized as a ContextCrush-style vector because it serves no content, accesses no external URLs, writes no files, and executes no shell commands. Its on-chain authorization layer enforces payment policy independently of AI context. Enterprise teams evaluating MCP governance should treat payment-specific, isolated MCP servers differently from general-purpose documentation or utility servers.
+For enterprise security teams evaluating MCP servers: the security posture document provides the artifact your audit process needs.
 
 ---
 
-## Configuration
+## Architecture
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `AGENT_PRIVATE_KEY` | ✅ | — | Agent hot wallet private key (0x-prefixed hex) |
-| `AGENT_WALLET_ADDRESS` | ✅ | — | Deployed AgentAccountV2 contract address |
-| `CHAIN_ID` | ⬜ | `8453` | Chain ID (8453 = Base Mainnet, 84532 = Base Sepolia) |
-| `RPC_URL` | ⬜ | Public Base RPC | Custom RPC endpoint (recommended for production) |
-| `FACTORY_ADDRESS` | ⬜ | — | Required for `deploy_wallet` only |
-| `NFT_CONTRACT_ADDRESS` | ⬜ | — | Required for `deploy_wallet` only |
+```
+┌─────────────────────────────────────────┐
+│  AI Agent (Claude / Cursor / Windsurf)  │
+└────────────────┬────────────────────────┘
+                 │  MCP (stdio / SSE)
+┌────────────────▼────────────────────────┐
+│           AgentPay MCP Server           │
+│  ┌────────────┐  ┌────────────────────┐ │
+│  │  23 Tools  │  │  Session Manager   │ │
+│  └─────┬──────┘  └────────────────────┘ │
+│        │                                │
+│  ┌─────▼──────────────────────────────┐ │
+│  │       agentwallet-sdk v6.0.0       │ │
+│  │  TokenRegistry  SwapModule         │ │
+│  │  BridgeModule   ERC8004Client      │ │
+│  └─────┬──────────────────────────────┘ │
+└────────┼────────────────────────────────┘
+         │  viem + RPC
+┌────────▼────────────────────────────────┐
+│  AgentAccountV2 Smart Contract          │
+│  SpendingPolicy  ·  Tx Queue            │
+│  (12 chains — Base, ETH, ARB, OP, ...)  │
+└─────────────────────────────────────────┘
+```
 
-> **Minimum to get started:** Just `AGENT_PRIVATE_KEY` + `AGENT_WALLET_ADDRESS`. Everything else has sensible defaults.
+Transport: `stdio` by default (Claude Desktop, Cursor, Windsurf). SSE available for remote deployments.
 
 ---
 
-## Integration Examples
+## Contributing
 
-### Cursor / Windsurf
-
-```json
-{
-  "mcpServers": {
-    "agentpay": {
-      "command": "npx",
-      "args": ["-y", "agentpay-mcp"],
-      "env": {
-        "AGENT_PRIVATE_KEY": "0x...",
-        "AGENT_WALLET_ADDRESS": "0x...",
-        "CHAIN_ID": "8453"
-      }
-    }
-  }
-}
+```bash
+git clone https://github.com/up2itnow0822/agentpay-mcp
+cd agentpay-mcp
+npm install
+npm run build
+npm test
 ```
 
 ---
 
-## Ecosystem
+## Patent Notice
 
-- **[Agent Wallet SDK](https://www.npmjs.com/package/agentwallet-sdk)** — Non-custodial wallet SDK for AI agents
-- **[@agent-wallet/mastra-plugin](https://www.npmjs.com/package/@agent-wallet/mastra-plugin)** — Mastra framework integration
-- **[AgentPay MCP](https://www.npmjs.com/package/agentpay-mcp)** — This package (MCP server)
-- **[x402 Protocol](https://x402.org)** — HTTP 402 payment standard
-- **[Base Network](https://base.org)** — L2 chain
+**Patent Pending** — USPTO provisional application filed March 2026: "Non-Custodial Multi-Chain Financial Infrastructure System for Autonomous AI Agents."
+
+We support the open x402 standard. Our filing is defensive — to prevent hostile monopolization of open payment rails, not to restrict builders using open standards.
 
 ---
 
 ## License
 
-MIT — see [LICENSE](LICENSE)
+MIT © [AI Agent Economy](https://ai-agent-economy.com)
+
+Built by **AI Agent Economy** — infrastructure for production agent workflows.