agentwallet-mcp 1.12.6 → 1.13.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 +382 -376
- package/build/index.js +284 -68
- package/build/local-solana.js +70 -4
- package/build/local-wallet.d.ts +1 -0
- package/build/local-wallet.js +74 -5
- package/build/ssrf-guard.d.ts +9 -0
- package/build/ssrf-guard.js +39 -2
- package/build/x402-eip3009.js +6 -1
- package/build/x402-payment.d.ts +70 -0
- package/build/x402-payment.js +158 -0
- package/build/x402-permit2.js +3 -1
- package/package.json +83 -69
package/README.md
CHANGED
|
@@ -1,377 +1,383 @@
|
|
|
1
|
-
# AgentWallet MCP Server
|
|
2
|
-
|
|
3
|
-
Permissionless wallet infrastructure for AI agents. Create wallets, sign transactions, and broadcast on-chain, on any EVM chain and Solana. Built-in guards. No KYC. The only AI agent wallet that accepts crypto for its own API fees.
|
|
4
|
-
|
|
5
|
-
**Your keys can stay on your machine.** Set one environment variable and every signature happens in your own process. No server sees the key, no company can freeze the wallet, and you can verify that claim by reading `src/local-wallet.ts` or by running the server with the API pointed at a closed port.
|
|
6
|
-
|
|
7
|
-
**No KYC. No KYT. No approval process. No transaction monitoring. No one can block your wallet. Pay with USDC on-chain, no credit card required.**
|
|
8
|
-
|
|
9
|
-
## Two modes
|
|
10
|
-
|
|
11
|
-
| | Local (self-custody) | Hosted (custodial) |
|
|
12
|
-
|---|---|---|
|
|
13
|
-
| Who holds the key | You, in your own process | Encrypted on AgentWallet servers |
|
|
14
|
-
| Set up | One env var, no account needed | API key |
|
|
15
|
-
| Chains | EVM + Solana | EVM + Solana |
|
|
16
|
-
| Can anyone freeze it | No | Yes, that is what pause is for |
|
|
17
|
-
| Spend guards | `AGENTWALLET_MAX_TX_NATIVE`, `AGENTWALLET_MAX_TX_SOL`, `AGENTWALLET_MAX_AUTOPAY` | Server-side limits, pause, rate limits |
|
|
18
|
-
| Paywalls, usage, billing | Needs an API key too | Included |
|
|
19
|
-
|
|
20
|
-
Run `wallet_mode` at any time and the server will tell you which one you are in, and which address it controls.
|
|
21
|
-
|
|
22
|
-
### Local signing in one variable
|
|
23
|
-
|
|
24
|
-
```json
|
|
25
|
-
{
|
|
26
|
-
"mcpServers": {
|
|
27
|
-
"agentwallet": {
|
|
28
|
-
"command": "npx",
|
|
29
|
-
"args": ["-y", "agentwallet-mcp"],
|
|
30
|
-
"env": {
|
|
31
|
-
"AGENTWALLET_PRIVATE_KEY": "0xyour_key",
|
|
32
|
-
"AGENTWALLET_RPC_8453": "https://your-own-rpc",
|
|
33
|
-
"AGENTWALLET_MAX_TX_NATIVE": "0.05"
|
|
34
|
-
}
|
|
35
|
-
}
|
|
36
|
-
}
|
|
37
|
-
}
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
Use `AGENTWALLET_KEYFILE=/path/to/key` instead if you would rather keep the key out of your shell config. The key is read once, never written to disk, never logged, and never included in an error message.
|
|
41
|
-
|
|
42
|
-
`AGENTWALLET_RPC_<chainId>` (or `AGENTWALLET_RPC_URL` for all chains) points at an endpoint you trust. Without it a public RPC is used, and a public RPC can see which addresses you ask about.
|
|
43
|
-
|
|
44
|
-
`AGENTWALLET_MAX_TX_NATIVE` is a per-transaction ceiling in native units (ETH, MATIC and so on). In hosted mode the server enforces limits; in local mode there is no server, so these guards are the only ones there are. Set them.
|
|
45
|
-
|
|
46
|
-
`AGENTWALLET_MAX_TX_TOKEN` is the equivalent ceiling for ERC-20 movement, in human units of the token. **Set this one too if you hold stablecoins.** The native cap cannot see a token transfer: an ERC-20 send carries `value = 0` with the amount in the calldata, so `AGENTWALLET_MAX_TX_NATIVE` alone leaves a USDC balance uncapped. `AGENTWALLET_MAX_TX_TOKEN` covers `transfer`, `transferFrom`, `approve`, `increaseAllowance`, Permit2 `approve`, and `deposit()` / `withdraw(uint256)` on the chain's own wrapped-native contract (so `wrap_eth` and `unwrap_eth` keep working under the cap), the approvals because an unbounded allowance is a drain waiting to happen. Any other calldata sent to a token contract or to Permit2 is refused while the cap is set, because the guard cannot price it; set `AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS=1` to allow such calls deliberately. Calls to other contracts (routers, bridges) pass, since they can only pull what an approval already allowed; a contract counts as "other" only when it demonstrably declines `decimals()`, so an absurd or malformed answer, or an RPC that cannot be reached, refuses rather than allows. Decimals are resolved locally from the trusted registry, then the token's own `decimals()`; a token that resolves neither way is evaluated at 0 decimals, the only value that cannot fail open.
|
|
47
|
-
|
|
48
|
-
### Solana local signing
|
|
49
|
-
|
|
50
|
-
```json
|
|
51
|
-
"env": {
|
|
52
|
-
"AGENTWALLET_SOLANA_KEY": "[12,34...]",
|
|
53
|
-
"AGENTWALLET_SOLANA_RPC": "https://your-own-rpc",
|
|
54
|
-
"AGENTWALLET_MAX_TX_SOL": "1"
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
- **
|
|
78
|
-
- **
|
|
79
|
-
- **
|
|
80
|
-
- **
|
|
81
|
-
- **
|
|
82
|
-
- **
|
|
83
|
-
- **
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
-
|
|
89
|
-
-
|
|
90
|
-
-
|
|
91
|
-
- **
|
|
92
|
-
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
"
|
|
110
|
-
"
|
|
111
|
-
|
|
112
|
-
"
|
|
113
|
-
"
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
}
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
>
|
|
122
|
-
>
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
-e
|
|
130
|
-
-e
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
"
|
|
145
|
-
"
|
|
146
|
-
|
|
147
|
-
"
|
|
148
|
-
"
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
174
|
-
| `
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
181
|
-
| `
|
|
182
|
-
| `
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
|
201
|
-
|
|
|
202
|
-
|
|
|
203
|
-
|
|
|
204
|
-
|
|
|
205
|
-
|
|
|
206
|
-
|
|
|
207
|
-
|
|
|
208
|
-
|
|
|
209
|
-
| Solana
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
|
294
|
-
|
|
|
295
|
-
|
|
|
296
|
-
|
|
|
297
|
-
|
|
|
298
|
-
|
|
|
299
|
-
|
|
|
300
|
-
|
|
|
301
|
-
|
|
|
302
|
-
| x402
|
|
303
|
-
|
|
|
304
|
-
|
|
|
305
|
-
|
|
|
306
|
-
|
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
- **
|
|
324
|
-
- **
|
|
325
|
-
- **
|
|
326
|
-
- **
|
|
327
|
-
- **
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
1
|
+
# AgentWallet MCP Server
|
|
2
|
+
|
|
3
|
+
Permissionless wallet infrastructure for AI agents. Create wallets, sign transactions, and broadcast on-chain, on any EVM chain and Solana. Built-in guards. No KYC. The only AI agent wallet that accepts crypto for its own API fees.
|
|
4
|
+
|
|
5
|
+
**Your keys can stay on your machine.** Set one environment variable and every signature happens in your own process. No server sees the key, no company can freeze the wallet, and you can verify that claim by reading `src/local-wallet.ts` or by running the server with the API pointed at a closed port.
|
|
6
|
+
|
|
7
|
+
**No KYC. No KYT. No approval process. No transaction monitoring. No one can block your wallet. Pay with USDC on-chain, no credit card required.**
|
|
8
|
+
|
|
9
|
+
## Two modes
|
|
10
|
+
|
|
11
|
+
| | Local (self-custody) | Hosted (custodial) |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| Who holds the key | You, in your own process | Encrypted on AgentWallet servers |
|
|
14
|
+
| Set up | One env var, no account needed | API key |
|
|
15
|
+
| Chains | EVM + Solana | EVM + Solana |
|
|
16
|
+
| Can anyone freeze it | No | Yes, that is what pause is for |
|
|
17
|
+
| Spend guards | `AGENTWALLET_MAX_TX_NATIVE`, `AGENTWALLET_MAX_TX_TOKEN`, `AGENTWALLET_MAX_TX_SOL`, `AGENTWALLET_MAX_AUTOPAY` | Server-side limits, pause, rate limits |
|
|
18
|
+
| Paywalls, usage, billing | Needs an API key too | Included |
|
|
19
|
+
|
|
20
|
+
Run `wallet_mode` at any time and the server will tell you which one you are in, and which address it controls.
|
|
21
|
+
|
|
22
|
+
### Local signing in one variable
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{
|
|
26
|
+
"mcpServers": {
|
|
27
|
+
"agentwallet": {
|
|
28
|
+
"command": "npx",
|
|
29
|
+
"args": ["-y", "agentwallet-mcp"],
|
|
30
|
+
"env": {
|
|
31
|
+
"AGENTWALLET_PRIVATE_KEY": "0xyour_key",
|
|
32
|
+
"AGENTWALLET_RPC_8453": "https://your-own-rpc",
|
|
33
|
+
"AGENTWALLET_MAX_TX_NATIVE": "0.05"
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Use `AGENTWALLET_KEYFILE=/path/to/key` instead if you would rather keep the key out of your shell config. The key is read once, never written to disk, never logged, and never included in an error message.
|
|
41
|
+
|
|
42
|
+
`AGENTWALLET_RPC_<chainId>` (or `AGENTWALLET_RPC_URL` for all chains) points at an endpoint you trust. Without it a public RPC is used, and a public RPC can see which addresses you ask about.
|
|
43
|
+
|
|
44
|
+
`AGENTWALLET_MAX_TX_NATIVE` is a per-transaction ceiling in native units (ETH, MATIC and so on). In hosted mode the server enforces limits; in local mode there is no server, so these guards are the only ones there are. Set them.
|
|
45
|
+
|
|
46
|
+
`AGENTWALLET_MAX_TX_TOKEN` is the equivalent ceiling for ERC-20 movement, in human units of the token. **Set this one too if you hold stablecoins.** The native cap cannot see a token transfer: an ERC-20 send carries `value = 0` with the amount in the calldata, so `AGENTWALLET_MAX_TX_NATIVE` alone leaves a USDC balance uncapped. `AGENTWALLET_MAX_TX_TOKEN` covers `transfer`, `transferFrom`, `approve`, `increaseAllowance`, Permit2 `approve`, and `deposit()` / `withdraw(uint256)` on the chain's own wrapped-native contract (so `wrap_eth` and `unwrap_eth` keep working under the cap), the approvals because an unbounded allowance is a drain waiting to happen. Any other calldata sent to a token contract or to Permit2 is refused while the cap is set, because the guard cannot price it; set `AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS=1` to allow such calls deliberately. `increaseAllowance` is judged on the resulting total: the current allowance is read first and the call refuses if it cannot be, so two compliant increments cannot stack a standing allowance above the cap. Calls to other contracts (routers, bridges) pass, since they can only pull what an approval already allowed; a contract counts as "other" only when it demonstrably declines `decimals()`, so an absurd or malformed answer, or an RPC that cannot be reached, refuses rather than allows. Decimals are resolved locally from the trusted registry, then the token's own `decimals()`; a token that resolves neither way is evaluated at 0 decimals, the only value that cannot fail open. For a token outside the registry the RPC is the only source of decimals, and an RPC you do not control could scale the amount and the cap together; pin such tokens with `AGENTWALLET_TOKEN_DECIMALS` (for example `8453:0x<token>=6`) and the pin is used everywhere the RPC's answer would have been.
|
|
47
|
+
|
|
48
|
+
### Solana local signing
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
"env": {
|
|
52
|
+
"AGENTWALLET_SOLANA_KEY": "[12,34...]",
|
|
53
|
+
"AGENTWALLET_SOLANA_RPC": "https://your-own-rpc",
|
|
54
|
+
"AGENTWALLET_MAX_TX_SOL": "1",
|
|
55
|
+
"AGENTWALLET_MAX_TX_TOKEN": "25"
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Accepts whichever format you already have: a `solana-keygen` id.json array, a base58 secret key as exported by Phantom, or base64. Use `AGENTWALLET_SOLANA_KEYFILE` to point at a file instead. Native SOL and SPL token transfers are both signed locally, and a missing associated token account is created for the recipient automatically.
|
|
60
|
+
|
|
61
|
+
Set either key, or both. They are independent: run EVM locally and Solana hosted, or the reverse.
|
|
62
|
+
|
|
63
|
+
**An operation with no matching local key is refused, never silently routed to the hosted signer.** If you have an EVM key configured and ask for a Solana transfer with no Solana key, the server stops and tells you which variable is missing. Quietly moving funds onto a key you do not hold, while you believe you are in self-custody, is the worst thing this server could do.
|
|
64
|
+
|
|
65
|
+
### About the dependency tree
|
|
66
|
+
|
|
67
|
+
Local signing uses [viem](https://viem.sh) for EVM and `@solana/web3.js` for Solana, plus `bs58` for key parsing. SPL instructions are built by hand rather than with `@solana/spl-token`, because that package pulls in `bigint-buffer`, which carries a high severity buffer overflow advisory. A wallet has no business shipping that to save a dozen lines of instruction encoding.
|
|
68
|
+
|
|
69
|
+
`npm audit` currently reports issues inside `@modelcontextprotocol/sdk`'s HTTP transport dependencies. This server speaks stdio, so that code never loads, and the SDK is not something this package can patch. Run the audit yourself. Publishing a tree you can inspect is the point.
|
|
70
|
+
|
|
71
|
+
<p align="center">
|
|
72
|
+
<img src="assets/demo.svg" alt="AgentWallet demo, AI agent pays x402 invoice automatically" width="800">
|
|
73
|
+
</p>
|
|
74
|
+
|
|
75
|
+
## Features
|
|
76
|
+
|
|
77
|
+
- **34 MCP tools**: create wallets, send transactions, approve tokens, wrap ETH, transfer SPL tokens, pay and accept x402 payments, verify custody mode, and more
|
|
78
|
+
- **EVM + Solana**: Ethereum, Base, Polygon, BSC, Arbitrum, Optimism, Avalanche, Zora, PulseChain, Solana, and any other EVM-compatible chain
|
|
79
|
+
- **SOL + SPL tokens**: native SOL transfers and SPL token transfers (USDC, USDT, etc.) with automatic account creation
|
|
80
|
+
- **Built-in guards**: in hosted mode, daily spending limits, gas price protection, emergency pause and rate limiting are enforced server-side by default. In local mode your protection is the per-transaction caps you set (`AGENTWALLET_MAX_TX_NATIVE`, `AGENTWALLET_MAX_TX_TOKEN`, `AGENTWALLET_MAX_TX_SOL`, `AGENTWALLET_MAX_AUTOPAY`). x402 replay protection and on-chain verification apply either way
|
|
81
|
+
- **x402 payments**: pay for x402-enabled APIs automatically, or accept x402 payments on your own endpoints (EVM and Solana)
|
|
82
|
+
- **Self-custody option**: run local mode and the key never leaves your machine. In hosted mode, keys are encrypted at rest, decrypted only during signing, and zeroed from memory immediately after. Either way you can export and walk away.
|
|
83
|
+
- **Permissionless**: No KYC. No KYT. No identity verification. No approval process. No compliance gatekeeping. Sign up, get an API key, and start transacting immediately.
|
|
84
|
+
- **30-second setup**: three lines of config. No SDK to install. No dependencies to manage.
|
|
85
|
+
|
|
86
|
+
## Pricing
|
|
87
|
+
|
|
88
|
+
- **$0.00345 per operation**
|
|
89
|
+
- **6,000 free operations/month**
|
|
90
|
+
- **$0.0005 per x402 verification**
|
|
91
|
+
- **1,000 free x402 verifications/month**
|
|
92
|
+
- **Pay with USDC on-chain** via x402, no credit card required
|
|
93
|
+
- No monthly fee, no tiers, just pay as you go
|
|
94
|
+
|
|
95
|
+
Competitor comparisons are kept at [hifriendbot.com/wallet/#pricing](https://hifriendbot.com/wallet/#pricing) with the date they were last verified. They live there rather than here because a published npm README cannot be corrected when someone else changes their prices.
|
|
96
|
+
|
|
97
|
+
## Quick Start
|
|
98
|
+
|
|
99
|
+
Get your free API key at [hifriendbot.com/wallet](https://hifriendbot.com/wallet), no credit card required, no KYC, no approval wait.
|
|
100
|
+
|
|
101
|
+
### Claude Desktop / OpenClaw
|
|
102
|
+
|
|
103
|
+
Add to your config:
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"mcpServers": {
|
|
108
|
+
"agentwallet": {
|
|
109
|
+
"command": "npx",
|
|
110
|
+
"args": ["-y", "agentwallet-mcp"],
|
|
111
|
+
"env": {
|
|
112
|
+
"AGENTWALLET_USER": "your_username",
|
|
113
|
+
"AGENTWALLET_PASS": "your_api_key",
|
|
114
|
+
"AGENTWALLET_WALLET_ID": "1"
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
> `AGENTWALLET_WALLET_ID` is optional. Set it to enable x402 auto-pay: when you exceed the free tier without a credit card, the MCP server automatically pays for operations with USDC from this wallet.
|
|
122
|
+
>
|
|
123
|
+
> **Auto-pay safety cap.** `AGENTWALLET_MAX_AUTOPAY` (optional, default `1`) is the most one x402 payment may authorize, in stablecoin units: `1` means one dollar. It prices registry stablecoins only (USDC, USDT, USDbC, DAI on the supported chains, USDC and USDT on Solana). A requirement in the chain's native asset or in any other token is refused, because "1" measured in ETH is a few thousand dollars; list such assets in `AGENTWALLET_AUTOPAY_ASSETS` (comma-separated addresses or mints, or the word `native`) to allow them, and the cap then applies in that asset's own units. Any requirement above the cap is rejected instead of paid, so a malformed or tampered payment requirement cannot drain the wallet. This automatic path settles `exact` requirements only; an `upto` offer from the API is refused before any wallet call, because paying a usage maximum upfront is not what the offer means (use `pay_x402`, which signs a Permit2 authorization for it). The cap is the operator's ceiling: a `max_payment` argument can lower it for one call but never raise it. Raise the variable itself if you genuinely need larger automatic payments (for example `"5"` for up to 5 USDC per call).
|
|
124
|
+
|
|
125
|
+
### Claude Code
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
claude mcp add agentwallet \
|
|
129
|
+
-e AGENTWALLET_USER=your_username \
|
|
130
|
+
-e AGENTWALLET_PASS=your_api_key \
|
|
131
|
+
-e AGENTWALLET_WALLET_ID=1 \
|
|
132
|
+
-- npx -y agentwallet-mcp
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### VS Code
|
|
136
|
+
|
|
137
|
+
Add to your settings:
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"mcp": {
|
|
142
|
+
"servers": {
|
|
143
|
+
"agentwallet": {
|
|
144
|
+
"command": "npx",
|
|
145
|
+
"args": ["-y", "agentwallet-mcp"],
|
|
146
|
+
"env": {
|
|
147
|
+
"AGENTWALLET_USER": "your_username",
|
|
148
|
+
"AGENTWALLET_PASS": "your_api_key",
|
|
149
|
+
"AGENTWALLET_WALLET_ID": "1"
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Tools
|
|
158
|
+
|
|
159
|
+
| Tool | Description |
|
|
160
|
+
|------|-------------|
|
|
161
|
+
| `create_wallet` | Create a new EVM or Solana wallet |
|
|
162
|
+
| `list_wallets` | List all your wallets |
|
|
163
|
+
| `get_wallet` | Get wallet details by ID |
|
|
164
|
+
| `get_balance` | Check native token balance on any chain |
|
|
165
|
+
| `get_token_balance` | Check ERC-20 or SPL token balance |
|
|
166
|
+
| `get_token_info` | Get ERC-20 token name, symbol, and decimals |
|
|
167
|
+
| `transfer` | Send native tokens (ETH, SOL, POL, BNB, etc.) |
|
|
168
|
+
| `transfer_token` | Send ERC-20 or SPL tokens (USDC, USDT, etc.) |
|
|
169
|
+
| `send_transaction` | Sign and broadcast a raw transaction |
|
|
170
|
+
| `sign_transaction` | Sign a transaction without broadcasting |
|
|
171
|
+
| `call_contract` | Read-only contract call (eth_call) |
|
|
172
|
+
| `approve_token` | Approve ERC-20 token spending for DeFi |
|
|
173
|
+
| `get_allowance` | Check ERC-20 token allowance |
|
|
174
|
+
| `wrap_eth` | Wrap native tokens to WETH/WAVAX/etc. |
|
|
175
|
+
| `unwrap_eth` | Unwrap WETH back to native tokens |
|
|
176
|
+
| `pay_x402` | Pay x402 invoices (exact via EIP-3009, upto via Permit2), with approvals above the cap |
|
|
177
|
+
| `check_approval` | Status of a human approval created by an over-cap `pay_x402` |
|
|
178
|
+
| `approve_permit2` | One-time token approval to Permit2 for `upto` endpoints |
|
|
179
|
+
| `check_token_risk` | Honeypot, tax, owner-power and holder-concentration flags for a token |
|
|
180
|
+
| `create_paywall` | Create an x402 paywall to charge for a resource |
|
|
181
|
+
| `list_paywalls` | List all your x402 paywalls |
|
|
182
|
+
| `get_paywall` | Get paywall details by ID |
|
|
183
|
+
| `update_paywall` | Update paywall pricing, resource, or status |
|
|
184
|
+
| `delete_paywall` | Delete a paywall |
|
|
185
|
+
| `get_paywall_payments` | View payment history for a paywall |
|
|
186
|
+
| `get_x402_revenue` | Aggregate revenue stats across all paywalls |
|
|
187
|
+
| `wallet_mode` | Report whether signing is local (self-custody) or hosted, and which address is in use |
|
|
188
|
+
| `export_wallet_key` | How to export a hosted wallet key and move to self-custody |
|
|
189
|
+
| `buy_verification_credits` | Buy x402 verification credits with USDC on-chain |
|
|
190
|
+
| `get_usage` | Check your monthly usage and billing |
|
|
191
|
+
| `get_chains` | List all supported chains |
|
|
192
|
+
| `pause_wallet` | Emergency pause a wallet |
|
|
193
|
+
| `unpause_wallet` | Resume a paused wallet |
|
|
194
|
+
| `delete_wallet` | Delete a wallet |
|
|
195
|
+
|
|
196
|
+
## Supported Chains
|
|
197
|
+
|
|
198
|
+
| Chain | ID | Native Token | Stablecoin |
|
|
199
|
+
|-------|-----|-------------|------------|
|
|
200
|
+
| Ethereum | 1 | ETH | USDC |
|
|
201
|
+
| Base | 8453 | ETH | USDC |
|
|
202
|
+
| Polygon | 137 | POL | USDC |
|
|
203
|
+
| BSC | 56 | BNB | USDT |
|
|
204
|
+
| Arbitrum | 42161 | ETH | USDC |
|
|
205
|
+
| Optimism | 10 | ETH | USDC |
|
|
206
|
+
| Avalanche | 43114 | AVAX | USDC |
|
|
207
|
+
| Zora | 7777777 | ETH | USDC |
|
|
208
|
+
| PulseChain | 369 | PLS | USDC |
|
|
209
|
+
| Solana | 900 | SOL | USDC |
|
|
210
|
+
| Solana Devnet | 901 | SOL | USDC |
|
|
211
|
+
|
|
212
|
+
## Use Case: GuessMarket
|
|
213
|
+
|
|
214
|
+
Pair with [guessmarket-mcp](https://www.npmjs.com/package/guessmarket-mcp) to let your AI agent trade prediction markets:
|
|
215
|
+
|
|
216
|
+
1. Create a wallet on Base
|
|
217
|
+
2. Approve USDC spending
|
|
218
|
+
3. Buy YES/NO shares on prediction markets
|
|
219
|
+
4. Provide liquidity and earn trading fees
|
|
220
|
+
5. Claim winnings
|
|
221
|
+
|
|
222
|
+
All on-chain. All through MCP. No frontend needed.
|
|
223
|
+
|
|
224
|
+
## x402 Payments
|
|
225
|
+
|
|
226
|
+
AgentWallet speaks the [x402 open payment standard](https://x402.org) the way the spec defines it. When your Ai agent hits an API that answers HTTP 402, `pay_x402` does the whole flow:
|
|
227
|
+
|
|
228
|
+
1. Fetches the URL and reads the payment requirements, from the v2 `PAYMENT-REQUIRED` header or the v1 JSON body.
|
|
229
|
+
2. Picks an `exact` option (you can steer it with `prefer_chain`).
|
|
230
|
+
3. Signs an **EIP-3009 `TransferWithAuthorization`** for exactly that amount. Nothing is broadcast and no gas is paid by the payer; the endpoint's facilitator settles it on-chain.
|
|
231
|
+
4. Retries the request with the payment header (`PAYMENT-SIGNATURE` for v2, `X-PAYMENT` for v1).
|
|
232
|
+
5. Returns the response, the settlement receipt (`PAYMENT-RESPONSE` / `X-PAYMENT-RESPONSE`) and, if the endpoint declined, its stated reason in `retry_error`.
|
|
233
|
+
|
|
234
|
+
Verified against Coinbase's public facilitator (`isValid: true` for v1 and v2 payloads) and live x402 servers on Base. Works in both custody modes: the local key signs in-process; hosted wallets sign through `POST /wallets/{id}/x402/authorize`, a narrow endpoint that only ever signs this one struct and runs the same pause and token-cap checks as a transfer.
|
|
235
|
+
|
|
236
|
+
```
|
|
237
|
+
pay_x402(
|
|
238
|
+
url="https://api.example.com/premium-data",
|
|
239
|
+
wallet_id=1,
|
|
240
|
+
max_payment="1.00"
|
|
241
|
+
)
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
`max_payment` lowers the cap for one call. It cannot raise it: `AGENTWALLET_MAX_AUTOPAY` (default `1`) is the operator's ceiling, and a `max_payment` above it is ignored and reported back as `max_payment_ignored`, so neither a malicious 402 endpoint nor a prompt-injected agent can authorize more than the operator allowed. Hosted wallets can go above the ceiling only through an emailed owner approval (below); local mode raises the variable. In local mode `AGENTWALLET_MAX_TX_TOKEN` applies to authorizations too, because an authorization is a transfer somebody else executes. Authorizations are valid for at most `AGENTWALLET_X402_MAX_TIMEOUT` seconds (default 3600) however long the endpoint asks for, and a repeat `pay_x402` call for the same endpoint, amount and recipient inside that window re-sends the earlier signature instead of signing a second one (its nonce is single-use, so a server that withheld the resource after settling cannot be paid twice; pass `fresh_authorization=true` to force a new one). The label shown for the asset comes from the registry or the chain, never from the 402 body.
|
|
245
|
+
|
|
246
|
+
**Schemes.** `exact` (EIP-3009, gasless for the payer) is preferred and works on every EVM chain AgentWallet knows. `upto` (a Permit2 maximum the seller settles at actual usage) is signed as a `PermitWitnessTransferFrom` bound to the endpoint's facilitator; it needs a one-time `approve_permit2` per token (or `AGENTWALLET_PERMIT2_AUTO_APPROVE=1`). An `upto` option without `extra.facilitatorAddress` is refused, never approximated with an upfront transfer. Native-asset and Solana requests, and AgentWallet's own paywalls, are paid by an on-chain transfer proved by transaction hash, which is what those servers verify.
|
|
247
|
+
|
|
248
|
+
**Approvals above the cap.** On a hosted wallet, a payment above the cap does not have to fail. With `request_approval` (default on; `AGENTWALLET_APPROVALS=0` turns it off) the wallet owner gets an email with approve and deny links, `pay_x402` returns an `approval_id`, and the agent retries with it once `check_approval` says approved. An approval is bound to one wallet, chain, asset, recipient and maximum, expires in 24 hours, and is consumed by one signature. Local mode has no approval channel: the caps in your environment are the policy.
|
|
249
|
+
|
|
250
|
+
**Asset risk.** `check_token_risk` (and every `approve_token` result) reports honeypot, tax, owner-power, verified-source, holder-concentration and liquidity flags from GoPlus Security, with an on-chain fallback. A warning for the caller to weigh, never a block.
|
|
251
|
+
|
|
252
|
+
**Proof.** Real settlements are listed in [PAYMENTS.md](https://github.com/hifriendbot/agentwallet-mcp/blob/main/PAYMENTS.md); the first is a 0.02 USDC `exact` payment on Base with the facilitator paying the gas.
|
|
253
|
+
|
|
254
|
+
## Pay any x402 API from Claude in three steps
|
|
255
|
+
|
|
256
|
+
1. Add the server (one of the snippets under Quick Start). Self-custody: set `AGENTWALLET_PRIVATE_KEY` to a key that holds USDC on Base. Hosted: `AGENTWALLET_USER` and `AGENTWALLET_PASS` from hifriendbot.com/wallet.
|
|
257
|
+
2. Ask: *"Use pay_x402 to POST https://api.ozdreamtools.de/api/holidays with body {"year":2026,"state":"BY"} and a max_payment of 0.05."*
|
|
258
|
+
3. Read the result: `payment_made: true`, the amount, `payment_method`, and `settlement.transaction`, the on-chain hash. No ETH needed for `exact`: the endpoint's facilitator pays the gas.
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
**Token domains.** The EIP-712 domain comes from the endpoint's `extra.name` / `extra.version`, then a short registry of USDC deployments, then the token contract's own `name()` / `version()`. If none of those answer, the payment is refused rather than signed with a guessed domain.
|
|
262
|
+
|
|
263
|
+
**Delegated payers.** If the paying address is an EIP-7702 delegated account, `pay_x402` reports it in `payer_delegation` (the delegate and whether it answers ERC-1271). A delegate without ERC-1271 is declined by facilitators that check account code before recovering the signer, and the reason they return reads like a signature fault; the warning names the real cause. Pay from a plain EOA for reliable settlement.
|
|
264
|
+
|
|
265
|
+
## x402 Acceptance
|
|
266
|
+
|
|
267
|
+
AgentWallet also lets you **accept** x402 payments. Create a paywall, point it at any resource, and get a public URL that charges agents automatically:
|
|
268
|
+
|
|
269
|
+
```
|
|
270
|
+
create_paywall(
|
|
271
|
+
wallet_id=1,
|
|
272
|
+
name="Premium API",
|
|
273
|
+
amount="0.01",
|
|
274
|
+
token_name="USDC",
|
|
275
|
+
token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
|
|
276
|
+
chain_id=8453,
|
|
277
|
+
resource_url="https://your-api.com/data"
|
|
278
|
+
)
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
When an agent hits the paywall URL:
|
|
282
|
+
1. Gets back HTTP 402 with payment requirements
|
|
283
|
+
2. Pays on-chain using `pay_x402` (or any x402-compatible client)
|
|
284
|
+
3. Retries with proof of payment
|
|
285
|
+
4. Receives the protected content
|
|
286
|
+
|
|
287
|
+
On-chain verification ensures every payment is real. Replay protection prevents double-spending. Revenue tracking shows you who paid, how much, and when. 1,000 free verifications/month, then $0.0005 each. See the [pricing comparison](https://hifriendbot.com/wallet/#pricing) for how that stacks up.
|
|
288
|
+
|
|
289
|
+
## How We Compare
|
|
290
|
+
|
|
291
|
+
| Feature | Coinbase CDP | AgentWallet |
|
|
292
|
+
|---------|-------------|-------------|
|
|
293
|
+
| Setup Time | Install SDK + configure | **3 lines of config** |
|
|
294
|
+
| Approval Process | Identity verification required | **None, instant access** |
|
|
295
|
+
| KYC Required | Yes | **No** |
|
|
296
|
+
| KYT / Transaction Monitoring | Yes | **No** |
|
|
297
|
+
| Can Block Your Wallet | Yes | **No** |
|
|
298
|
+
| Built-in Guards | Yes (requires setup) | **Yes (hosted: active by default; local: env caps you set)** |
|
|
299
|
+
| Free Operations / Month | 5,000 | **6,000** |
|
|
300
|
+
| Cost Per Operation | $0.005 | **$0.00345** |
|
|
301
|
+
| x402 Verification Cost | $0.001 | **$0.0005** |
|
|
302
|
+
| Free x402 Verifications / Month | 1,000 | **1,000** |
|
|
303
|
+
| x402 Acceptance (Paywalls) | No | **Yes** |
|
|
304
|
+
| Pay for API Fees with Crypto | No (credit card only) | **Yes (USDC via x402)** |
|
|
305
|
+
| Supported Chains | 8 EVM + Solana | **Any EVM + Solana** |
|
|
306
|
+
| Token Tools | Yes | **ERC-20 + SPL (34 tools)** |
|
|
307
|
+
| MCP Server | Yes | **Yes** |
|
|
308
|
+
|
|
309
|
+
## Pay with Crypto, No Credit Card Required
|
|
310
|
+
|
|
311
|
+
AgentWallet is the only AI agent wallet infrastructure that accepts crypto for its own API fees. Every competitor, Coinbase CDP, Circle, MoonPay, Crossmint, Turnkey, requires a credit card or monthly invoice. With AgentWallet, your agent can pay for operations with USDC on-chain via the x402 protocol. No credit card, no invoice, no billing portal. Just on-chain payments.
|
|
312
|
+
|
|
313
|
+
When your agent exceeds the free tier (6,000 ops/month) without a credit card configured, the API returns HTTP 402 with USDC payment instructions. Your agent pays on-chain, retries with proof of payment, and the operation executes. Fully automated via the MCP server.
|
|
314
|
+
|
|
315
|
+
You can also pre-purchase x402 verification credits with USDC using the `buy_verification_credits` tool, keeping your paywalls running beyond the free 1,000 verifications/month without needing a credit card.
|
|
316
|
+
|
|
317
|
+
## Built-in Guards
|
|
318
|
+
|
|
319
|
+
Which guards apply depends on who holds the key.
|
|
320
|
+
|
|
321
|
+
**Hosted mode** (the server holds the key): every guard below is active by default, no configuration required.
|
|
322
|
+
|
|
323
|
+
- **Encrypted at rest**: private keys encrypted before storage and never leave the server
|
|
324
|
+
- **Memory zeroing**: keys wiped from memory immediately after every signing operation
|
|
325
|
+
- **Daily spending limits**: set a per-wallet daily cap in USD, enforced by the server on every transaction
|
|
326
|
+
- **Gas price protection**: transactions blocked when gas prices spike above safe thresholds
|
|
327
|
+
- **Emergency pause**: instantly freeze any wallet or all wallets with one click
|
|
328
|
+
- **Rate limiting**: API requests capped per minute to prevent abuse and brute force attacks
|
|
329
|
+
|
|
330
|
+
**Local mode** (you hold the key): there is no server in the signing path, so the server-side limits and pause above cannot see or stop a locally signed transaction, and nobody (including us) can freeze a local wallet. Your protection is the per-transaction caps enforced inside your own process before anything is signed. Set them before you fund the wallet; an unset cap means no limit.
|
|
331
|
+
|
|
332
|
+
- `AGENTWALLET_MAX_TX_NATIVE`: ceiling per transaction in native units (ETH, MATIC, and so on)
|
|
332
333
|
- `AGENTWALLET_MAX_TX_TOKEN`: ceiling per ERC-20 transfer or approval, in human units of the token
|
|
333
|
-
- `AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS`: set to `1` to let calldata the token cap cannot price reach a token contract or Permit2 (refused by default while the cap is set)
|
|
334
|
-
- `
|
|
335
|
-
- `
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
334
|
+
- `AGENTWALLET_ALLOW_UNKNOWN_TOKEN_CALLS`: set to `1` to let calldata the token cap cannot price reach a token contract or Permit2 (refused by default while the cap is set)
|
|
335
|
+
- `AGENTWALLET_TOKEN_DECIMALS`: pin decimals for tokens outside the registry (`8453:0x<token>=6,<mint>=9`); a pin is used for amounts and caps instead of asking the RPC
|
|
336
|
+
- `AGENTWALLET_MAX_TX_SOL`: ceiling per native SOL transfer (also charged for the rent of a recipient token account an SPL send has to create). It does not cover SPL token amounts: `AGENTWALLET_MAX_TX_TOKEN` does, on Solana as on EVM
|
|
337
|
+
- `AGENTWALLET_MAX_AUTOPAY`: ceiling per x402 auto-payment in stablecoin units (default `1`); `AGENTWALLET_AUTOPAY_ASSETS` opts native or non-stable assets in; `AGENTWALLET_X402_MAX_TIMEOUT` bounds how long a signed authorization stays valid (default 3600 seconds)
|
|
338
|
+
- `AGENTWALLET_SOLANA_RPC_<chainId>` (or `AGENTWALLET_SOLANA_RPC` for all clusters): the RPC's genesis hash is checked against the chain id before anything is sent, and an EVM RPC's `eth_chainId` likewise, so one URL cannot silently serve a different network than the one requested
|
|
339
|
+
- `AGENTWALLET_TOKEN_RISK=0`: skip the GoPlus lookup `approve_token` performs (a third-party call that reveals which token you are about to approve)
|
|
340
|
+
|
|
341
|
+
All cap variables are validated at startup; a typo stops the server rather than reading as "no limit". `wallet_mode` reports every guard, including the token cap and whether unknown token calls are allowed. Node.js 22.19 or newer is required.
|
|
342
|
+
|
|
343
|
+
**Either mode**, for x402 paywalls you run through the hosted API:
|
|
344
|
+
|
|
345
|
+
- **Replay protection**: every x402 payment verified on-chain with unique transaction tracking
|
|
346
|
+
- **On-chain verification**: x402 payments verified directly on the blockchain with finalized commitment
|
|
347
|
+
|
|
348
|
+
Bug bounty program: $50 to $500 for responsible disclosure ([details](https://hifriendbot.com/wallet)).
|
|
349
|
+
|
|
350
|
+
## Links
|
|
351
|
+
|
|
352
|
+
- **Website:** [hifriendbot.com/wallet](https://hifriendbot.com/wallet)
|
|
353
|
+
- **npm:** [agentwallet-mcp](https://www.npmjs.com/package/agentwallet-mcp)
|
|
354
|
+
- **Security:** [security@hifriendbot.com](mailto:security@hifriendbot.com), policy and disclosure history in [SECURITY.md](https://github.com/hifriendbot/agentwallet-mcp/blob/main/SECURITY.md)
|
|
355
|
+
|
|
356
|
+
|
|
357
|
+
## Security
|
|
358
|
+
|
|
359
|
+
`pay_x402` validates the target URL before every outbound request and again on
|
|
360
|
+
each redirect hop. IP literals are canonicalized (including IPv4-mapped IPv6
|
|
361
|
+
such as `[::ffff:127.0.0.1]`) and hostnames are resolved, with loopback,
|
|
362
|
+
private, link-local, carrier-grade NAT, multicast and cloud-metadata
|
|
363
|
+
destinations refused.
|
|
364
|
+
|
|
365
|
+
Validation and connection use the same DNS answer. Each hop resolves once, and
|
|
366
|
+
the socket is pinned to an address from that answer, so a hostname cannot
|
|
367
|
+
resolve public for the check and private for the connection. The hostname is
|
|
368
|
+
still used for the `Host` header and for TLS SNI and certificate validation, so
|
|
369
|
+
pinning is invisible to legitimate endpoints.
|
|
370
|
+
|
|
371
|
+
Credentials stay with the origin they were given to. If an endpoint redirects
|
|
372
|
+
`pay_x402` to a different origin, the caller-supplied `Authorization`, `Cookie`
|
|
373
|
+
and `X-PAYMENT` headers, and every other custom header, are dropped before the
|
|
374
|
+
next hop; only content-negotiation headers (`Accept`, `Accept-Language`,
|
|
375
|
+
`Accept-Encoding`, `User-Agent`, `Content-Type`) are carried. A redirect that
|
|
376
|
+
turns a POST into a GET also sheds the body headers. Same-origin redirects keep
|
|
377
|
+
everything, as a browser would.
|
|
378
|
+
|
|
379
|
+
Report security issues privately to security@hifriendbot.com.
|
|
380
|
+
|
|
381
|
+
## License
|
|
382
|
+
|
|
383
|
+
MIT
|