agentpay-mcp 4.0.0 → 4.0.1
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 +313 -514
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -5,69 +5,112 @@
|
|
|
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
|
+
## Security & Dependencies
|
|
17
39
|
|
|
18
|
-
|
|
40
|
+
AgentPay MCP is built for enterprise MCP deployments where supply chain security matters.
|
|
19
41
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
| DeFi | `swap_tokens` (Uniswap V3), `bridge_usdc` (CCTP V2) |
|
|
25
|
-
| Spending Controls | `set_spend_policy`, `check_budget` |
|
|
26
|
-
| Agent Identity | `verify_agent_identity`, `get_reputation` |
|
|
27
|
-
| Escrow | `create_escrow` |
|
|
42
|
+
- **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.
|
|
43
|
+
- **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.
|
|
44
|
+
- **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.
|
|
45
|
+
- **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.
|
|
28
46
|
|
|
29
|
-
|
|
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
|
|
47
|
+
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.
|
|
36
48
|
|
|
37
49
|
---
|
|
38
50
|
|
|
39
|
-
##
|
|
51
|
+
## AI Agent Discovery
|
|
40
52
|
|
|
41
|
-
|
|
53
|
+
AgentPay MCP is designed to be discovered and used by AI agents. Compatible with:
|
|
42
54
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
55
|
+
- **[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
|
|
56
|
+
- **[AgentSkills](https://agentskills.io)** - Installable as a cross-framework skill in any AgentSkills-compatible harness (Claude Code, Cursor, Gemini CLI, Antigravity)
|
|
57
|
+
- **[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)** - Pairs as the payment layer for browser-native agents
|
|
46
58
|
|
|
47
|
-
###
|
|
59
|
+
### Install as a Skill
|
|
48
60
|
|
|
49
|
-
|
|
61
|
+
Add to any MCP-compatible harness config:
|
|
50
62
|
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"mcpServers": {
|
|
66
|
+
"agentpay": {
|
|
67
|
+
"command": "npx",
|
|
68
|
+
"args": ["agentpay-mcp"],
|
|
69
|
+
"env": {
|
|
70
|
+
"AGENT_PRIVATE_KEY": "0x...",
|
|
71
|
+
"AGENT_WALLET_ADDRESS": "0x..."
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Works with Claude Code, Cursor, Gemini CLI, OpenClaw, Windsurf, and any MCP client.
|
|
55
79
|
|
|
56
|
-
|
|
57
|
-
CHAIN_ID=8453 # 8453 = Base Mainnet (default)
|
|
58
|
-
RPC_URL=https://mainnet.base.org # Custom RPC URL
|
|
80
|
+
---
|
|
59
81
|
|
|
60
|
-
|
|
61
|
-
SESSION_TTL_SECONDS=3600 # Session lifetime (default: 1 hour)
|
|
82
|
+
## The 402 Flow — What This Actually Does
|
|
62
83
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
84
|
+
```
|
|
85
|
+
Agent calls a paid API
|
|
86
|
+
│
|
|
87
|
+
▼
|
|
88
|
+
HTTP 402 ←── "Payment required: 0.50 USDC on Base"
|
|
89
|
+
│
|
|
90
|
+
▼
|
|
91
|
+
AgentPay MCP evaluates your policy:
|
|
92
|
+
• Is 0.50 USDC under your per-tx cap? ($5 limit → ✅)
|
|
93
|
+
• Is this recipient allowlisted? (api.example.com → ✅)
|
|
94
|
+
• Require human approval? (under $1 threshold → auto)
|
|
95
|
+
│
|
|
96
|
+
▼
|
|
97
|
+
Payment sent → API retried with payment proof → 200 OK
|
|
98
|
+
│
|
|
99
|
+
▼
|
|
100
|
+
Agent gets the data. Full tx on basescan.org.
|
|
66
101
|
```
|
|
67
102
|
|
|
68
|
-
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Quick Start
|
|
106
|
+
|
|
107
|
+
### 1. Install
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
npm install -g agentpay-mcp
|
|
111
|
+
```
|
|
69
112
|
|
|
70
|
-
|
|
113
|
+
### 2. Configure Claude Desktop
|
|
71
114
|
|
|
72
115
|
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
73
116
|
|
|
@@ -87,9 +130,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
|
87
130
|
}
|
|
88
131
|
```
|
|
89
132
|
|
|
90
|
-
|
|
133
|
+
### 3. Configure Cursor
|
|
91
134
|
|
|
92
|
-
Add to `.cursor/mcp.json`
|
|
135
|
+
Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
|
|
93
136
|
|
|
94
137
|
```json
|
|
95
138
|
{
|
|
@@ -107,585 +150,347 @@ Add to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:
|
|
|
107
150
|
}
|
|
108
151
|
```
|
|
109
152
|
|
|
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
|
-
---
|
|
153
|
+
### 4. Set Spend Caps
|
|
148
154
|
|
|
149
|
-
|
|
155
|
+
Once running, tell your agent:
|
|
150
156
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
157
|
+
```
|
|
158
|
+
Set my spend policy: $1 per transaction, $10 per day, only send to allowlisted addresses.
|
|
159
|
+
```
|
|
154
160
|
|
|
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) |
|
|
161
|
+
Or call `set_spend_policy` directly:
|
|
161
162
|
|
|
162
|
-
**Example:**
|
|
163
163
|
```json
|
|
164
|
-
// Request
|
|
165
|
-
{ "token_id": "42" }
|
|
166
|
-
|
|
167
|
-
// Response
|
|
168
164
|
{
|
|
169
|
-
"
|
|
170
|
-
"
|
|
171
|
-
|
|
165
|
+
"tool": "set_spend_policy",
|
|
166
|
+
"arguments": {
|
|
167
|
+
"perTxCapEth": "0.0004",
|
|
168
|
+
"dailyLimitEth": "0.004",
|
|
169
|
+
"allowedRecipients": ["0xapi-provider-address..."]
|
|
170
|
+
}
|
|
172
171
|
}
|
|
173
172
|
```
|
|
174
173
|
|
|
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
|
-
```
|
|
174
|
+
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
175
|
|
|
203
176
|
---
|
|
204
177
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
Execute an ETH or ERC-20 transfer via the AgentAccountV2 contract. Subject to on-chain spend limits.
|
|
178
|
+
## Human-Approval Mode (the Default)
|
|
208
179
|
|
|
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) |
|
|
180
|
+
By default, transactions above your auto-approve threshold queue for human review. The agent cannot bypass this.
|
|
217
181
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
{ "to": "0xrecipient...", "amount_eth": "0.01" }
|
|
222
|
-
|
|
223
|
-
// Response
|
|
224
|
-
"✅ Payment sent: 0.01 ETH → 0xrecipient...
|
|
225
|
-
Tx: 0xtxhash..."
|
|
182
|
+
```
|
|
183
|
+
$0.50 USDC request → under $1 threshold → auto-approved → paid → result returned
|
|
184
|
+
$5.00 USDC request → over $1 threshold → queued → you get notified → approve or reject
|
|
226
185
|
```
|
|
227
186
|
|
|
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 |
|
|
187
|
+
To approve a queued payment:
|
|
268
188
|
|
|
269
|
-
**Example:**
|
|
270
189
|
```json
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
190
|
+
{
|
|
191
|
+
"tool": "queue_approval",
|
|
192
|
+
"arguments": {
|
|
193
|
+
"action": "approve",
|
|
194
|
+
"tx_id": "0x..."
|
|
195
|
+
}
|
|
196
|
+
}
|
|
276
197
|
```
|
|
277
198
|
|
|
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
|
-
---
|
|
199
|
+
To reject it:
|
|
293
200
|
|
|
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.
|
|
297
|
-
|
|
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
201
|
```json
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
202
|
+
{
|
|
203
|
+
"tool": "queue_approval",
|
|
204
|
+
"arguments": {
|
|
205
|
+
"action": "cancel",
|
|
206
|
+
"tx_id": "0x..."
|
|
207
|
+
}
|
|
208
|
+
}
|
|
313
209
|
```
|
|
314
210
|
|
|
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) |
|
|
211
|
+
The agent sees the outcome and decides what to do next (use cached data, ask user, abort).
|
|
329
212
|
|
|
330
213
|
---
|
|
331
214
|
|
|
332
|
-
|
|
215
|
+
## Value Packs — Three Production Workflow Patterns
|
|
333
216
|
|
|
334
|
-
|
|
217
|
+
### 1. Paid API Agent
|
|
335
218
|
|
|
336
|
-
**
|
|
337
|
-
| Name | Type | Required | Description |
|
|
338
|
-
|---|---|---|---|
|
|
339
|
-
| `session_id` | string | ❌ | Specific session to inspect (omit for all active sessions) |
|
|
340
|
-
|
|
341
|
-
---
|
|
219
|
+
**What it does:** Finds the right paid API for a data need, pays once, caches the result.
|
|
342
220
|
|
|
343
|
-
|
|
221
|
+
**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
222
|
|
|
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.
|
|
223
|
+
```
|
|
224
|
+
Agent: "I need current options flow data for AAPL"
|
|
225
|
+
│
|
|
226
|
+
├─ Tries free sources → insufficient data
|
|
227
|
+
├─ Finds paid API → gets 402 for $0.25 USDC
|
|
228
|
+
├─ Checks: $0.25 < $1 cap → auto-approved
|
|
229
|
+
├─ Pays with x402_pay → gets data
|
|
230
|
+
├─ Caches result at ~/.clawpowers/state/market:AAPL:options
|
|
231
|
+
└─ Returns data + payment receipt
|
|
232
|
+
```
|
|
357
233
|
|
|
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) |
|
|
234
|
+
**Tools used:** `x402_pay`, `check_spend_limit`, `get_transaction_history`
|
|
363
235
|
|
|
364
|
-
**Example:**
|
|
365
|
-
```
|
|
366
|
-
|
|
367
|
-
{ "symbol": "USDC", "chainId": 8453 }
|
|
236
|
+
**Example exchange:**
|
|
237
|
+
```
|
|
238
|
+
User: Get me the options flow for AAPL for the last 7 days.
|
|
368
239
|
|
|
369
|
-
|
|
370
|
-
|
|
240
|
+
Agent: Checking free sources... insufficient. Found paid API at data.example.com.
|
|
241
|
+
Cost: $0.25 USDC (under your $1 auto-approve cap). Paying now.
|
|
242
|
+
[x402_pay → 200 OK, paid 0.25 USDC, tx: 0xabc...]
|
|
243
|
+
Here's the options flow data: [results]
|
|
244
|
+
Total cost today: $0.25 of your $10 daily budget.
|
|
371
245
|
```
|
|
372
246
|
|
|
373
247
|
---
|
|
374
248
|
|
|
375
|
-
###
|
|
249
|
+
### 2. Research Agent
|
|
376
250
|
|
|
377
|
-
|
|
251
|
+
**What it does:** Gathers from free sources first, fills gaps with paid data, compiles a structured output.
|
|
378
252
|
|
|
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 |
|
|
253
|
+
**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
254
|
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
255
|
+
```
|
|
256
|
+
Agent: "Research competitive landscape for real-time flight tracking APIs"
|
|
257
|
+
│
|
|
258
|
+
├─ Scrapes free sources (GitHub, HN, docs) → baseline data
|
|
259
|
+
├─ Identifies gaps: pricing data, SLA guarantees, enterprise contacts
|
|
260
|
+
├─ Proposes paid lookups totaling $2.75 USDC → presents for approval
|
|
261
|
+
├─ Human approves
|
|
262
|
+
├─ Pays for Apollo contact enrichment ($1.50) + Crunchbase data ($1.25)
|
|
263
|
+
└─ Compiles: free data + paid data → structured report
|
|
395
264
|
```
|
|
396
265
|
|
|
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 }
|
|
266
|
+
**Tools used:** `x402_pay`, `x402_session_start`, `x402_session_fetch`, `check_budget`
|
|
412
267
|
|
|
413
|
-
|
|
414
|
-
{ "chainId": 8453, "count": 47, "tokens": [{ "symbol": "USDC", "address": "0x833589...", "decimals": 6 }, ...] }
|
|
268
|
+
**Example exchange:**
|
|
415
269
|
```
|
|
270
|
+
User: Research the real-time flight tracking API market. Budget up to $5.
|
|
416
271
|
|
|
417
|
-
|
|
272
|
+
Agent: Starting with free sources... [scrapes 12 sources, builds baseline]
|
|
273
|
+
Gaps identified:
|
|
274
|
+
- Vendor pricing (not public for 3 of 5 vendors)
|
|
275
|
+
- Contact info for enterprise sales at FlightAware
|
|
276
|
+
- Recent funding data for two startups
|
|
418
277
|
|
|
419
|
-
|
|
278
|
+
To fill these I'd spend ~$2.75 USDC:
|
|
279
|
+
- Apollo contact enrichment: $1.50
|
|
280
|
+
- Crunchbase firmographics: $1.25
|
|
420
281
|
|
|
421
|
-
|
|
282
|
+
Approve? (y/n)
|
|
422
283
|
|
|
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"`) |
|
|
284
|
+
User: y
|
|
430
285
|
|
|
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..." }
|
|
286
|
+
Agent: [pays, fetches, compiles]
|
|
287
|
+
Report ready. Spent $2.75 of your $5 budget. [structured report attached]
|
|
438
288
|
```
|
|
439
289
|
|
|
440
290
|
---
|
|
441
291
|
|
|
442
|
-
###
|
|
292
|
+
### 3. Automation Agent
|
|
443
293
|
|
|
444
|
-
|
|
294
|
+
**What it does:** Completes real tasks end-to-end, paying for whatever services are needed along the way.
|
|
445
295
|
|
|
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) |
|
|
296
|
+
**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
297
|
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
298
|
+
```
|
|
299
|
+
Agent: "Enrich this list of 50 leads and add to CRM"
|
|
300
|
+
│
|
|
301
|
+
├─ Processes first 10 free (from existing data)
|
|
302
|
+
├─ Remaining 40 need enrichment → $0.10/contact = $4.00 USDC
|
|
303
|
+
├─ Presents plan: 40 contacts × $0.10 = $4.00 total → user approves
|
|
304
|
+
├─ Runs enrichment in batches of 10 (staying under per-tx cap)
|
|
305
|
+
├─ Writes enriched data to CRM via API
|
|
306
|
+
└─ Reports: 50 leads enriched, $4.00 spent, 47 successful
|
|
459
307
|
```
|
|
460
308
|
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
### `swap_tokens`
|
|
309
|
+
**Tools used:** `x402_pay`, `x402_session_start`, `set_spend_policy`, `get_transaction_history`
|
|
464
310
|
|
|
465
|
-
|
|
311
|
+
---
|
|
466
312
|
|
|
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%) |
|
|
313
|
+
## Environment Variables
|
|
475
314
|
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
315
|
+
```bash
|
|
316
|
+
# Required
|
|
317
|
+
AGENT_PRIVATE_KEY=0x... # Agent hot wallet key (0x-prefixed hex)
|
|
318
|
+
AGENT_WALLET_ADDRESS=0x... # Deployed AgentAccountV2 contract address
|
|
319
|
+
|
|
320
|
+
# Optional
|
|
321
|
+
CHAIN_ID=8453 # 8453 = Base Mainnet (default, recommended)
|
|
322
|
+
RPC_URL=https://mainnet.base.org # Custom RPC (Alchemy/Infura recommended for production)
|
|
323
|
+
SESSION_TTL_SECONDS=3600 # x402 session lifetime (default: 1 hour)
|
|
324
|
+
FACTORY_ADDRESS=0x... # For deploy_wallet and create_escrow
|
|
325
|
+
NFT_CONTRACT_ADDRESS=0x... # For deploy_wallet
|
|
483
326
|
```
|
|
484
327
|
|
|
485
328
|
---
|
|
486
329
|
|
|
487
|
-
|
|
330
|
+
## All 23 Tools
|
|
488
331
|
|
|
489
|
-
|
|
332
|
+
### Payments & 402 Flow
|
|
490
333
|
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
| `
|
|
495
|
-
| `
|
|
496
|
-
| `
|
|
334
|
+
| Tool | What It Does |
|
|
335
|
+
|------|-------------|
|
|
336
|
+
| `x402_pay` | Fetch a URL, automatically pay 402, retry — the core use case |
|
|
337
|
+
| `x402_session_start` | Pay once, get reusable session token for a base URL |
|
|
338
|
+
| `x402_session_fetch` | Make calls within an active session (no new payment) |
|
|
339
|
+
| `x402_session_status` | Inspect active sessions and TTL |
|
|
340
|
+
| `x402_session_end` | Explicitly close a session |
|
|
497
341
|
|
|
498
|
-
|
|
342
|
+
### Wallet & Spend Control
|
|
499
343
|
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
344
|
+
| Tool | What It Does |
|
|
345
|
+
|------|-------------|
|
|
346
|
+
| `get_wallet_info` | Address, balances, spend limits, queue depth |
|
|
347
|
+
| `send_payment` | Send ETH or ERC-20 via the AgentAccountV2 contract |
|
|
348
|
+
| `check_spend_limit` | Remaining spend limit for current period |
|
|
349
|
+
| `set_spend_policy` | Configure daily limits, per-tx caps, recipient allowlists |
|
|
350
|
+
| `check_budget` | Query on-chain remaining budget |
|
|
351
|
+
| `queue_approval` | Approve or cancel a queued transaction |
|
|
352
|
+
| `get_transaction_history` | On-chain event logs with filtering |
|
|
353
|
+
| `deploy_wallet` | Deploy a new AgentAccountV2 smart contract wallet |
|
|
504
354
|
|
|
505
|
-
|
|
506
|
-
{ "success": true, "burnTxHash": "0x...", "mintTxHash": "0x...", "amount": "500 USDC" }
|
|
507
|
-
```
|
|
355
|
+
### Token Operations
|
|
508
356
|
|
|
509
|
-
|
|
357
|
+
| Tool | What It Does |
|
|
358
|
+
|------|-------------|
|
|
359
|
+
| `lookup_token` | Token address + decimals by symbol and chain |
|
|
360
|
+
| `add_custom_token` | Register a custom ERC-20 in the token registry |
|
|
361
|
+
| `list_chain_tokens` | All registered tokens for a chain |
|
|
362
|
+
| `send_token` | Send any registry token (resolves address + decimals automatically) |
|
|
363
|
+
| `get_balances` | Token balances across one or more tokens |
|
|
510
364
|
|
|
511
|
-
###
|
|
365
|
+
### DeFi
|
|
512
366
|
|
|
513
|
-
|
|
367
|
+
| Tool | What It Does |
|
|
368
|
+
|------|-------------|
|
|
369
|
+
| `swap_tokens` | Uniswap V3 swap on Base, Arbitrum, Optimism, or Polygon |
|
|
370
|
+
| `bridge_usdc` | CCTP V2 cross-chain USDC bridge (10 EVM chains, ~12s) |
|
|
514
371
|
|
|
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. |
|
|
372
|
+
### Identity & Trust
|
|
521
373
|
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
// Response
|
|
528
|
-
{ "success": true, "policy": { "dailyLimitEth": "0.5", "perTxCapEth": "0.05" } }
|
|
529
|
-
```
|
|
374
|
+
| Tool | What It Does |
|
|
375
|
+
|------|-------------|
|
|
376
|
+
| `verify_agent_identity` | ERC-8004 on-chain identity verification |
|
|
377
|
+
| `get_reputation` | On-chain reputation score and history |
|
|
378
|
+
| `create_escrow` | Mutual-stake USDC escrow — both parties lock collateral |
|
|
530
379
|
|
|
531
380
|
---
|
|
532
381
|
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
Query the on-chain remaining budget for a given spender and token.
|
|
382
|
+
## Key Tool Examples
|
|
536
383
|
|
|
537
|
-
|
|
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) |
|
|
384
|
+
### `x402_pay` — The Core Tool
|
|
542
385
|
|
|
543
|
-
**Example:**
|
|
544
386
|
```json
|
|
545
387
|
// Request
|
|
546
|
-
{
|
|
388
|
+
{
|
|
389
|
+
"tool": "x402_pay",
|
|
390
|
+
"arguments": {
|
|
391
|
+
"url": "https://api.example.com/premium-data",
|
|
392
|
+
"max_payment_eth": "0.0002"
|
|
393
|
+
}
|
|
394
|
+
}
|
|
547
395
|
|
|
548
396
|
// Response
|
|
549
|
-
{ "
|
|
397
|
+
{ "status": 200, "body": "{ ... }" }
|
|
550
398
|
```
|
|
551
399
|
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
### `verify_agent_identity`
|
|
555
|
-
|
|
556
|
-
Verify an agent's on-chain identity using ERC-8004. Returns identity details including agent ID, URI, and registration file.
|
|
400
|
+
If the cost exceeds `max_payment_eth`, the tool returns an error before paying — no surprise charges.
|
|
557
401
|
|
|
558
|
-
|
|
559
|
-
| Name | Type | Required | Description |
|
|
560
|
-
|---|---|---|---|
|
|
561
|
-
| `agentAddress` | string | ✅ | Agent owner address (0x-prefixed) |
|
|
402
|
+
### `x402_session_start` — Pay Once for Multiple Calls
|
|
562
403
|
|
|
563
|
-
**Example:**
|
|
564
404
|
```json
|
|
565
405
|
// Request
|
|
566
|
-
{
|
|
406
|
+
{
|
|
407
|
+
"tool": "x402_session_start",
|
|
408
|
+
"arguments": {
|
|
409
|
+
"endpoint": "https://api.example.com/",
|
|
410
|
+
"ttl_seconds": 3600,
|
|
411
|
+
"label": "market-data-session"
|
|
412
|
+
}
|
|
413
|
+
}
|
|
567
414
|
|
|
568
415
|
// Response
|
|
569
|
-
{ "
|
|
416
|
+
{ "session_id": "sess_abc123", "token": "eyJ...", "expires_at": 1741000000 }
|
|
570
417
|
```
|
|
571
418
|
|
|
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
419
|
```json
|
|
585
|
-
//
|
|
586
|
-
{
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
420
|
+
// Subsequent calls — no new payment
|
|
421
|
+
{
|
|
422
|
+
"tool": "x402_session_fetch",
|
|
423
|
+
"arguments": {
|
|
424
|
+
"url": "https://api.example.com/stocks/AAPL",
|
|
425
|
+
"session_id": "sess_abc123"
|
|
426
|
+
}
|
|
427
|
+
}
|
|
590
428
|
```
|
|
591
429
|
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
### `create_escrow`
|
|
430
|
+
### `check_budget` — Know Before You Loop
|
|
595
431
|
|
|
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) |
|
|
607
|
-
|
|
608
|
-
**Example:**
|
|
609
432
|
```json
|
|
610
|
-
// Request
|
|
611
|
-
{ "
|
|
433
|
+
// Request — check before starting an expensive loop
|
|
434
|
+
{ "tool": "check_budget", "arguments": {} }
|
|
612
435
|
|
|
613
436
|
// Response
|
|
614
|
-
{
|
|
437
|
+
{
|
|
438
|
+
"remaining": "7.50 USDC",
|
|
439
|
+
"spent": "2.50 USDC",
|
|
440
|
+
"limit": "10.00 USDC",
|
|
441
|
+
"periodEnds": "2026-03-24T00:00:00Z"
|
|
442
|
+
}
|
|
615
443
|
```
|
|
616
444
|
|
|
617
445
|
---
|
|
618
446
|
|
|
619
447
|
## Supported Chains
|
|
620
448
|
|
|
621
|
-
| Chain | Chain ID |
|
|
622
|
-
|
|
623
|
-
| Base Mainnet | 8453 |
|
|
624
|
-
|
|
|
625
|
-
|
|
|
626
|
-
|
|
|
627
|
-
|
|
|
449
|
+
| Chain | Chain ID | Recommended For |
|
|
450
|
+
|-------|----------|----------------|
|
|
451
|
+
| Base Mainnet | 8453 | Everything — lowest gas, most x402 activity |
|
|
452
|
+
| Arbitrum One | 42161 | High-throughput swaps |
|
|
453
|
+
| Optimism | 10 | Low-cost transfers |
|
|
454
|
+
| Polygon | 137 | High-frequency micro-payments |
|
|
455
|
+
| Ethereum Mainnet | 1 | Identity, large settlements |
|
|
628
456
|
| 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 |
|
|
457
|
+
| Linea / Unichain / Sonic / Worldchain | various | Bridge, transfers |
|
|
458
|
+
| Base Sepolia | 84532 | Testing |
|
|
635
459
|
|
|
636
460
|
---
|
|
637
461
|
|
|
638
|
-
##
|
|
639
|
-
|
|
640
|
-
AgentPay MCP ships with **100+ pre-loaded tokens** across all supported chains via `agentwallet-sdk`'s TokenRegistry. Common tokens available on every major chain include:
|
|
462
|
+
## Security Model
|
|
641
463
|
|
|
642
|
-
-
|
|
643
|
-
- **Native Wrapped:** WETH, WBTC, WMATIC, WAVAX
|
|
644
|
-
- **DeFi:** UNI, AAVE, LINK, CRV, LDO
|
|
645
|
-
- **L2 Tokens:** cbETH, rETH, weETH, ezETH
|
|
464
|
+
**Non-custodial:** The agent signs all transactions locally with its private key. No third party holds or validates keys.
|
|
646
465
|
|
|
647
|
-
**
|
|
466
|
+
**On-chain enforcement:**
|
|
467
|
+
- Per-transaction caps — over-cap transactions queue for human approval via `queue_approval`
|
|
468
|
+
- Daily period limits — aggregate spending enforced by the AgentAccountV2 smart contract
|
|
469
|
+
- Recipient allowlists — restrict which addresses the agent can send to
|
|
648
470
|
|
|
649
|
-
|
|
471
|
+
**Role separation:**
|
|
472
|
+
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.
|
|
650
473
|
|
|
651
|
-
|
|
474
|
+
**x402 sessions:**
|
|
475
|
+
Session tokens are ECDSA-signed claims. Any x402 V2 server can independently verify them — no central session store required.
|
|
652
476
|
|
|
653
|
-
|
|
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`) |
|
|
477
|
+
**Minimal dependency footprint:**
|
|
478
|
+
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
479
|
|
|
663
480
|
---
|
|
664
481
|
|
|
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.
|
|
482
|
+
## MCP 2026 Compliance
|
|
670
483
|
|
|
671
|
-
|
|
484
|
+
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
485
|
|
|
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`
|
|
486
|
+
**Security posture documentation:** See [`docs/security-posture.md`](docs/security-posture.md) for the full compliance matrix covering:
|
|
676
487
|
|
|
677
|
-
|
|
488
|
+
- **CoSAI T9 (Financial Fraud)** — On-chain spend caps, merchant allowlists, and human-approval gates mitigate unauthorized agent spending
|
|
489
|
+
- **CoSAI T10 (Identity Spoofing)** — ERC-8004 agent identity verification + non-custodial key management prevent identity-based attacks
|
|
490
|
+
- **OAuth 2.1 + PKCE** — MCP server authentication supports OAuth 2.1 with PKCE for enterprise SSO integration (Azure AD, Okta)
|
|
491
|
+
- **MCP Audit Logging** — Every tool invocation logged with timestamp, parameters, outcome, and transaction hash (where applicable)
|
|
678
492
|
|
|
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.
|
|
493
|
+
For enterprise security teams evaluating MCP servers: the security posture document provides the artifact your audit process needs.
|
|
689
494
|
|
|
690
495
|
---
|
|
691
496
|
|
|
@@ -695,7 +500,7 @@ Session tokens are self-contained ECDSA-signed claims. Any server implementing x
|
|
|
695
500
|
┌─────────────────────────────────────────┐
|
|
696
501
|
│ AI Agent (Claude / Cursor / Windsurf) │
|
|
697
502
|
└────────────────┬────────────────────────┘
|
|
698
|
-
│ MCP (stdio/SSE)
|
|
503
|
+
│ MCP (stdio / SSE)
|
|
699
504
|
┌────────────────▼────────────────────────┐
|
|
700
505
|
│ AgentPay MCP Server │
|
|
701
506
|
│ ┌────────────┐ ┌────────────────────┐ │
|
|
@@ -706,28 +511,22 @@ Session tokens are self-contained ECDSA-signed claims. Any server implementing x
|
|
|
706
511
|
│ │ agentwallet-sdk v6.0.0 │ │
|
|
707
512
|
│ │ TokenRegistry SwapModule │ │
|
|
708
513
|
│ │ BridgeModule ERC8004Client │ │
|
|
709
|
-
│ │ ReputationClient MutualStake... │ │
|
|
710
514
|
│ └─────┬──────────────────────────────┘ │
|
|
711
515
|
└────────┼────────────────────────────────┘
|
|
712
516
|
│ viem + RPC
|
|
713
517
|
┌────────▼────────────────────────────────┐
|
|
714
518
|
│ AgentAccountV2 Smart Contract │
|
|
519
|
+
│ SpendingPolicy · Tx Queue │
|
|
715
520
|
│ (12 chains — Base, ETH, ARB, OP, ...) │
|
|
716
521
|
└─────────────────────────────────────────┘
|
|
717
522
|
```
|
|
718
523
|
|
|
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.
|
|
524
|
+
Transport: `stdio` by default (Claude Desktop, Cursor, Windsurf). SSE available for remote deployments.
|
|
724
525
|
|
|
725
526
|
---
|
|
726
527
|
|
|
727
528
|
## Contributing
|
|
728
529
|
|
|
729
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on submitting issues and pull requests.
|
|
730
|
-
|
|
731
530
|
```bash
|
|
732
531
|
git clone https://github.com/up2itnow0822/agentpay-mcp
|
|
733
532
|
cd agentpay-mcp
|
|
@@ -738,16 +537,16 @@ npm test
|
|
|
738
537
|
|
|
739
538
|
---
|
|
740
539
|
|
|
741
|
-
##
|
|
540
|
+
## Patent Notice
|
|
742
541
|
|
|
743
|
-
|
|
542
|
+
**Patent Pending** — USPTO provisional application filed March 2026: "Non-Custodial Multi-Chain Financial Infrastructure System for Autonomous AI Agents."
|
|
744
543
|
|
|
745
|
-
|
|
544
|
+
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.
|
|
746
545
|
|
|
747
|
-
|
|
546
|
+
---
|
|
748
547
|
|
|
749
|
-
|
|
548
|
+
## License
|
|
750
549
|
|
|
751
|
-
|
|
550
|
+
MIT © [AI Agent Economy](https://ai-agent-economy.com)
|
|
752
551
|
|
|
753
|
-
**
|
|
552
|
+
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.1",
|
|
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"
|