agentpay-mcp 4.0.0 → 4.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +375 -513
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -5,69 +5,132 @@
|
|
|
5
5
|
[](tests/)
|
|
6
6
|
[](https://uspto.gov)
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
**The MCP server that lets your agent pay for APIs safely.**
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
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.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Payment infrastructure integrated into **[NVIDIA's official NeMo Agent Toolkit Examples](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17)**.
|
|
13
|
+
|
|
14
|
+
## Why Trust Matters
|
|
15
|
+
|
|
16
|
+
McKinsey's 2026 AI Trust Maturity Survey quantifies what builders already feel: agent capability has outpaced agent governance.
|
|
17
|
+
|
|
18
|
+
| Finding | Stat |
|
|
19
|
+
|---------|------|
|
|
20
|
+
| Enterprises that formally approve agents before deployment | **14.4%** |
|
|
21
|
+
| Enterprises reporting at least one agent security incident | **88%** |
|
|
22
|
+
| Enterprises confident in agent IAM for payments | **18%** |
|
|
23
|
+
|
|
24
|
+
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.
|
|
25
|
+
|
|
26
|
+
AgentPay MCP addresses this directly:
|
|
27
|
+
|
|
28
|
+
- **Human-approval mode** — transactions above your threshold require explicit human confirmation before executing
|
|
29
|
+
- **On-chain spend caps** — enforced by smart contract, not application code. The agent cannot override them.
|
|
30
|
+
- **Full audit trail** — every payment attempt logged with merchant, amount, timestamp, approval status
|
|
31
|
+
- **Fail-closed** — any policy engine error produces rejection, never approval
|
|
32
|
+
- **Non-custodial** — private keys never leave the local machine
|
|
33
|
+
|
|
34
|
+
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.
|
|
13
35
|
|
|
14
36
|
---
|
|
15
37
|
|
|
16
|
-
##
|
|
38
|
+
## Why Cost Governance Matters for MCP Agents
|
|
39
|
+
|
|
40
|
+
The Model Context Protocol gives agents access to powerful tools — but the protocol itself has no built-in mechanism for controlling what those tools cost. This isn't a theoretical gap. WorkOS's 2026 guide to MCP security explicitly identifies **rate limiting, cost attribution, and per-call spend caps** as unsolved problems at the MCP protocol level. Every MCP server can charge. No MCP client enforces budgets.
|
|
17
41
|
|
|
18
|
-
|
|
42
|
+
The result: an agent with access to 10 MCP servers can accumulate unbounded costs across sessions, with no standard way to attribute spend per tool, cap exposure per call, or halt runaway loops before they drain a wallet.
|
|
19
43
|
|
|
20
|
-
|
|
44
|
+
AgentPay MCP closes this gap at the infrastructure layer:
|
|
45
|
+
|
|
46
|
+
| MCP Cost Governance Gap | AgentPay MCP Solution |
|
|
21
47
|
|---|---|
|
|
22
|
-
|
|
|
23
|
-
|
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
Other highlights:
|
|
30
|
-
- **12 supported chains** — Base, Ethereum, Arbitrum, Optimism, Polygon, Avalanche, Linea, Unichain, Sonic, Worldchain, Base Sepolia, Arbitrum Sepolia
|
|
31
|
-
- **100+ pre-loaded tokens** via TokenRegistry
|
|
32
|
-
- **CCTP V2** cross-chain USDC bridging (10 EVM chains)
|
|
33
|
-
- **Uniswap V3** swaps on Base, Arbitrum, Optimism, Polygon
|
|
34
|
-
- **ERC-8004** on-chain agent identity verification
|
|
35
|
-
- 42 new tests (149 total), 99.6% type coverage
|
|
48
|
+
| No per-call spend caps in the MCP spec | **On-chain per-transaction caps** — enforced by smart contract, not application logic |
|
|
49
|
+
| No cost attribution across MCP servers | **Full transaction history** with merchant, amount, timestamp, and tool context per call |
|
|
50
|
+
| No rate limiting for paid tool invocations | **Daily aggregate spend limits** — hard ceiling regardless of how many tools or sessions run |
|
|
51
|
+
| No human oversight mechanism in the protocol | **Human-in-the-loop approval** — transactions above threshold queue for explicit human review |
|
|
52
|
+
| No simulation/dry-run for cost estimation | **Simulation mode** — preview transaction cost and recipient before committing funds |
|
|
53
|
+
|
|
54
|
+
If you're building agents that interact with paid APIs, MCP spend limits and MCP cost governance aren't optional — they're the difference between a demo and a production deployment. AgentPay MCP is the open-source reference implementation for solving this at the protocol's edge.
|
|
36
55
|
|
|
37
56
|
---
|
|
38
57
|
|
|
39
|
-
##
|
|
58
|
+
## Security & Dependencies
|
|
40
59
|
|
|
41
|
-
|
|
60
|
+
AgentPay MCP is built for enterprise MCP deployments where supply chain security matters.
|
|
42
61
|
|
|
43
|
-
|
|
44
|
-
npm
|
|
45
|
-
|
|
62
|
+
- **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.
|
|
63
|
+
- **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.
|
|
64
|
+
- **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.
|
|
65
|
+
- **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.
|
|
46
66
|
|
|
47
|
-
|
|
67
|
+
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.
|
|
48
68
|
|
|
49
|
-
|
|
69
|
+
---
|
|
50
70
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
71
|
+
## AI Agent Discovery
|
|
72
|
+
|
|
73
|
+
AgentPay MCP is designed to be discovered and used by AI agents. Compatible with:
|
|
74
|
+
|
|
75
|
+
- **[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
|
|
76
|
+
- **[AgentSkills](https://agentskills.io)** - Installable as a cross-framework skill in any AgentSkills-compatible harness (Claude Code, Cursor, Gemini CLI, Antigravity)
|
|
77
|
+
- **[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)** - Pairs as the payment layer for browser-native agents
|
|
78
|
+
|
|
79
|
+
### Install as a Skill
|
|
80
|
+
|
|
81
|
+
Add to any MCP-compatible harness config:
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"mcpServers": {
|
|
86
|
+
"agentpay": {
|
|
87
|
+
"command": "npx",
|
|
88
|
+
"args": ["agentpay-mcp"],
|
|
89
|
+
"env": {
|
|
90
|
+
"AGENT_PRIVATE_KEY": "0x...",
|
|
91
|
+
"AGENT_WALLET_ADDRESS": "0x..."
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
55
97
|
|
|
56
|
-
|
|
57
|
-
CHAIN_ID=8453 # 8453 = Base Mainnet (default)
|
|
58
|
-
RPC_URL=https://mainnet.base.org # Custom RPC URL
|
|
98
|
+
Works with Claude Code, Cursor, Gemini CLI, OpenClaw, Windsurf, and any MCP client.
|
|
59
99
|
|
|
60
|
-
|
|
61
|
-
SESSION_TTL_SECONDS=3600 # Session lifetime (default: 1 hour)
|
|
100
|
+
---
|
|
62
101
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
102
|
+
## The 402 Flow — What This Actually Does
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
Agent calls a paid API
|
|
106
|
+
│
|
|
107
|
+
▼
|
|
108
|
+
HTTP 402 ←── "Payment required: 0.50 USDC on Base"
|
|
109
|
+
│
|
|
110
|
+
▼
|
|
111
|
+
AgentPay MCP evaluates your policy:
|
|
112
|
+
• Is 0.50 USDC under your per-tx cap? ($5 limit → ✅)
|
|
113
|
+
• Is this recipient allowlisted? (api.example.com → ✅)
|
|
114
|
+
• Require human approval? (under $1 threshold → auto)
|
|
115
|
+
│
|
|
116
|
+
▼
|
|
117
|
+
Payment sent → API retried with payment proof → 200 OK
|
|
118
|
+
│
|
|
119
|
+
▼
|
|
120
|
+
Agent gets the data. Full tx on basescan.org.
|
|
66
121
|
```
|
|
67
122
|
|
|
68
|
-
|
|
123
|
+
---
|
|
69
124
|
|
|
70
|
-
|
|
125
|
+
## Quick Start
|
|
126
|
+
|
|
127
|
+
### 1. Install
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
npm install -g agentpay-mcp
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### 2. Configure Claude Desktop
|
|
71
134
|
|
|
72
135
|
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
73
136
|
|
|
@@ -87,9 +150,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
|
87
150
|
}
|
|
88
151
|
```
|
|
89
152
|
|
|
90
|
-
|
|
153
|
+
### 3. Configure Cursor
|
|
91
154
|
|
|
92
|
-
Add to `.cursor/mcp.json`
|
|
155
|
+
Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
|
|
93
156
|
|
|
94
157
|
```json
|
|
95
158
|
{
|
|
@@ -107,585 +170,347 @@ Add to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:
|
|
|
107
170
|
}
|
|
108
171
|
```
|
|
109
172
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
## All 23 Tools Reference
|
|
113
|
-
|
|
114
|
-
### Original Tools (v1.0.0–v3.1.0)
|
|
115
|
-
|
|
116
|
-
| Tool | Description | Key Parameters |
|
|
117
|
-
|---|---|---|
|
|
118
|
-
| `deploy_wallet` | Deploy a new AgentAccountV2 wallet via factory | `token_id`, `nft_contract_address?`, `factory_address?` |
|
|
119
|
-
| `get_wallet_info` | Wallet address, balances, spend limits, queue depth | `token?` (address) |
|
|
120
|
-
| `send_payment` | Send ETH or ERC-20 via AgentAccountV2 contract | `to`, `amount_eth`, `token?`, `token_decimals?`, `memo?` |
|
|
121
|
-
| `check_spend_limit` | Check remaining spend limit for a token | `token?` |
|
|
122
|
-
| `queue_approval` | Approve or cancel a queued transaction | `action`, `tx_id`, `token?` |
|
|
123
|
-
| `x402_pay` | Auto-pay x402 paywalled URLs | `url`, `method?`, `headers?`, `body?`, `max_payment_eth?` |
|
|
124
|
-
| `get_transaction_history` | Query on-chain event logs | `limit?`, `from_block?`, `to_block?`, `event_type?` |
|
|
125
|
-
| `x402_session_start` | Pay once, get reusable session token | `endpoint`, `scope?`, `ttl_seconds?`, `label?` |
|
|
126
|
-
| `x402_session_fetch` | Make calls within an active session | `url`, `method?`, `headers?`, `body?`, `session_id?` |
|
|
127
|
-
| `x402_session_status` | Inspect active sessions and TTL | `session_id?` |
|
|
128
|
-
| `x402_session_end` | Explicitly close a session | `session_id` |
|
|
129
|
-
|
|
130
|
-
### New Tools (v4.0.0)
|
|
131
|
-
|
|
132
|
-
| Tool | Description | Key Parameters |
|
|
133
|
-
|---|---|---|
|
|
134
|
-
| `lookup_token` | Look up token address and decimals by symbol | `symbol`, `chainId` |
|
|
135
|
-
| `add_custom_token` | Register a custom ERC-20 in the token registry | `symbol`, `address`, `decimals`, `chainId`, `name?` |
|
|
136
|
-
| `list_chain_tokens` | List all registered tokens for a chain | `chainId` |
|
|
137
|
-
| `send_token` | Send any registry token to a recipient | `tokenSymbol`, `chainId`, `recipientAddress`, `amount` |
|
|
138
|
-
| `get_balances` | Get balances for multiple tokens | `chainId`, `tokens?` |
|
|
139
|
-
| `swap_tokens` | Swap tokens via Uniswap V3 | `fromSymbol`, `toSymbol`, `amount`, `chainId`, `slippageBps?` |
|
|
140
|
-
| `bridge_usdc` | Bridge USDC cross-chain via CCTP V2 | `fromChain`, `toChain`, `amount` |
|
|
141
|
-
| `set_spend_policy` | Configure daily limits and recipient allowlists | `dailyLimitEth?`, `perTxCapEth?`, `allowedRecipients?` |
|
|
142
|
-
| `check_budget` | Query on-chain remaining budget | `token?`, `spender?` |
|
|
143
|
-
| `verify_agent_identity` | Verify agent ERC-8004 on-chain identity | `agentAddress` |
|
|
144
|
-
| `get_reputation` | Fetch agent reputation score | `agentAddress` |
|
|
145
|
-
| `create_escrow` | Create mutual-stake USDC escrow vault | `counterpartyAddress`, `stakeAmount`, `terms`, `factoryAddress?`, `deadlineDays?`, `challengeWindowHours?` |
|
|
146
|
-
|
|
147
|
-
---
|
|
148
|
-
|
|
149
|
-
## Detailed Tool Documentation
|
|
173
|
+
### 4. Set Spend Caps
|
|
150
174
|
|
|
151
|
-
|
|
175
|
+
Once running, tell your agent:
|
|
152
176
|
|
|
153
|
-
|
|
177
|
+
```
|
|
178
|
+
Set my spend policy: $1 per transaction, $10 per day, only send to allowlisted addresses.
|
|
179
|
+
```
|
|
154
180
|
|
|
155
|
-
|
|
156
|
-
| Name | Type | Required | Description |
|
|
157
|
-
|---|---|---|---|
|
|
158
|
-
| `token_id` | string | ✅ | NFT token ID that will own the wallet (e.g. `"1"`) |
|
|
159
|
-
| `nft_contract_address` | string | ❌ | NFT contract address (defaults to `NFT_CONTRACT_ADDRESS` env) |
|
|
160
|
-
| `factory_address` | string | ❌ | Factory contract address (defaults to `FACTORY_ADDRESS` env) |
|
|
181
|
+
Or call `set_spend_policy` directly:
|
|
161
182
|
|
|
162
|
-
**Example:**
|
|
163
183
|
```json
|
|
164
|
-
// Request
|
|
165
|
-
{ "token_id": "42" }
|
|
166
|
-
|
|
167
|
-
// Response
|
|
168
184
|
{
|
|
169
|
-
"
|
|
170
|
-
"
|
|
171
|
-
|
|
185
|
+
"tool": "set_spend_policy",
|
|
186
|
+
"arguments": {
|
|
187
|
+
"perTxCapEth": "0.0004",
|
|
188
|
+
"dailyLimitEth": "0.004",
|
|
189
|
+
"allowedRecipients": ["0xapi-provider-address..."]
|
|
190
|
+
}
|
|
172
191
|
}
|
|
173
192
|
```
|
|
174
193
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
### `get_wallet_info`
|
|
178
|
-
|
|
179
|
-
Get comprehensive wallet information: address, on-chain balance, spend limits, period utilization, and pending queue depth.
|
|
180
|
-
|
|
181
|
-
**Parameters:**
|
|
182
|
-
| Name | Type | Required | Description |
|
|
183
|
-
|---|---|---|---|
|
|
184
|
-
| `token` | string | ❌ | Token address to check budget for. Omit for ETH. |
|
|
185
|
-
|
|
186
|
-
**Example:**
|
|
187
|
-
```json
|
|
188
|
-
// Request
|
|
189
|
-
{}
|
|
190
|
-
|
|
191
|
-
// Response (text)
|
|
192
|
-
"📊 Agent Wallet Info
|
|
193
|
-
📍 Address: 0xabc...def
|
|
194
|
-
🌐 Chain: Base Mainnet
|
|
195
|
-
💰 ETH Balance: 0.05 ETH
|
|
196
|
-
📈 Spend Limits (ETH)
|
|
197
|
-
Per-tx limit: 0.01 ETH
|
|
198
|
-
Period limit: 0.1 ETH
|
|
199
|
-
Remaining: 0.085 ETH
|
|
200
|
-
Utilization: 15% 🟢"
|
|
201
|
-
```
|
|
194
|
+
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.
|
|
202
195
|
|
|
203
196
|
---
|
|
204
197
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
Execute an ETH or ERC-20 transfer via the AgentAccountV2 contract. Subject to on-chain spend limits.
|
|
198
|
+
## Human-Approval Mode (the Default)
|
|
208
199
|
|
|
209
|
-
|
|
210
|
-
| Name | Type | Required | Description |
|
|
211
|
-
|---|---|---|---|
|
|
212
|
-
| `to` | string | ✅ | Recipient address (0x-prefixed) |
|
|
213
|
-
| `amount_eth` | string | ✅ | Amount in ETH (or token's human-readable units) |
|
|
214
|
-
| `token` | string | ❌ | ERC-20 contract address. Omit for native ETH. |
|
|
215
|
-
| `token_decimals` | number | ❌ | Token decimals (default: 18; use 6 for USDC) |
|
|
216
|
-
| `memo` | string | ❌ | Optional memo (logged locally, not on-chain) |
|
|
200
|
+
By default, transactions above your auto-approve threshold queue for human review. The agent cannot bypass this.
|
|
217
201
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
{ "to": "0xrecipient...", "amount_eth": "0.01" }
|
|
222
|
-
|
|
223
|
-
// Response
|
|
224
|
-
"✅ Payment sent: 0.01 ETH → 0xrecipient...
|
|
225
|
-
Tx: 0xtxhash..."
|
|
202
|
+
```
|
|
203
|
+
$0.50 USDC request → under $1 threshold → auto-approved → paid → result returned
|
|
204
|
+
$5.00 USDC request → over $1 threshold → queued → you get notified → approve or reject
|
|
226
205
|
```
|
|
227
206
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
### `check_spend_limit`
|
|
231
|
-
|
|
232
|
-
Check the remaining spend limit for the current period for a given token.
|
|
233
|
-
|
|
234
|
-
**Parameters:**
|
|
235
|
-
| Name | Type | Required | Description |
|
|
236
|
-
|---|---|---|---|
|
|
237
|
-
| `token` | string | ❌ | Token address (omit for ETH) |
|
|
238
|
-
|
|
239
|
-
---
|
|
240
|
-
|
|
241
|
-
### `queue_approval`
|
|
242
|
-
|
|
243
|
-
Approve or cancel a queued transaction that exceeded the per-tx cap.
|
|
244
|
-
|
|
245
|
-
**Parameters:**
|
|
246
|
-
| Name | Type | Required | Description |
|
|
247
|
-
|---|---|---|---|
|
|
248
|
-
| `action` | string | ✅ | `"approve"` or `"cancel"` |
|
|
249
|
-
| `tx_id` | string | ✅ | Queued transaction ID |
|
|
250
|
-
| `token` | string | ❌ | Token address (omit for ETH) |
|
|
251
|
-
|
|
252
|
-
---
|
|
253
|
-
|
|
254
|
-
### `x402_pay`
|
|
255
|
-
|
|
256
|
-
Fetch a URL, automatically handling HTTP 402 Payment Required by paying with the Agent Wallet and retrying. Supports auto-session detection — if an active session covers the URL, no new payment is made.
|
|
257
|
-
|
|
258
|
-
**Parameters:**
|
|
259
|
-
| Name | Type | Required | Description |
|
|
260
|
-
|---|---|---|---|
|
|
261
|
-
| `url` | string | ✅ | URL to fetch |
|
|
262
|
-
| `method` | string | ❌ | HTTP method (default: `GET`) |
|
|
263
|
-
| `headers` | object | ❌ | Additional request headers |
|
|
264
|
-
| `body` | string | ❌ | Request body (JSON string for JSON APIs) |
|
|
265
|
-
| `max_payment_eth` | string | ❌ | Max ETH to pay (rejects if exceeded) |
|
|
266
|
-
| `timeout_ms` | number | ❌ | Timeout in ms (default: 30000) |
|
|
267
|
-
| `skip_session_check` | boolean | ❌ | Force fresh payment even if session exists |
|
|
207
|
+
To approve a queued payment:
|
|
268
208
|
|
|
269
|
-
**Example:**
|
|
270
209
|
```json
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
210
|
+
{
|
|
211
|
+
"tool": "queue_approval",
|
|
212
|
+
"arguments": {
|
|
213
|
+
"action": "approve",
|
|
214
|
+
"tx_id": "0x..."
|
|
215
|
+
}
|
|
216
|
+
}
|
|
276
217
|
```
|
|
277
218
|
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
### `get_transaction_history`
|
|
281
|
-
|
|
282
|
-
Query on-chain event logs for the wallet's transaction history. Filter by event type or block range.
|
|
283
|
-
|
|
284
|
-
**Parameters:**
|
|
285
|
-
| Name | Type | Required | Description |
|
|
286
|
-
|---|---|---|---|
|
|
287
|
-
| `limit` | number | ❌ | Max entries (default: 20, max: 100) |
|
|
288
|
-
| `from_block` | string | ❌ | Start block number (hex or decimal) |
|
|
289
|
-
| `to_block` | string | ❌ | End block (default: latest) |
|
|
290
|
-
| `event_type` | string | ❌ | Filter: `all`, `execution`, `queued`, `approved`, `cancelled`, `policy_update`, `operator_update` |
|
|
291
|
-
|
|
292
|
-
---
|
|
293
|
-
|
|
294
|
-
### `x402_session_start`
|
|
295
|
-
|
|
296
|
-
Pay once, receive a signed x402 V2 session token. Subsequent requests to the endpoint use the session token without additional payments.
|
|
219
|
+
To reject it:
|
|
297
220
|
|
|
298
|
-
**Parameters:**
|
|
299
|
-
| Name | Type | Required | Description |
|
|
300
|
-
|---|---|---|---|
|
|
301
|
-
| `endpoint` | string | ✅ | Base URL to establish a session for |
|
|
302
|
-
| `scope` | string | ❌ | `"prefix"` (default) or `"exact"` |
|
|
303
|
-
| `ttl_seconds` | number | ❌ | Session lifetime in seconds (min: 60, max: 2592000) |
|
|
304
|
-
| `label` | string | ❌ | Human-readable session label |
|
|
305
|
-
|
|
306
|
-
**Example:**
|
|
307
221
|
```json
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
222
|
+
{
|
|
223
|
+
"tool": "queue_approval",
|
|
224
|
+
"arguments": {
|
|
225
|
+
"action": "cancel",
|
|
226
|
+
"tx_id": "0x..."
|
|
227
|
+
}
|
|
228
|
+
}
|
|
313
229
|
```
|
|
314
230
|
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
### `x402_session_fetch`
|
|
318
|
-
|
|
319
|
-
Make an HTTP call within an active session. No new payment required.
|
|
320
|
-
|
|
321
|
-
**Parameters:**
|
|
322
|
-
| Name | Type | Required | Description |
|
|
323
|
-
|---|---|---|---|
|
|
324
|
-
| `url` | string | ✅ | URL to fetch within the session |
|
|
325
|
-
| `method` | string | ❌ | HTTP method (default: `GET`) |
|
|
326
|
-
| `headers` | object | ❌ | Additional headers |
|
|
327
|
-
| `body` | string | ❌ | Request body |
|
|
328
|
-
| `session_id` | string | ❌ | Explicit session ID (auto-detected if omitted) |
|
|
231
|
+
The agent sees the outcome and decides what to do next (use cached data, ask user, abort).
|
|
329
232
|
|
|
330
233
|
---
|
|
331
234
|
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
Inspect active sessions, TTL remaining, and call counts.
|
|
235
|
+
## Value Packs — Three Production Workflow Patterns
|
|
335
236
|
|
|
336
|
-
|
|
337
|
-
| Name | Type | Required | Description |
|
|
338
|
-
|---|---|---|---|
|
|
339
|
-
| `session_id` | string | ❌ | Specific session to inspect (omit for all active sessions) |
|
|
237
|
+
### 1. Paid API Agent
|
|
340
238
|
|
|
341
|
-
|
|
239
|
+
**What it does:** Finds the right paid API for a data need, pays once, caches the result.
|
|
342
240
|
|
|
343
|
-
|
|
241
|
+
**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.
|
|
344
242
|
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
Look up a token's address, decimals, and metadata from the global token registry by symbol and chain.
|
|
243
|
+
```
|
|
244
|
+
Agent: "I need current options flow data for AAPL"
|
|
245
|
+
│
|
|
246
|
+
├─ Tries free sources → insufficient data
|
|
247
|
+
├─ Finds paid API → gets 402 for $0.25 USDC
|
|
248
|
+
├─ Checks: $0.25 < $1 cap → auto-approved
|
|
249
|
+
├─ Pays with x402_pay → gets data
|
|
250
|
+
├─ Caches result at ~/.clawpowers/state/market:AAPL:options
|
|
251
|
+
└─ Returns data + payment receipt
|
|
252
|
+
```
|
|
357
253
|
|
|
358
|
-
**
|
|
359
|
-
| Name | Type | Required | Description |
|
|
360
|
-
|---|---|---|---|
|
|
361
|
-
| `symbol` | string | ✅ | Token symbol (e.g. `"USDC"`, `"WETH"`) |
|
|
362
|
-
| `chainId` | number | ✅ | Chain ID (e.g. `8453` for Base Mainnet) |
|
|
254
|
+
**Tools used:** `x402_pay`, `check_spend_limit`, `get_transaction_history`
|
|
363
255
|
|
|
364
|
-
**Example:**
|
|
365
|
-
```
|
|
366
|
-
|
|
367
|
-
{ "symbol": "USDC", "chainId": 8453 }
|
|
256
|
+
**Example exchange:**
|
|
257
|
+
```
|
|
258
|
+
User: Get me the options flow for AAPL for the last 7 days.
|
|
368
259
|
|
|
369
|
-
|
|
370
|
-
|
|
260
|
+
Agent: Checking free sources... insufficient. Found paid API at data.example.com.
|
|
261
|
+
Cost: $0.25 USDC (under your $1 auto-approve cap). Paying now.
|
|
262
|
+
[x402_pay → 200 OK, paid 0.25 USDC, tx: 0xabc...]
|
|
263
|
+
Here's the options flow data: [results]
|
|
264
|
+
Total cost today: $0.25 of your $10 daily budget.
|
|
371
265
|
```
|
|
372
266
|
|
|
373
267
|
---
|
|
374
268
|
|
|
375
|
-
###
|
|
269
|
+
### 2. Research Agent
|
|
376
270
|
|
|
377
|
-
|
|
271
|
+
**What it does:** Gathers from free sources first, fills gaps with paid data, compiles a structured output.
|
|
378
272
|
|
|
379
|
-
**
|
|
380
|
-
| Name | Type | Required | Description |
|
|
381
|
-
|---|---|---|---|
|
|
382
|
-
| `symbol` | string | ✅ | Token symbol |
|
|
383
|
-
| `address` | string | ✅ | Contract address (0x-prefixed) |
|
|
384
|
-
| `decimals` | number | ✅ | Token decimal precision (0–18) |
|
|
385
|
-
| `chainId` | number | ✅ | Chain ID |
|
|
386
|
-
| `name` | string | ❌ | Human-readable token name |
|
|
273
|
+
**When to use it:** You need a comprehensive research report and want the agent to spend money only where free data is genuinely insufficient.
|
|
387
274
|
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
275
|
+
```
|
|
276
|
+
Agent: "Research competitive landscape for real-time flight tracking APIs"
|
|
277
|
+
│
|
|
278
|
+
├─ Scrapes free sources (GitHub, HN, docs) → baseline data
|
|
279
|
+
├─ Identifies gaps: pricing data, SLA guarantees, enterprise contacts
|
|
280
|
+
├─ Proposes paid lookups totaling $2.75 USDC → presents for approval
|
|
281
|
+
├─ Human approves
|
|
282
|
+
├─ Pays for Apollo contact enrichment ($1.50) + Crunchbase data ($1.25)
|
|
283
|
+
└─ Compiles: free data + paid data → structured report
|
|
395
284
|
```
|
|
396
285
|
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
### `list_chain_tokens`
|
|
400
|
-
|
|
401
|
-
List all tokens registered in the global registry for a specific chain.
|
|
402
|
-
|
|
403
|
-
**Parameters:**
|
|
404
|
-
| Name | Type | Required | Description |
|
|
405
|
-
|---|---|---|---|
|
|
406
|
-
| `chainId` | number | ✅ | Chain ID (e.g. `8453`) |
|
|
407
|
-
|
|
408
|
-
**Example:**
|
|
409
|
-
```json
|
|
410
|
-
// Request
|
|
411
|
-
{ "chainId": 8453 }
|
|
286
|
+
**Tools used:** `x402_pay`, `x402_session_start`, `x402_session_fetch`, `check_budget`
|
|
412
287
|
|
|
413
|
-
|
|
414
|
-
{ "chainId": 8453, "count": 47, "tokens": [{ "symbol": "USDC", "address": "0x833589...", "decimals": 6 }, ...] }
|
|
288
|
+
**Example exchange:**
|
|
415
289
|
```
|
|
290
|
+
User: Research the real-time flight tracking API market. Budget up to $5.
|
|
416
291
|
|
|
417
|
-
|
|
292
|
+
Agent: Starting with free sources... [scrapes 12 sources, builds baseline]
|
|
293
|
+
Gaps identified:
|
|
294
|
+
- Vendor pricing (not public for 3 of 5 vendors)
|
|
295
|
+
- Contact info for enterprise sales at FlightAware
|
|
296
|
+
- Recent funding data for two startups
|
|
418
297
|
|
|
419
|
-
|
|
298
|
+
To fill these I'd spend ~$2.75 USDC:
|
|
299
|
+
- Apollo contact enrichment: $1.50
|
|
300
|
+
- Crunchbase firmographics: $1.25
|
|
420
301
|
|
|
421
|
-
|
|
302
|
+
Approve? (y/n)
|
|
422
303
|
|
|
423
|
-
|
|
424
|
-
| Name | Type | Required | Description |
|
|
425
|
-
|---|---|---|---|
|
|
426
|
-
| `tokenSymbol` | string | ✅ | Token symbol (e.g. `"USDC"`) |
|
|
427
|
-
| `chainId` | number | ✅ | Chain ID |
|
|
428
|
-
| `recipientAddress` | string | ✅ | Recipient wallet address (0x-prefixed) |
|
|
429
|
-
| `amount` | string | ✅ | Amount in human-readable units (e.g. `"10.5"`) |
|
|
304
|
+
User: y
|
|
430
305
|
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
// Request
|
|
434
|
-
{ "tokenSymbol": "USDC", "chainId": 8453, "recipientAddress": "0xrecipient...", "amount": "100" }
|
|
435
|
-
|
|
436
|
-
// Response
|
|
437
|
-
{ "success": true, "txHash": "0x...", "amount": "100", "token": "USDC", "recipient": "0xrecipient..." }
|
|
306
|
+
Agent: [pays, fetches, compiles]
|
|
307
|
+
Report ready. Spent $2.75 of your $5 budget. [structured report attached]
|
|
438
308
|
```
|
|
439
309
|
|
|
440
310
|
---
|
|
441
311
|
|
|
442
|
-
###
|
|
312
|
+
### 3. Automation Agent
|
|
443
313
|
|
|
444
|
-
|
|
314
|
+
**What it does:** Completes real tasks end-to-end, paying for whatever services are needed along the way.
|
|
445
315
|
|
|
446
|
-
**
|
|
447
|
-
| Name | Type | Required | Description |
|
|
448
|
-
|---|---|---|---|
|
|
449
|
-
| `chainId` | number | ✅ | Chain ID |
|
|
450
|
-
| `tokens` | string[] | ❌ | Token symbols to check (omit for all registered tokens on chain) |
|
|
316
|
+
**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.
|
|
451
317
|
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
318
|
+
```
|
|
319
|
+
Agent: "Enrich this list of 50 leads and add to CRM"
|
|
320
|
+
│
|
|
321
|
+
├─ Processes first 10 free (from existing data)
|
|
322
|
+
├─ Remaining 40 need enrichment → $0.10/contact = $4.00 USDC
|
|
323
|
+
├─ Presents plan: 40 contacts × $0.10 = $4.00 total → user approves
|
|
324
|
+
├─ Runs enrichment in batches of 10 (staying under per-tx cap)
|
|
325
|
+
├─ Writes enriched data to CRM via API
|
|
326
|
+
└─ Reports: 50 leads enriched, $4.00 spent, 47 successful
|
|
459
327
|
```
|
|
460
328
|
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
### `swap_tokens`
|
|
464
|
-
|
|
465
|
-
Swap one ERC-20 token for another using Uniswap V3. Supported chains: Base, Arbitrum, Optimism, Polygon.
|
|
329
|
+
**Tools used:** `x402_pay`, `x402_session_start`, `set_spend_policy`, `get_transaction_history`
|
|
466
330
|
|
|
467
|
-
|
|
468
|
-
| Name | Type | Required | Description |
|
|
469
|
-
|---|---|---|---|
|
|
470
|
-
| `fromSymbol` | string | ✅ | Symbol of token to sell (e.g. `"USDC"`) |
|
|
471
|
-
| `toSymbol` | string | ✅ | Symbol of token to buy (e.g. `"WETH"`) |
|
|
472
|
-
| `amount` | string | ✅ | Amount to sell in human-readable units |
|
|
473
|
-
| `chainId` | number | ✅ | Chain ID (8453, 42161, 10, or 137) |
|
|
474
|
-
| `slippageBps` | number | ❌ | Slippage in basis points (default: 50 = 0.5%) |
|
|
331
|
+
---
|
|
475
332
|
|
|
476
|
-
|
|
477
|
-
```json
|
|
478
|
-
// Request
|
|
479
|
-
{ "fromSymbol": "USDC", "toSymbol": "WETH", "amount": "100", "chainId": 8453 }
|
|
333
|
+
## Environment Variables
|
|
480
334
|
|
|
481
|
-
|
|
482
|
-
|
|
335
|
+
```bash
|
|
336
|
+
# Required
|
|
337
|
+
AGENT_PRIVATE_KEY=0x... # Agent hot wallet key (0x-prefixed hex)
|
|
338
|
+
AGENT_WALLET_ADDRESS=0x... # Deployed AgentAccountV2 contract address
|
|
339
|
+
|
|
340
|
+
# Optional
|
|
341
|
+
CHAIN_ID=8453 # 8453 = Base Mainnet (default, recommended)
|
|
342
|
+
RPC_URL=https://mainnet.base.org # Custom RPC (Alchemy/Infura recommended for production)
|
|
343
|
+
SESSION_TTL_SECONDS=3600 # x402 session lifetime (default: 1 hour)
|
|
344
|
+
FACTORY_ADDRESS=0x... # For deploy_wallet and create_escrow
|
|
345
|
+
NFT_CONTRACT_ADDRESS=0x... # For deploy_wallet
|
|
483
346
|
```
|
|
484
347
|
|
|
485
348
|
---
|
|
486
349
|
|
|
487
|
-
|
|
350
|
+
## All 23 Tools
|
|
488
351
|
|
|
489
|
-
|
|
352
|
+
### Payments & 402 Flow
|
|
490
353
|
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
| `
|
|
495
|
-
| `
|
|
496
|
-
| `
|
|
354
|
+
| Tool | What It Does |
|
|
355
|
+
|------|-------------|
|
|
356
|
+
| `x402_pay` | Fetch a URL, automatically pay 402, retry — the core use case |
|
|
357
|
+
| `x402_session_start` | Pay once, get reusable session token for a base URL |
|
|
358
|
+
| `x402_session_fetch` | Make calls within an active session (no new payment) |
|
|
359
|
+
| `x402_session_status` | Inspect active sessions and TTL |
|
|
360
|
+
| `x402_session_end` | Explicitly close a session |
|
|
497
361
|
|
|
498
|
-
|
|
362
|
+
### Wallet & Spend Control
|
|
499
363
|
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
364
|
+
| Tool | What It Does |
|
|
365
|
+
|------|-------------|
|
|
366
|
+
| `get_wallet_info` | Address, balances, spend limits, queue depth |
|
|
367
|
+
| `send_payment` | Send ETH or ERC-20 via the AgentAccountV2 contract |
|
|
368
|
+
| `check_spend_limit` | Remaining spend limit for current period |
|
|
369
|
+
| `set_spend_policy` | Configure daily limits, per-tx caps, recipient allowlists |
|
|
370
|
+
| `check_budget` | Query on-chain remaining budget |
|
|
371
|
+
| `queue_approval` | Approve or cancel a queued transaction |
|
|
372
|
+
| `get_transaction_history` | On-chain event logs with filtering |
|
|
373
|
+
| `deploy_wallet` | Deploy a new AgentAccountV2 smart contract wallet |
|
|
504
374
|
|
|
505
|
-
|
|
506
|
-
{ "success": true, "burnTxHash": "0x...", "mintTxHash": "0x...", "amount": "500 USDC" }
|
|
507
|
-
```
|
|
375
|
+
### Token Operations
|
|
508
376
|
|
|
509
|
-
|
|
377
|
+
| Tool | What It Does |
|
|
378
|
+
|------|-------------|
|
|
379
|
+
| `lookup_token` | Token address + decimals by symbol and chain |
|
|
380
|
+
| `add_custom_token` | Register a custom ERC-20 in the token registry |
|
|
381
|
+
| `list_chain_tokens` | All registered tokens for a chain |
|
|
382
|
+
| `send_token` | Send any registry token (resolves address + decimals automatically) |
|
|
383
|
+
| `get_balances` | Token balances across one or more tokens |
|
|
510
384
|
|
|
511
|
-
###
|
|
385
|
+
### DeFi
|
|
512
386
|
|
|
513
|
-
|
|
387
|
+
| Tool | What It Does |
|
|
388
|
+
|------|-------------|
|
|
389
|
+
| `swap_tokens` | Uniswap V3 swap on Base, Arbitrum, Optimism, or Polygon |
|
|
390
|
+
| `bridge_usdc` | CCTP V2 cross-chain USDC bridge (10 EVM chains, ~12s) |
|
|
514
391
|
|
|
515
|
-
|
|
516
|
-
| Name | Type | Required | Description |
|
|
517
|
-
|---|---|---|---|
|
|
518
|
-
| `dailyLimitEth` | string | ❌ | Daily spend limit in ETH-equivalent (e.g. `"0.1"`) |
|
|
519
|
-
| `perTxCapEth` | string | ❌ | Per-transaction cap in ETH-equivalent (e.g. `"0.01"`) |
|
|
520
|
-
| `allowedRecipients` | string[] | ❌ | Allowlist of recipient addresses. Empty = all allowed. |
|
|
521
|
-
|
|
522
|
-
**Example:**
|
|
523
|
-
```json
|
|
524
|
-
// Request
|
|
525
|
-
{ "dailyLimitEth": "0.5", "perTxCapEth": "0.05", "allowedRecipients": ["0xrecipient..."] }
|
|
392
|
+
### Identity & Trust
|
|
526
393
|
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
394
|
+
| Tool | What It Does |
|
|
395
|
+
|------|-------------|
|
|
396
|
+
| `verify_agent_identity` | ERC-8004 on-chain identity verification |
|
|
397
|
+
| `get_reputation` | On-chain reputation score and history |
|
|
398
|
+
| `create_escrow` | Mutual-stake USDC escrow — both parties lock collateral |
|
|
530
399
|
|
|
531
400
|
---
|
|
532
401
|
|
|
533
|
-
|
|
402
|
+
## Key Tool Examples
|
|
534
403
|
|
|
535
|
-
|
|
404
|
+
### `x402_pay` — The Core Tool
|
|
536
405
|
|
|
537
|
-
**Parameters:**
|
|
538
|
-
| Name | Type | Required | Description |
|
|
539
|
-
|---|---|---|---|
|
|
540
|
-
| `token` | string | ❌ | Token address (omit for ETH / zero address) |
|
|
541
|
-
| `spender` | string | ❌ | Spender address (defaults to Agent Wallet address) |
|
|
542
|
-
|
|
543
|
-
**Example:**
|
|
544
406
|
```json
|
|
545
407
|
// Request
|
|
546
|
-
{
|
|
408
|
+
{
|
|
409
|
+
"tool": "x402_pay",
|
|
410
|
+
"arguments": {
|
|
411
|
+
"url": "https://api.example.com/premium-data",
|
|
412
|
+
"max_payment_eth": "0.0002"
|
|
413
|
+
}
|
|
414
|
+
}
|
|
547
415
|
|
|
548
416
|
// Response
|
|
549
|
-
{ "
|
|
417
|
+
{ "status": 200, "body": "{ ... }" }
|
|
550
418
|
```
|
|
551
419
|
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
### `verify_agent_identity`
|
|
420
|
+
If the cost exceeds `max_payment_eth`, the tool returns an error before paying — no surprise charges.
|
|
555
421
|
|
|
556
|
-
|
|
422
|
+
### `x402_session_start` — Pay Once for Multiple Calls
|
|
557
423
|
|
|
558
|
-
**Parameters:**
|
|
559
|
-
| Name | Type | Required | Description |
|
|
560
|
-
|---|---|---|---|
|
|
561
|
-
| `agentAddress` | string | ✅ | Agent owner address (0x-prefixed) |
|
|
562
|
-
|
|
563
|
-
**Example:**
|
|
564
424
|
```json
|
|
565
425
|
// Request
|
|
566
|
-
{
|
|
426
|
+
{
|
|
427
|
+
"tool": "x402_session_start",
|
|
428
|
+
"arguments": {
|
|
429
|
+
"endpoint": "https://api.example.com/",
|
|
430
|
+
"ttl_seconds": 3600,
|
|
431
|
+
"label": "market-data-session"
|
|
432
|
+
}
|
|
433
|
+
}
|
|
567
434
|
|
|
568
435
|
// Response
|
|
569
|
-
{ "
|
|
436
|
+
{ "session_id": "sess_abc123", "token": "eyJ...", "expires_at": 1741000000 }
|
|
570
437
|
```
|
|
571
438
|
|
|
572
|
-
---
|
|
573
|
-
|
|
574
|
-
### `get_reputation`
|
|
575
|
-
|
|
576
|
-
Fetch an agent's on-chain reputation score and history.
|
|
577
|
-
|
|
578
|
-
**Parameters:**
|
|
579
|
-
| Name | Type | Required | Description |
|
|
580
|
-
|---|---|---|---|
|
|
581
|
-
| `agentAddress` | string | ✅ | Agent address (0x-prefixed) |
|
|
582
|
-
|
|
583
|
-
**Example:**
|
|
584
439
|
```json
|
|
585
|
-
//
|
|
586
|
-
{
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
440
|
+
// Subsequent calls — no new payment
|
|
441
|
+
{
|
|
442
|
+
"tool": "x402_session_fetch",
|
|
443
|
+
"arguments": {
|
|
444
|
+
"url": "https://api.example.com/stocks/AAPL",
|
|
445
|
+
"session_id": "sess_abc123"
|
|
446
|
+
}
|
|
447
|
+
}
|
|
590
448
|
```
|
|
591
449
|
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
### `create_escrow`
|
|
595
|
-
|
|
596
|
-
Create a mutual-stake escrow vault between the Agent Wallet (buyer) and a counterparty (seller). Both parties lock collateral equal to the payment amount, ensuring aligned incentives. Uses USDC as the payment token.
|
|
597
|
-
|
|
598
|
-
**Parameters:**
|
|
599
|
-
| Name | Type | Required | Description |
|
|
600
|
-
|---|---|---|---|
|
|
601
|
-
| `counterpartyAddress` | string | ✅ | Seller/counterparty address (0x-prefixed) |
|
|
602
|
-
| `stakeAmount` | string | ✅ | Payment amount in USDC (e.g. `"100"`) |
|
|
603
|
-
| `terms` | string | ✅ | Human-readable escrow terms |
|
|
604
|
-
| `factoryAddress` | string | ❌ | StakeVaultFactory address (defaults to `FACTORY_ADDRESS` env) |
|
|
605
|
-
| `deadlineDays` | number | ❌ | Deadline in days (default: 7) |
|
|
606
|
-
| `challengeWindowHours` | number | ❌ | Challenge window in hours after fulfillment (default: 24) |
|
|
450
|
+
### `check_budget` — Know Before You Loop
|
|
607
451
|
|
|
608
|
-
**Example:**
|
|
609
452
|
```json
|
|
610
|
-
// Request
|
|
611
|
-
{ "
|
|
453
|
+
// Request — check before starting an expensive loop
|
|
454
|
+
{ "tool": "check_budget", "arguments": {} }
|
|
612
455
|
|
|
613
456
|
// Response
|
|
614
|
-
{
|
|
457
|
+
{
|
|
458
|
+
"remaining": "7.50 USDC",
|
|
459
|
+
"spent": "2.50 USDC",
|
|
460
|
+
"limit": "10.00 USDC",
|
|
461
|
+
"periodEnds": "2026-03-24T00:00:00Z"
|
|
462
|
+
}
|
|
615
463
|
```
|
|
616
464
|
|
|
617
465
|
---
|
|
618
466
|
|
|
619
467
|
## Supported Chains
|
|
620
468
|
|
|
621
|
-
| Chain | Chain ID |
|
|
622
|
-
|
|
623
|
-
| Base Mainnet | 8453 |
|
|
624
|
-
|
|
|
625
|
-
|
|
|
626
|
-
|
|
|
627
|
-
|
|
|
469
|
+
| Chain | Chain ID | Recommended For |
|
|
470
|
+
|-------|----------|----------------|
|
|
471
|
+
| Base Mainnet | 8453 | Everything — lowest gas, most x402 activity |
|
|
472
|
+
| Arbitrum One | 42161 | High-throughput swaps |
|
|
473
|
+
| Optimism | 10 | Low-cost transfers |
|
|
474
|
+
| Polygon | 137 | High-frequency micro-payments |
|
|
475
|
+
| Ethereum Mainnet | 1 | Identity, large settlements |
|
|
628
476
|
| Avalanche | 43114 | Bridge, transfers |
|
|
629
|
-
| Linea |
|
|
630
|
-
|
|
|
631
|
-
| Sonic | 146 | Bridge, transfers |
|
|
632
|
-
| Worldchain | 480 | Bridge, transfers |
|
|
633
|
-
| Base Sepolia | 84532 | Testnet — all features |
|
|
634
|
-
| Arbitrum Sepolia | 421614 | Testnet — identity, transfers |
|
|
477
|
+
| Linea / Unichain / Sonic / Worldchain | various | Bridge, transfers |
|
|
478
|
+
| Base Sepolia | 84532 | Testing |
|
|
635
479
|
|
|
636
480
|
---
|
|
637
481
|
|
|
638
|
-
##
|
|
482
|
+
## Security Model
|
|
639
483
|
|
|
640
|
-
|
|
484
|
+
**Non-custodial:** The agent signs all transactions locally with its private key. No third party holds or validates keys.
|
|
641
485
|
|
|
642
|
-
-
|
|
643
|
-
-
|
|
644
|
-
-
|
|
645
|
-
-
|
|
486
|
+
**On-chain enforcement:**
|
|
487
|
+
- Per-transaction caps — over-cap transactions queue for human approval via `queue_approval`
|
|
488
|
+
- Daily period limits — aggregate spending enforced by the AgentAccountV2 smart contract
|
|
489
|
+
- Recipient allowlists — restrict which addresses the agent can send to
|
|
646
490
|
|
|
647
|
-
**
|
|
491
|
+
**Role separation:**
|
|
492
|
+
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.
|
|
648
493
|
|
|
649
|
-
|
|
494
|
+
**x402 sessions:**
|
|
495
|
+
Session tokens are ECDSA-signed claims. Any x402 V2 server can independently verify them — no central session store required.
|
|
650
496
|
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
| Env Var | Required | Default | Description |
|
|
654
|
-
|---|---|---|---|
|
|
655
|
-
| `AGENT_PRIVATE_KEY` | ✅ | — | Agent signing key (0x-prefixed hex). NOT the owner key. |
|
|
656
|
-
| `AGENT_WALLET_ADDRESS` | ✅ | — | Deployed AgentAccountV2 contract address |
|
|
657
|
-
| `CHAIN_ID` | ❌ | `8453` | Chain ID (8453 = Base Mainnet) |
|
|
658
|
-
| `RPC_URL` | ❌ | Public Base RPC | Custom RPC endpoint (Alchemy, Infura, etc. recommended) |
|
|
659
|
-
| `SESSION_TTL_SECONDS` | ❌ | `3600` | Default x402 session lifetime (60–2592000 seconds) |
|
|
660
|
-
| `FACTORY_ADDRESS` | ❌ | — | AgentAccountFactoryV2 address (for `deploy_wallet`, `create_escrow`) |
|
|
661
|
-
| `NFT_CONTRACT_ADDRESS` | ❌ | — | NFT contract address (for `deploy_wallet`) |
|
|
497
|
+
**Minimal dependency footprint:**
|
|
498
|
+
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.
|
|
662
499
|
|
|
663
500
|
---
|
|
664
501
|
|
|
665
|
-
##
|
|
666
|
-
|
|
667
|
-
### Non-Custodial Design
|
|
668
|
-
|
|
669
|
-
AgentPay MCP is **non-custodial** — the agent signs all transactions locally with its private key. No third party holds or validates keys at any point.
|
|
502
|
+
## MCP 2026 Compliance
|
|
670
503
|
|
|
671
|
-
|
|
504
|
+
AgentPay MCP aligns with the emerging MCP security standards for 2026, including CoSAI (Coalition for Secure AI) threat categories and OAuth 2.1 requirements.
|
|
672
505
|
|
|
673
|
-
|
|
674
|
-
- **Daily period limits** — aggregate spending is enforced on-chain by the AgentAccountV2 contract
|
|
675
|
-
- **Recipient allowlists** — restrict which addresses the agent can send to via `set_spend_policy`
|
|
506
|
+
**Security posture documentation:** See [`docs/security-posture.md`](docs/security-posture.md) for the full compliance matrix covering:
|
|
676
507
|
|
|
677
|
-
|
|
508
|
+
- **CoSAI T9 (Financial Fraud)** — On-chain spend caps, merchant allowlists, and human-approval gates mitigate unauthorized agent spending
|
|
509
|
+
- **CoSAI T10 (Identity Spoofing)** — ERC-8004 agent identity verification + non-custodial key management prevent identity-based attacks
|
|
510
|
+
- **OAuth 2.1 + PKCE** — MCP server authentication supports OAuth 2.1 with PKCE for enterprise SSO integration (Azure AD, Okta)
|
|
511
|
+
- **MCP Audit Logging** — Every tool invocation logged with timestamp, parameters, outcome, and transaction hash (where applicable)
|
|
678
512
|
|
|
679
|
-
|
|
680
|
-
- Adjust spend limits without redeploying
|
|
681
|
-
- Revoke the agent's operator access
|
|
682
|
-
- Cancel queued transactions
|
|
683
|
-
|
|
684
|
-
This means even if the agent's key is compromised, the attacker can only spend up to the configured limit.
|
|
685
|
-
|
|
686
|
-
### x402 Session Tokens
|
|
687
|
-
|
|
688
|
-
Session tokens are self-contained ECDSA-signed claims. Any server implementing x402 V2 can independently verify them — no central session store required.
|
|
513
|
+
For enterprise security teams evaluating MCP servers: the security posture document provides the artifact your audit process needs.
|
|
689
514
|
|
|
690
515
|
---
|
|
691
516
|
|
|
@@ -695,7 +520,7 @@ Session tokens are self-contained ECDSA-signed claims. Any server implementing x
|
|
|
695
520
|
┌─────────────────────────────────────────┐
|
|
696
521
|
│ AI Agent (Claude / Cursor / Windsurf) │
|
|
697
522
|
└────────────────┬────────────────────────┘
|
|
698
|
-
│ MCP (stdio/SSE)
|
|
523
|
+
│ MCP (stdio / SSE)
|
|
699
524
|
┌────────────────▼────────────────────────┐
|
|
700
525
|
│ AgentPay MCP Server │
|
|
701
526
|
│ ┌────────────┐ ┌────────────────────┐ │
|
|
@@ -706,28 +531,22 @@ Session tokens are self-contained ECDSA-signed claims. Any server implementing x
|
|
|
706
531
|
│ │ agentwallet-sdk v6.0.0 │ │
|
|
707
532
|
│ │ TokenRegistry SwapModule │ │
|
|
708
533
|
│ │ BridgeModule ERC8004Client │ │
|
|
709
|
-
│ │ ReputationClient MutualStake... │ │
|
|
710
534
|
│ └─────┬──────────────────────────────┘ │
|
|
711
535
|
└────────┼────────────────────────────────┘
|
|
712
536
|
│ viem + RPC
|
|
713
537
|
┌────────▼────────────────────────────────┐
|
|
714
538
|
│ AgentAccountV2 Smart Contract │
|
|
539
|
+
│ SpendingPolicy · Tx Queue │
|
|
715
540
|
│ (12 chains — Base, ETH, ARB, OP, ...) │
|
|
716
541
|
└─────────────────────────────────────────┘
|
|
717
542
|
```
|
|
718
543
|
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
**Tool Routing:** Each MCP tool call is routed to the corresponding handler in `src/tools/`. All handlers are typed with Zod schemas and return structured `{ content: [{ type: "text", text: "..." }] }` responses.
|
|
722
|
-
|
|
723
|
-
**Token Resolution:** `send_token`, `get_balances`, and `swap_tokens` use the agentwallet-sdk `TokenRegistry` to resolve symbols to on-chain addresses and decimals, eliminating the need for agents to manage contract addresses manually.
|
|
544
|
+
Transport: `stdio` by default (Claude Desktop, Cursor, Windsurf). SSE available for remote deployments.
|
|
724
545
|
|
|
725
546
|
---
|
|
726
547
|
|
|
727
548
|
## Contributing
|
|
728
549
|
|
|
729
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on submitting issues and pull requests.
|
|
730
|
-
|
|
731
550
|
```bash
|
|
732
551
|
git clone https://github.com/up2itnow0822/agentpay-mcp
|
|
733
552
|
cd agentpay-mcp
|
|
@@ -738,16 +557,59 @@ npm test
|
|
|
738
557
|
|
|
739
558
|
---
|
|
740
559
|
|
|
741
|
-
##
|
|
560
|
+
## Patent Notice
|
|
742
561
|
|
|
743
|
-
|
|
562
|
+
**Patent Pending** — USPTO provisional application filed March 2026: "Non-Custodial Multi-Chain Financial Infrastructure System for Autonomous AI Agents."
|
|
563
|
+
|
|
564
|
+
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.
|
|
565
|
+
|
|
566
|
+
---
|
|
567
|
+
|
|
568
|
+
## x402 Ecosystem — 75M+ Transactions, Cloudflare Native Support
|
|
569
|
+
|
|
570
|
+
agentpay-mcp is built on the [x402 HTTP payment standard](https://x402.org), which has now processed **75M+ transactions on Base mainnet** — primarily through Coinbase Agentic Wallets and developer integrations.
|
|
571
|
+
|
|
572
|
+
**Cloudflare has added native x402 support** to its Agents SDK and MCP server runtime, meaning any Cloudflare Worker-hosted agent can now make x402 payments natively. Google, Circle, and Stripe are all actively integrating x402 into their agent ecosystems.
|
|
573
|
+
|
|
574
|
+
agentpay-mcp is the **open-source governance layer** on top of this infrastructure: while x402 handles the payment protocol, agentpay-mcp adds the trust controls that production agents require — HITL approval queues, spend caps, recipient allowlists, and on-chain audit trails.
|
|
575
|
+
|
|
576
|
+
| x402 Ecosystem | Status |
|
|
577
|
+
|---|---|
|
|
578
|
+
| Base mainnet transactions | 75M+ |
|
|
579
|
+
| Cloudflare Agents SDK | ✅ Native support |
|
|
580
|
+
| Cloudflare MCP servers | ✅ Native support |
|
|
581
|
+
| Coinbase Agentic Wallets | ✅ Primary client |
|
|
582
|
+
| Google / Circle / Stripe | 🔄 Active integration |
|
|
583
|
+
| agentpay-mcp governance layer | ✅ Open-source |
|
|
744
584
|
|
|
745
585
|
---
|
|
746
586
|
|
|
747
|
-
##
|
|
587
|
+
## EU AI Act Compliance
|
|
588
|
+
|
|
589
|
+
**Enforcement deadline: August 2, 2026.** AI systems that execute or facilitate financial transactions are classified as **high-risk** under EU AI Act Annex III. High-risk classification requires:
|
|
590
|
+
|
|
591
|
+
- ✅ **Human oversight mechanisms** — mandatory human review and override capability
|
|
592
|
+
- ✅ **Transparency and explainability** — auditable transaction records
|
|
593
|
+
- ✅ **Access controls** — spend limits that cannot be bypassed by the agent
|
|
594
|
+
- ✅ **Technical documentation** — conformity assessment support
|
|
595
|
+
|
|
596
|
+
agentpay-mcp satisfies all four requirements out of the box:
|
|
597
|
+
|
|
598
|
+
| Requirement | agentpay-mcp Feature |
|
|
599
|
+
|---|---|
|
|
600
|
+
| Human oversight | `queue_approval` — transactions above threshold require explicit human approval before execution |
|
|
601
|
+
| Audit trail | `get_transaction_history` — full on-chain event log, immutable, verifiable on basescan.org |
|
|
602
|
+
| Spend controls | `set_spend_policy` — per-tx caps and daily limits enforced at the smart contract layer |
|
|
603
|
+
| Scope restriction | Recipient allowlists — agent cannot send to unapproved addresses regardless of instructions |
|
|
604
|
+
|
|
605
|
+
European enterprises deploying agent systems that touch payments have **~150 days** to implement compliant human oversight and audit controls. agentpay-mcp is the fastest path to EU AI Act compliance for MCP-compatible agent deployments.
|
|
748
606
|
|
|
749
|
-
|
|
607
|
+
> **Fines for non-compliance:** Up to €35M or 7% of global annual revenue. Germany published its national enforcement bill in February 2026.
|
|
608
|
+
|
|
609
|
+
---
|
|
750
610
|
|
|
751
|
-
|
|
611
|
+
## License
|
|
612
|
+
|
|
613
|
+
MIT © [AI Agent Economy](https://ai-agent-economy.com)
|
|
752
614
|
|
|
753
|
-
**
|
|
615
|
+
Built by **AI Agent Economy** — infrastructure for production agent workflows.
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentpay-mcp",
|
|
3
|
-
"version": "4.0.
|
|
3
|
+
"version": "4.0.2",
|
|
4
4
|
"mcpName": "io.github.up2itnow0822/agentpay",
|
|
5
|
-
"description": "AgentPay MCP Server — Non-custodial x402 payment layer for AI agents. Multi-chain wallets, spending limits, and machine-to-machine payments.",
|
|
5
|
+
"description": "AgentPay MCP Server — Non-custodial x402 payment layer for AI agents. Multi-chain wallets, spending limits, and machine-to-machine payments. Patent Pending.",
|
|
6
6
|
"main": "dist/index.js",
|
|
7
7
|
"types": "dist/index.d.ts",
|
|
8
8
|
"bin": {
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
"test:watch": "vitest",
|
|
24
24
|
"test:coverage": "vitest run --coverage",
|
|
25
25
|
"typecheck": "tsc --noEmit",
|
|
26
|
-
"lint": "eslint src/",
|
|
26
|
+
"lint": "eslint src/ tests/ --config eslint.config.mjs",
|
|
27
27
|
"prepublishOnly": "npm run clean && npm run build && npm run typecheck"
|
|
28
28
|
},
|
|
29
29
|
"keywords": [
|
|
@@ -66,6 +66,7 @@
|
|
|
66
66
|
"@typescript-eslint/parser": "^8.57.1",
|
|
67
67
|
"@vitest/coverage-v8": "^4.0.18",
|
|
68
68
|
"eslint": "^10.1.0",
|
|
69
|
+
"globals": "^17.4.0",
|
|
69
70
|
"typescript": "^5.3.3",
|
|
70
71
|
"typescript-eslint": "^8.57.1",
|
|
71
72
|
"vitest": "^4.0.18"
|