ClawPay MCP — Non-custodial x402 Payment Layer for AI Agents

by up2itnow0822

148 downloads

Not rated

GitHub

Other

About

Non-custodial x402 MCP payment protocol for AI agents. Agents sign locally, no custodial infra. Supports EVM (Base) + Solana, auto-handles HTTP 402 payment flows, on-chain spend limits. Published in Coinbase x402 ecosystem (PR #1381).

Details

Author: up2itnow0822
Downloads: 148
Categories: Other

- 🔐 Non-custodial — you hold your keys via an NFT-owned smart contract wallet.
- 💸 On-chain spend limits cap per-transaction and per-period spending.
- ⚡ x402-native automatic handling of HTTP 402 Payment Required responses.
- 🌐 Operates on Base network (fast, cheap, EVM-compatible).
- 🧩 Fully compatible with any MCP client (Claude Desktop, Cursor, Windsurf, etc.).
- 📋 Over-limit transactions queue for your explicit on-chain approval.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name ClawPay MCP — Non-custodial x402 Payment Layer for AI Agents

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

From the repository

Install globally via npm install -g agentpay-mcp, set environment variables (AGENT_PRIVATE_KEY, AGENT_WALLET_ADDRESS, optionally CHAIN_ID and RPC_URL), and add the server to your MCP client’s configuration (e.g., Claude Desktop’s claude_desktop_config.json). The server exposes tools such as deploy_wallet, send_payment, x402_pay, check_spend_limit, get_wallet_info, queue_approval, and get_transaction_history.

`deploy_wallet`

Deploy a new AgentAccountV2 wallet via the factory contract. The wallet is deterministically addressed (CREATE2) and owned by an NFT. Returns the wallet address and deployment transaction hash. Requires FACTORY_ADDRESS and NFT_CONTRACT_ADDRESS env vars (or pass them as arguments).

`get_wallet_info`

Get comprehensive wallet information including address, on-chain balance, spend limits, remaining period allowance, and queue depth. Use token parameter to check budget for a specific ERC20 (defaults to ETH).

`send_payment`

Send ETH or ERC20 tokens from the Agent Wallet. If the amount is within the configured spend limits, it executes immediately and returns the tx hash. If it exceeds limits, the transaction is queued for owner approval (use queue_approval to manage). Always check spend limits first with check_spend_limit to avoid surprises.

`check_spend_limit`

Check whether a proposed payment amount is within the wallet's autonomous spend limits. Returns a clear yes/no with remaining budget details. Use this before send_payment to avoid surprise queuing.

`queue_approval`

Manage over-limit transactions queued for owner review. Use action="list" to see pending transactions, "approve" to approve one by ID, or "cancel" to cancel one by ID. Approve/cancel require the agent key to have owner privileges.

`x402_pay`

Fetch a URL and automatically handle HTTP 402 Payment Required responses. If an active x402 V2 session covers this URL, the session token is used instead of making a new payment (no on-chain cost). If no session exists, the Agent Wallet pays the required amount and retries. Payment is rejected if it exceeds your wallet's spend limits or the max_payment_eth cap. Powered by the x402 protocol on Base network. Tip: Use x402_session_start to pay once for a session and save on repeated calls.

`get_transaction_history`

Retrieve the wallet's recent on-chain transaction history from event logs. Shows executions, queued transactions, approvals, cancellations, spend policy updates, and operator changes. Filter by event type or block range for targeted queries.

`x402_session_start`

Establish an x402 V2 payment session: make a SINGLE on-chain payment and receive a cryptographically signed session token. All subsequent calls to the same endpoint within the session lifetime use x402_session_fetch — no additional payments required. Agents pay once per session rather than once per API call. Session tokens are signed locally by your wallet key (non-custodial). Returns a session_id you pass to x402_session_fetch for all future calls.

`x402_session_fetch`

Make an HTTP request within an established x402 V2 session — NO payment required. The session token (signed by your wallet) is automatically attached to the request. The server recognises your session and grants access without a new on-chain payment. Requires a session_id from x402_session_start. Returns an error if the session has expired (call x402_session_start again to renew).

`x402_session_status`

Check the status of x402 V2 payment sessions. Without arguments, lists all active sessions with TTL remaining. With a session_id, shows full details for that session including call count, payment info, and the signed session token.

`x402_session_end`

Explicitly close an x402 V2 session before it expires naturally. After calling this, x402_session_fetch will return an error for the closed session. Useful for security hygiene or when you know a session is no longer needed.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "clawpay mcp \u2014 non-custodial x402 payment layer for ai agents": {
            "clawpay-mcp": {
                "command": "npx",
                "args": [
                    "-y",
                    "clawpay-mcp"
                ],
                "env": {
                    "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
                    "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
                    "CHAIN_ID": "8453"
                }
            }
        }
    }
}

McpServers

{
    "clawpay-mcp": {
        "command": "npx",
        "args": [
            "-y",
            "clawpay-mcp"
        ],
        "env": {
            "AGENT_PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
            "AGENT_WALLET_ADDRESS": "<YOUR_WALLET_ADDRESS>",
            "CHAIN_ID": "8453"
        }
    }
}

AgentPay MCP

> _Formerly ClawPay MCP_ — Non-custodial x402 payment layer for AI agents on Base network.

> 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.

---

What is AgentPay MCP?

AgentPay MCP is a Model Context Protocol server that wraps the Agent Wallet SDK (agentwallet-sdk) — enabling any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, etc.) to make on-chain payments with built-in spend limit enforcement.

Key properties:

- 🔐 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.)
- 🌐 Base network — Fast, cheap, EVM-compatible (Mainnet + Sepolia testnet)

Part of the Agent Wallet ecosystem.

---

Quick Start

1. Install

npm install -g agentpay-mcp

2. Configure environment

Create a .env file (or set env vars for your MCP client):

# Required
AGENT_PRIVATE_KEY=0x...     # Agent hot wallet private key
AGENT_WALLET_ADDRESS=0x...  # Your deployed AgentAccountV2 address
Optional (defaults shown)
CHAIN_ID=8453               # 8453 = Base Mainnet, 84532 = Base Sepolia
RPC_URL=https://mainnet.base.org

> 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. Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "AGENT_PRIVATE_KEY": "0x...",
        "AGENT_WALLET_ADDRESS": "0x...",
        "CHAIN_ID": "8453"
      }
    }
  }
}

Then restart Claude Desktop. You'll see the 🔧 AgentPay tools available in your conversation.

---

Tools Reference

1. `deploy_wallet`

Deploy a new AgentAccountV2 wallet via the factory contract.

Input:

{
  "token_id": "1",
  "factory_address": "0x...",
  "nft_contract_address": "0x..."
}

Output:

✅ Agent Wallet deployed successfully! 📍 Wallet Address: 0xabc... 🔗 Explorer: https://basescan.org/address/0xabc... 📋 Transaction: 0xdef... 🔑 Owner NFT: 0xnft... #1 🌐 Chain: Base Mainnet

ℹ️ 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

---

2. `get_wallet_info`

Get wallet address, balance, spend limits, and remaining allowance.

Input:

{
  "token": "0x0000000000000000000000000000000000000000"
}

token is optional — omit for native ETH.

Output:

📊 Agent Wallet Info 📍 Address: 0xabc... 🌐 Chain: Base Mainnet 💰 ETH Balance: 0.5 ETH

📈 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

---

3. `send_payment`

Send ETH or ERC20 tokens within spend limits.

Input:

{
  "to": "0xrecipient...",
  "amount_eth": "0.001",
  "memo": "Payment for API access"
}

For ERC20 (e.g. USDC):

{
  "to": "0xrecipient...",
  "amount_eth": "5.00",
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "token_decimals": 6
}

Output:

✅ Payment Sent

To: 0xrecipient... Amount: 0.001 ETH Network: Base Mainnet TX Hash: 0xabc... 🔗 https://basescan.org/tx/0xabc... 📝 Memo: Payment for API access

> If the payment exceeds spend limits, it's automatically queued for your approval. Use queue_approval to manage the queue.

---

4. `check_spend_limit`

Check if a proposed payment is within autonomous limits before sending.

Input:

{
  "amount_eth": "0.005"
}

Output:

🔍 Spend Limit Check Token: ETH Amount: 0.005 ETH Per-tx limit: 0.01 ETH Within per-tx: ✅ Yes Remaining period: 0.07 ETH Within period: ✅ Yes Resets in: 18h 22m

✅ APPROVED — This payment can execute autonomously.

---

5. `queue_approval`

Manage over-limit transactions queued for owner review.

List pending:

{ "action": "list" }

Approve:

{ "action": "approve", "tx_id": "0" }

Cancel:

{ "action": "cancel", "tx_id": "0" }

---

6. `x402_pay`

Fetch a URL and automatically handle HTTP 402 Payment Required responses.

Input:

{
  "url": "https://api.example.com/premium-data",
  "max_payment_eth": "0.001",
  "timeout_ms": 15000
}

---

7. `get_transaction_history`

Retrieve on-chain transaction history from event logs.

Input:

{
  "limit": 10,
  "event_type": "execution"
}

---

Security Model

Non-Custodial Architecture

AgentPay MCP wraps AgentAccountV2 — a smart contract wallet that you own via an NFT. The security model:

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.

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 |

---

Configuration

| 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 |

> Minimum to get started: Just AGENT_PRIVATE_KEY + AGENT_WALLET_ADDRESS. Everything else has sensible defaults.

---

Integration Examples

Cursor / Windsurf

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "agentpay-mcp"],
      "env": {
        "AGENT_PRIVATE_KEY": "0x...",
        "AGENT_WALLET_ADDRESS": "0x...",
        "CHAIN_ID": "8453"
      }
    }
  }
}

---

Ecosystem

- Agent Wallet SDK — Non-custodial wallet SDK for AI agents
- @agent-wallet/mastra-plugin — Mastra framework integration
- AgentPay MCP — This package (MCP server)
- x402 Protocol — HTTP 402 payment standard
- Base Network — L2 chain

---

License

MIT — see LICENSE

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

deploy_wallet

get_wallet_info

send_payment

check_spend_limit

queue_approval

x402_pay

get_transaction_history

x402_session_start

x402_session_fetch

x402_session_status

x402_session_end

Claude Desktop / Cursor

McpServers

AgentPay MCP

What is AgentPay MCP?

Quick Start

1. Install

2. Configure environment

Optional (defaults shown)

3. Add to Claude Desktop

Tools Reference

1. deploy_wallet

2. get_wallet_info

3. send_payment

4. check_spend_limit

5. queue_approval

6. x402_pay

7. get_transaction_history

Security Model

Non-Custodial Architecture

Threat Model

Configuration

Integration Examples

Cursor / Windsurf

Ecosystem

License

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀

`deploy_wallet`

`get_wallet_info`

`send_payment`

`check_spend_limit`

`queue_approval`

`x402_pay`

`get_transaction_history`

`x402_session_start`

`x402_session_fetch`

`x402_session_status`

`x402_session_end`

1. `deploy_wallet`

2. `get_wallet_info`

3. `send_payment`

4. `check_spend_limit`

5. `queue_approval`

6. `x402_pay`

7. `get_transaction_history`