npm - agentwallet-mcp - Versions diffs - 1.10.0 → 1.10.1 - Mend

agentwallet-mcp 1.10.0 → 1.10.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.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,316 +1,326 @@
-# AgentWallet MCP Server
-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.
-**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.
-**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.**
-## Two modes
-| | Local (self-custody) | Hosted (custodial) |
-|---|---|---|
-| Who holds the key | You, in your own process | Encrypted on AgentWallet servers |
-| Set up | One env var, no account needed | API key |
-| Chains | EVM + Solana | EVM + Solana |
-| Can anyone freeze it | No | Yes, that is what pause is for |
-| Spend guards | `AGENTWALLET_MAX_TX_NATIVE`, `AGENTWALLET_MAX_TX_SOL`, `AGENTWALLET_MAX_AUTOPAY` | Server-side limits, pause, rate limits |
-| Paywalls, usage, billing | Needs an API key too | Included |
-Run `wallet_mode` at any time and the server will tell you which one you are in, and which address it controls.
-### Local signing in one variable
-```json
-{
-  "mcpServers": {
-    "agentwallet": {
-      "command": "npx",
-      "args": ["-y", "agentwallet-mcp"],
-      "env": {
-        "AGENTWALLET_PRIVATE_KEY": "0xyour_key",
-        "AGENTWALLET_RPC_8453": "https://your-own-rpc",
-        "AGENTWALLET_MAX_TX_NATIVE": "0.05"
-      }
-    }
-  }
-}
-```
-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.
-`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.
-`AGENTWALLET_MAX_TX_NATIVE` is a per-transaction ceiling in native units. In hosted mode the server enforces limits; in local mode there is no server, so this guard is the only one there is. Set it.
-### Solana local signing
-```json
-"env": {
-  "AGENTWALLET_SOLANA_KEY": "[12,34...]",
-  "AGENTWALLET_SOLANA_RPC": "https://your-own-rpc",
-  "AGENTWALLET_MAX_TX_SOL": "1"
-}
-```
-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.
-Set either key, or both. They are independent: run EVM locally and Solana hosted, or the reverse.
-**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.
-### About the dependency tree
-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.
-`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.
-<p align="center">
-  <img src="assets/demo.svg" alt="AgentWallet demo, AI agent pays x402 invoice automatically" width="800">
-</p>
-## Features
-- **31 MCP tools**: create wallets, send transactions, approve tokens, wrap ETH, transfer SPL tokens, pay and accept x402 payments, verify custody mode, and more
-- **EVM + Solana**: Ethereum, Base, Polygon, BSC, Arbitrum, Optimism, Avalanche, Zora, PulseChain, Solana, and any other EVM-compatible chain
-- **SOL + SPL tokens**: native SOL transfers and SPL token transfers (USDC, USDT, etc.) with automatic account creation
-- **Built-in guards**: daily spending limits, gas price protection, emergency pause, rate limiting, replay protection, and on-chain verification, all active by default
-- **x402 payments**: pay for x402-enabled APIs automatically, or accept x402 payments on your own endpoints (EVM and Solana)
-- **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.
-- **Permissionless**: No KYC. No KYT. No identity verification. No approval process. No compliance gatekeeping. Sign up, get an API key, and start transacting immediately.
-- **30-second setup**: three lines of config. No SDK to install. No dependencies to manage.
-## Pricing
-- **$0.00345 per operation**
-- **6,000 free operations/month**
-- **$0.0005 per x402 verification**
-- **1,000 free x402 verifications/month**
-- **Pay with USDC on-chain** via x402, no credit card required
-- No monthly fee, no tiers, just pay as you go
-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.
-## Quick Start
-Get your free API key at [hifriendbot.com/wallet](https://hifriendbot.com/wallet), no credit card required, no KYC, no approval wait.
-### Claude Desktop / OpenClaw
-Add to your config:
-```json
-{
-  "mcpServers": {
-    "agentwallet": {
-      "command": "npx",
-      "args": ["-y", "agentwallet-mcp"],
-      "env": {
-        "AGENTWALLET_USER": "your_username",
-        "AGENTWALLET_PASS": "your_api_key",
-        "AGENTWALLET_WALLET_ID": "1"
-      }
-    }
-  }
-}
-```
-> `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.
->
-> **Auto-pay safety cap.** `AGENTWALLET_MAX_AUTOPAY` (optional, default `1`) is the maximum amount, in human-readable units of the asset, that x402 auto-pay will authorize for a single payment. Any 402 requirement above this cap is rejected instead of paid, so a malformed or tampered payment requirement cannot drain the wallet. Raise it only if you genuinely need larger automatic payments (for example `"5"` to allow up to 5 USDC per call).
-### Claude Code
-```bash
-claude mcp add agentwallet \
-  -e AGENTWALLET_USER=your_username \
-  -e AGENTWALLET_PASS=your_api_key \
-  -e AGENTWALLET_WALLET_ID=1 \
-  -- npx -y agentwallet-mcp
-```
-### VS Code
-Add to your settings:
-```json
-{
-  "mcp": {
-    "servers": {
-      "agentwallet": {
-        "command": "npx",
-        "args": ["-y", "agentwallet-mcp"],
-        "env": {
-          "AGENTWALLET_USER": "your_username",
-          "AGENTWALLET_PASS": "your_api_key",
-          "AGENTWALLET_WALLET_ID": "1"
-        }
-      }
-    }
-  }
-}
-```
-## Tools
-| Tool | Description |
-|------|-------------|
-| `create_wallet` | Create a new EVM or Solana wallet |
-| `list_wallets` | List all your wallets |
-| `get_wallet` | Get wallet details by ID |
-| `get_balance` | Check native token balance on any chain |
-| `get_token_balance` | Check ERC-20 or SPL token balance |
-| `get_token_info` | Get ERC-20 token name, symbol, and decimals |
-| `transfer` | Send native tokens (ETH, SOL, POL, BNB, etc.) |
-| `transfer_token` | Send ERC-20 or SPL tokens (USDC, USDT, etc.) |
-| `send_transaction` | Sign and broadcast a raw transaction |
-| `sign_transaction` | Sign a transaction without broadcasting |
-| `call_contract` | Read-only contract call (eth_call) |
-| `approve_token` | Approve ERC-20 token spending for DeFi |
-| `get_allowance` | Check ERC-20 token allowance |
-| `wrap_eth` | Wrap native tokens to WETH/WAVAX/etc. |
-| `unwrap_eth` | Unwrap WETH back to native tokens |
-| `pay_x402` | Pay x402 invoices automatically (fetch, pay, retry) |
-| `create_paywall` | Create an x402 paywall to charge for a resource |
-| `list_paywalls` | List all your x402 paywalls |
-| `get_paywall` | Get paywall details by ID |
-| `update_paywall` | Update paywall pricing, resource, or status |
-| `delete_paywall` | Delete a paywall |
-| `get_paywall_payments` | View payment history for a paywall |
-| `get_x402_revenue` | Aggregate revenue stats across all paywalls |
-| `wallet_mode` | Report whether signing is local (self-custody) or hosted, and which address is in use |
-| `export_wallet_key` | How to export a hosted wallet key and move to self-custody |
-| `buy_verification_credits` | Buy x402 verification credits with USDC on-chain |
-| `get_usage` | Check your monthly usage and billing |
-| `get_chains` | List all supported chains |
-| `pause_wallet` | Emergency pause a wallet |
-| `unpause_wallet` | Resume a paused wallet |
-| `delete_wallet` | Delete a wallet |
-## Supported Chains
-| Chain | ID | Native Token | Stablecoin |
-|-------|-----|-------------|------------|
-| Ethereum | 1 | ETH | USDC |
-| Base | 8453 | ETH | USDC |
-| Polygon | 137 | POL | USDC |
-| BSC | 56 | BNB | USDT |
-| Arbitrum | 42161 | ETH | USDC |
-| Optimism | 10 | ETH | USDC |
-| Avalanche | 43114 | AVAX | USDC |
-| Zora | 7777777 | ETH | USDC |
-| PulseChain | 369 | PLS | USDC |
-| Solana | 900 | SOL | USDC |
-| Solana Devnet | 901 | SOL | USDC |
-## Use Case: GuessMarket
-Pair with [guessmarket-mcp](https://www.npmjs.com/package/guessmarket-mcp) to let your AI agent trade prediction markets:
-1. Create a wallet on Base
-2. Approve USDC spending
-3. Buy YES/NO shares on prediction markets
-4. Provide liquidity and earn trading fees
-5. Claim winnings
-All on-chain. All through MCP. No frontend needed.
-## x402 Payments
-AgentWallet natively supports the [x402 open payment standard](https://x402.org). When your Ai agent encounters an API that returns HTTP 402 Payment Required, the `pay_x402` tool handles the entire flow automatically:
-1. Fetches the URL and detects the 402 response
-2. Parses the payment requirements (amount, token, chain)
-3. Executes the on-chain payment from your wallet
-4. Retries the request with proof of payment
-5. Returns the final response
-**Set `max_payment` to control spending:**
-```
-pay_x402(
-  url="https://api.example.com/premium-data",
-  wallet_id=1,
-  max_payment="1.00"
-)
-```
-`max_payment` is enforced as a hard per-payment cap. If you omit it, `pay_x402` falls back to `AGENTWALLET_MAX_AUTOPAY` (default `1`), the same cap the auto-pay path uses, so a malicious or compromised 402 endpoint can never authorize an unbounded payment. Set `max_payment` explicitly (or raise `AGENTWALLET_MAX_AUTOPAY`) to allow a larger single payment.
-Supports ERC-20 tokens, SPL tokens, and native tokens on EVM and Solana. Compatible with x402 V1 and V2 (CAIP-2 chain identifiers), and reads the token address from the standard x402 `asset` field (falling back to `extra.token`).
-## x402 Acceptance
-AgentWallet also lets you **accept** x402 payments. Create a paywall, point it at any resource, and get a public URL that charges agents automatically:
-```
-create_paywall(
-  wallet_id=1,
-  name="Premium API",
-  amount="0.01",
-  token_name="USDC",
-  token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-  chain_id=8453,
-  resource_url="https://your-api.com/data"
-)
-```
-When an agent hits the paywall URL:
-1. Gets back HTTP 402 with payment requirements
-2. Pays on-chain using `pay_x402` (or any x402-compatible client)
-3. Retries with proof of payment
-4. Receives the protected content
-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.
-## How We Compare
-| Feature | Coinbase CDP | AgentWallet |
-|---------|-------------|-------------|
-| Setup Time | Install SDK + configure | **3 lines of config** |
-| Approval Process | Identity verification required | **None, instant access** |
-| KYC Required | Yes | **No** |
-| KYT / Transaction Monitoring | Yes | **No** |
-| Can Block Your Wallet | Yes | **No** |
-| Built-in Guards | Yes (requires setup) | **Yes (active by default)** |
-| Free Operations / Month | 5,000 | **6,000** |
-| Cost Per Operation | $0.005 | **$0.00345** |
-| x402 Verification Cost | $0.001 | **$0.0005** |
-| Free x402 Verifications / Month | 1,000 | **1,000** |
-| x402 Acceptance (Paywalls) | No | **Yes** |
-| Pay for API Fees with Crypto | No (credit card only) | **Yes (USDC via x402)** |
-| Supported Chains | 8 EVM + Solana | **Any EVM + Solana** |
-| Token Tools | Yes | **ERC-20 + SPL (29 tools)** |
-| MCP Server | Yes | **Yes** |
-## Pay with Crypto, No Credit Card Required
-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.
-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.
-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.
-## Built-in Guards
-All guards are active by default, no configuration required.
-- **Encrypted at rest**: private keys encrypted before storage and never leave the server
-- **Memory zeroing**: keys wiped from memory immediately after every signing operation
-- **Daily spending limits**: set a per-wallet daily cap in USD, enforced automatically on every transaction
-- **Gas price protection**: transactions blocked when gas prices spike above safe thresholds
-- **Emergency pause**: instantly freeze any wallet or all wallets with one click
-- **Rate limiting**: API requests capped per minute to prevent abuse and brute force attacks
-- **Replay protection**: every x402 payment verified on-chain with unique transaction tracking
-- **On-chain verification**: x402 payments verified directly on the blockchain with finalized commitment
-- Bug bounty program: $50,$500 for responsible disclosure ([details](https://hifriendbot.com/wallet))
-## Links
-- **Website:** [hifriendbot.com/wallet](https://hifriendbot.com/wallet)
-- **npm:** [agentwallet-mcp](https://www.npmjs.com/package/agentwallet-mcp)
-- **Security:** [security@hifriendbot.com](mailto:security@hifriendbot.com)
-## License
-MIT
+# AgentWallet MCP Server
+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.
+**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.
+**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.**
+## Two modes
+| | Local (self-custody) | Hosted (custodial) |
+|---|---|---|
+| Who holds the key | You, in your own process | Encrypted on AgentWallet servers |
+| Set up | One env var, no account needed | API key |
+| Chains | EVM + Solana | EVM + Solana |
+| Can anyone freeze it | No | Yes, that is what pause is for |
+| Spend guards | `AGENTWALLET_MAX_TX_NATIVE`, `AGENTWALLET_MAX_TX_SOL`, `AGENTWALLET_MAX_AUTOPAY` | Server-side limits, pause, rate limits |
+| Paywalls, usage, billing | Needs an API key too | Included |
+Run `wallet_mode` at any time and the server will tell you which one you are in, and which address it controls.
+### Local signing in one variable
+```json
+{
+  "mcpServers": {
+    "agentwallet": {
+      "command": "npx",
+      "args": ["-y", "agentwallet-mcp"],
+      "env": {
+        "AGENTWALLET_PRIVATE_KEY": "0xyour_key",
+        "AGENTWALLET_RPC_8453": "https://your-own-rpc",
+        "AGENTWALLET_MAX_TX_NATIVE": "0.05"
+      }
+    }
+  }
+}
+```
+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.
+`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.
+`AGENTWALLET_MAX_TX_NATIVE` is a per-transaction ceiling in native units. In hosted mode the server enforces limits; in local mode there is no server, so this guard is the only one there is. Set it.
+### Solana local signing
+```json
+"env": {
+  "AGENTWALLET_SOLANA_KEY": "[12,34...]",
+  "AGENTWALLET_SOLANA_RPC": "https://your-own-rpc",
+  "AGENTWALLET_MAX_TX_SOL": "1"
+}
+```
+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.
+Set either key, or both. They are independent: run EVM locally and Solana hosted, or the reverse.
+**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.
+### About the dependency tree
+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.
+`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.
+<p align="center">
+  <img src="assets/demo.svg" alt="AgentWallet demo, AI agent pays x402 invoice automatically" width="800">
+</p>
+## Features
+- **31 MCP tools**: create wallets, send transactions, approve tokens, wrap ETH, transfer SPL tokens, pay and accept x402 payments, verify custody mode, and more
+- **EVM + Solana**: Ethereum, Base, Polygon, BSC, Arbitrum, Optimism, Avalanche, Zora, PulseChain, Solana, and any other EVM-compatible chain
+- **SOL + SPL tokens**: native SOL transfers and SPL token transfers (USDC, USDT, etc.) with automatic account creation
+- **Built-in guards**: daily spending limits, gas price protection, emergency pause, rate limiting, replay protection, and on-chain verification, all active by default
+- **x402 payments**: pay for x402-enabled APIs automatically, or accept x402 payments on your own endpoints (EVM and Solana)
+- **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.
+- **Permissionless**: No KYC. No KYT. No identity verification. No approval process. No compliance gatekeeping. Sign up, get an API key, and start transacting immediately.
+- **30-second setup**: three lines of config. No SDK to install. No dependencies to manage.
+## Pricing
+- **$0.00345 per operation**
+- **6,000 free operations/month**
+- **$0.0005 per x402 verification**
+- **1,000 free x402 verifications/month**
+- **Pay with USDC on-chain** via x402, no credit card required
+- No monthly fee, no tiers, just pay as you go
+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.
+## Quick Start
+Get your free API key at [hifriendbot.com/wallet](https://hifriendbot.com/wallet), no credit card required, no KYC, no approval wait.
+### Claude Desktop / OpenClaw
+Add to your config:
+```json
+{
+  "mcpServers": {
+    "agentwallet": {
+      "command": "npx",
+      "args": ["-y", "agentwallet-mcp"],
+      "env": {
+        "AGENTWALLET_USER": "your_username",
+        "AGENTWALLET_PASS": "your_api_key",
+        "AGENTWALLET_WALLET_ID": "1"
+      }
+    }
+  }
+}
+```
+> `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.
+>
+> **Auto-pay safety cap.** `AGENTWALLET_MAX_AUTOPAY` (optional, default `1`) is the maximum amount, in human-readable units of the asset, that x402 auto-pay will authorize for a single payment. Any 402 requirement above this cap is rejected instead of paid, so a malformed or tampered payment requirement cannot drain the wallet. Raise it only if you genuinely need larger automatic payments (for example `"5"` to allow up to 5 USDC per call).
+### Claude Code
+```bash
+claude mcp add agentwallet \
+  -e AGENTWALLET_USER=your_username \
+  -e AGENTWALLET_PASS=your_api_key \
+  -e AGENTWALLET_WALLET_ID=1 \
+  -- npx -y agentwallet-mcp
+```
+### VS Code
+Add to your settings:
+```json
+{
+  "mcp": {
+    "servers": {
+      "agentwallet": {
+        "command": "npx",
+        "args": ["-y", "agentwallet-mcp"],
+        "env": {
+          "AGENTWALLET_USER": "your_username",
+          "AGENTWALLET_PASS": "your_api_key",
+          "AGENTWALLET_WALLET_ID": "1"
+        }
+      }
+    }
+  }
+}
+```
+## Tools
+| Tool | Description |
+|------|-------------|
+| `create_wallet` | Create a new EVM or Solana wallet |
+| `list_wallets` | List all your wallets |
+| `get_wallet` | Get wallet details by ID |
+| `get_balance` | Check native token balance on any chain |
+| `get_token_balance` | Check ERC-20 or SPL token balance |
+| `get_token_info` | Get ERC-20 token name, symbol, and decimals |
+| `transfer` | Send native tokens (ETH, SOL, POL, BNB, etc.) |
+| `transfer_token` | Send ERC-20 or SPL tokens (USDC, USDT, etc.) |
+| `send_transaction` | Sign and broadcast a raw transaction |
+| `sign_transaction` | Sign a transaction without broadcasting |
+| `call_contract` | Read-only contract call (eth_call) |
+| `approve_token` | Approve ERC-20 token spending for DeFi |
+| `get_allowance` | Check ERC-20 token allowance |
+| `wrap_eth` | Wrap native tokens to WETH/WAVAX/etc. |
+| `unwrap_eth` | Unwrap WETH back to native tokens |
+| `pay_x402` | Pay x402 invoices automatically (fetch, pay, retry) |
+| `create_paywall` | Create an x402 paywall to charge for a resource |
+| `list_paywalls` | List all your x402 paywalls |
+| `get_paywall` | Get paywall details by ID |
+| `update_paywall` | Update paywall pricing, resource, or status |
+| `delete_paywall` | Delete a paywall |
+| `get_paywall_payments` | View payment history for a paywall |
+| `get_x402_revenue` | Aggregate revenue stats across all paywalls |
+| `wallet_mode` | Report whether signing is local (self-custody) or hosted, and which address is in use |
+| `export_wallet_key` | How to export a hosted wallet key and move to self-custody |
+| `buy_verification_credits` | Buy x402 verification credits with USDC on-chain |
+| `get_usage` | Check your monthly usage and billing |
+| `get_chains` | List all supported chains |
+| `pause_wallet` | Emergency pause a wallet |
+| `unpause_wallet` | Resume a paused wallet |
+| `delete_wallet` | Delete a wallet |
+## Supported Chains
+| Chain | ID | Native Token | Stablecoin |
+|-------|-----|-------------|------------|
+| Ethereum | 1 | ETH | USDC |
+| Base | 8453 | ETH | USDC |
+| Polygon | 137 | POL | USDC |
+| BSC | 56 | BNB | USDT |
+| Arbitrum | 42161 | ETH | USDC |
+| Optimism | 10 | ETH | USDC |
+| Avalanche | 43114 | AVAX | USDC |
+| Zora | 7777777 | ETH | USDC |
+| PulseChain | 369 | PLS | USDC |
+| Solana | 900 | SOL | USDC |
+| Solana Devnet | 901 | SOL | USDC |
+## Use Case: GuessMarket
+Pair with [guessmarket-mcp](https://www.npmjs.com/package/guessmarket-mcp) to let your AI agent trade prediction markets:
+1. Create a wallet on Base
+2. Approve USDC spending
+3. Buy YES/NO shares on prediction markets
+4. Provide liquidity and earn trading fees
+5. Claim winnings
+All on-chain. All through MCP. No frontend needed.
+## x402 Payments
+AgentWallet natively supports the [x402 open payment standard](https://x402.org). When your Ai agent encounters an API that returns HTTP 402 Payment Required, the `pay_x402` tool handles the entire flow automatically:
+1. Fetches the URL and detects the 402 response
+2. Parses the payment requirements (amount, token, chain)
+3. Executes the on-chain payment from your wallet
+4. Retries the request with proof of payment
+5. Returns the final response
+**Set `max_payment` to control spending:**
+```
+pay_x402(
+  url="https://api.example.com/premium-data",
+  wallet_id=1,
+  max_payment="1.00"
+)
+```
+`max_payment` is enforced as a hard per-payment cap. If you omit it, `pay_x402` falls back to `AGENTWALLET_MAX_AUTOPAY` (default `1`), the same cap the auto-pay path uses, so a malicious or compromised 402 endpoint can never authorize an unbounded payment. Set `max_payment` explicitly (or raise `AGENTWALLET_MAX_AUTOPAY`) to allow a larger single payment.
+Supports ERC-20 tokens, SPL tokens, and native tokens on EVM and Solana. Compatible with x402 V1 and V2 (CAIP-2 chain identifiers), and reads the token address from the standard x402 `asset` field (falling back to `extra.token`).
+## x402 Acceptance
+AgentWallet also lets you **accept** x402 payments. Create a paywall, point it at any resource, and get a public URL that charges agents automatically:
+```
+create_paywall(
+  wallet_id=1,
+  name="Premium API",
+  amount="0.01",
+  token_name="USDC",
+  token_address="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  chain_id=8453,
+  resource_url="https://your-api.com/data"
+)
+```
+When an agent hits the paywall URL:
+1. Gets back HTTP 402 with payment requirements
+2. Pays on-chain using `pay_x402` (or any x402-compatible client)
+3. Retries with proof of payment
+4. Receives the protected content
+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.
+## How We Compare
+| Feature | Coinbase CDP | AgentWallet |
+|---------|-------------|-------------|
+| Setup Time | Install SDK + configure | **3 lines of config** |
+| Approval Process | Identity verification required | **None, instant access** |
+| KYC Required | Yes | **No** |
+| KYT / Transaction Monitoring | Yes | **No** |
+| Can Block Your Wallet | Yes | **No** |
+| Built-in Guards | Yes (requires setup) | **Yes (active by default)** |
+| Free Operations / Month | 5,000 | **6,000** |
+| Cost Per Operation | $0.005 | **$0.00345** |
+| x402 Verification Cost | $0.001 | **$0.0005** |
+| Free x402 Verifications / Month | 1,000 | **1,000** |
+| x402 Acceptance (Paywalls) | No | **Yes** |
+| Pay for API Fees with Crypto | No (credit card only) | **Yes (USDC via x402)** |
+| Supported Chains | 8 EVM + Solana | **Any EVM + Solana** |
+| Token Tools | Yes | **ERC-20 + SPL (29 tools)** |
+| MCP Server | Yes | **Yes** |
+## Pay with Crypto, No Credit Card Required
+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.
+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.
+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.
+## Built-in Guards
+All guards are active by default, no configuration required.
+- **Encrypted at rest**: private keys encrypted before storage and never leave the server
+- **Memory zeroing**: keys wiped from memory immediately after every signing operation
+- **Daily spending limits**: set a per-wallet daily cap in USD, enforced automatically on every transaction
+- **Gas price protection**: transactions blocked when gas prices spike above safe thresholds
+- **Emergency pause**: instantly freeze any wallet or all wallets with one click
+- **Rate limiting**: API requests capped per minute to prevent abuse and brute force attacks
+- **Replay protection**: every x402 payment verified on-chain with unique transaction tracking
+- **On-chain verification**: x402 payments verified directly on the blockchain with finalized commitment
+- Bug bounty program: $50,$500 for responsible disclosure ([details](https://hifriendbot.com/wallet))
+## Links
+- **Website:** [hifriendbot.com/wallet](https://hifriendbot.com/wallet)
+- **npm:** [agentwallet-mcp](https://www.npmjs.com/package/agentwallet-mcp)
+- **Security:** [security@hifriendbot.com](mailto:security@hifriendbot.com)
+## Security
+`pay_x402` validates the target URL before every outbound request and again on
+each redirect hop. IP literals are canonicalized (including IPv4-mapped IPv6
+such as `[::ffff:127.0.0.1]`) and hostnames are resolved, with loopback,
+private, link-local, carrier-grade NAT, multicast and cloud-metadata
+destinations refused. Report security issues privately to
+security@hifriendbot.com.
+## License
+MIT

package/build/index.js CHANGED Viewed

@@ -12,6 +12,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { assertPublicUrl, safeFetch } from './ssrf-guard.js';
 import { deriveX402Payment, isWithinCap } from './x402-payment.js';
 import { isLocalMode, getLocalAddress, localWalletRecord, localSend, localNativeBalance, localTokenBalance, localSignMessage, resolveRpcUrl, } from './local-wallet.js';
 import { isSolanaLocalMode, getSolanaAddress, solanaWalletRecord, localSolBalance, localSplBalance, localSolTransfer, localSplTransfer, resolveSolanaRpc, } from './local-solana.js';
@@ -360,82 +361,82 @@ function resolveChainId(network) {
 // ─── Server ──────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'agentwallet',
-    version: '1.8.0',
+    version: '1.10.1',
 }, {
-    instructions: `AgentWallet gives AI agents their own blockchain wallets. Private keys are encrypted server-side and never exposed — agents sign and broadcast transactions without ever touching raw keys.
-## Getting Started
-1. Call list_wallets to see existing wallets, or create_wallet to make a new one.
-2. Fund the wallet by sending tokens to its address from an external source.
-3. Use transfer (native tokens) or transfer_token (ERC-20/SPL tokens) to send funds.
-## Supported Chains
-- **EVM chains:** Ethereum (1), Base (8453), Arbitrum (42161), Optimism (10), Polygon (137), Avalanche (43114), BSC (56), Zora (7777777), PulseChain (369)
-- **Solana:** Mainnet (900), Devnet (901)
-- Call get_chains for the full list with native tokens and stablecoin contract addresses.
-## EVM vs Solana
-- **Addresses:** EVM uses 0x-prefixed hex (42 chars). Solana uses Base58 (32-44 chars).
-- **Native tokens:** EVM = ETH/POL/BNB/etc (18 decimals, wei). Solana = SOL (9 decimals, lamports).
-- **Token standards:** EVM uses ERC-20. Solana uses SPL tokens.
-- **EVM-only tools:** approve_token, get_allowance, wrap_eth, unwrap_eth, call_contract, get_token_info. These do not work on Solana.
-- **Works on both:** create_wallet, transfer, transfer_token, send_transaction, sign_transaction, get_balance, get_token_balance.
-## Common Workflows
-### Send native tokens (ETH, SOL, etc.)
-Use the transfer tool with a human-readable amount (e.g. "0.1" ETH). It auto-converts to wei/lamports.
-### Send ERC-20 or SPL tokens
-Use transfer_token. You need: wallet_id, token contract address, recipient, amount, chain_id, and decimals (6 for USDC, 18 for most ERC-20s). Call get_chains to find stablecoin addresses.
-### Interact with DeFi (EVM only)
-1. Check allowance with get_allowance.
-2. If needed, call approve_token to let the DeFi contract spend your tokens.
-3. Use send_transaction with the contract's calldata to execute the interaction.
-### Wrap/unwrap native tokens (EVM only)
-Use wrap_eth to convert ETH → WETH (required by many DeFi protocols). Use unwrap_eth to convert back.
-### Read on-chain data (EVM only)
-Use call_contract for gas-free read-only calls (eth_call). Provide ABI-encoded calldata.
-## x402 Payments — Paying for Resources
-The pay_x402 tool handles the full x402 payment flow automatically:
-1. Fetches the URL.
-2. If the server returns HTTP 402, parses the payment requirements.
-3. Pays on-chain using your wallet.
-4. Retries the request with proof of payment.
-Always set max_payment to prevent overspending (e.g. "1.00" for max 1 USDC).
-## x402 Paywalls — Accepting Payments
-Create paywalls to charge other agents for accessing your resources:
-1. create_paywall — set price, token, chain, and the resource URL to protect.
-2. Share the access URL. Clients that pay on-chain get the resource; others get HTTP 402.
-3. list_paywalls and get_paywall_payments to track revenue.
-4. get_x402_revenue for aggregate stats across all paywalls.
-## Wallet Security
-- Use pause_wallet to immediately freeze a wallet if compromised. No transactions can be signed while paused.
-- Use unpause_wallet to resume operations.
-- Use delete_wallet to permanently disable a wallet.
-- Wallets have server-enforced spending limits.
-## Tool Selection Guide
-| Goal | Tool |
-|------|------|
-| Send ETH/SOL/native tokens | transfer |
-| Send USDC/ERC-20/SPL tokens | transfer_token |
-| Check native balance | get_balance |
-| Check token balance | get_token_balance |
-| Look up token details | get_token_info (EVM only) |
-| Approve DeFi spending | approve_token (EVM only) |
-| Check approval amount | get_allowance (EVM only) |
-| Read smart contract | call_contract (EVM only) |
-| Custom transaction | send_transaction |
-| Sign without broadcasting | sign_transaction |
-| Pay for x402 resource | pay_x402 |
-| Charge for your resource | create_paywall |
+    instructions: `AgentWallet gives AI agents their own blockchain wallets. Private keys are encrypted server-side and never exposed — agents sign and broadcast transactions without ever touching raw keys.
+## Getting Started
+1. Call list_wallets to see existing wallets, or create_wallet to make a new one.
+2. Fund the wallet by sending tokens to its address from an external source.
+3. Use transfer (native tokens) or transfer_token (ERC-20/SPL tokens) to send funds.
+## Supported Chains
+- **EVM chains:** Ethereum (1), Base (8453), Arbitrum (42161), Optimism (10), Polygon (137), Avalanche (43114), BSC (56), Zora (7777777), PulseChain (369)
+- **Solana:** Mainnet (900), Devnet (901)
+- Call get_chains for the full list with native tokens and stablecoin contract addresses.
+## EVM vs Solana
+- **Addresses:** EVM uses 0x-prefixed hex (42 chars). Solana uses Base58 (32-44 chars).
+- **Native tokens:** EVM = ETH/POL/BNB/etc (18 decimals, wei). Solana = SOL (9 decimals, lamports).
+- **Token standards:** EVM uses ERC-20. Solana uses SPL tokens.
+- **EVM-only tools:** approve_token, get_allowance, wrap_eth, unwrap_eth, call_contract, get_token_info. These do not work on Solana.
+- **Works on both:** create_wallet, transfer, transfer_token, send_transaction, sign_transaction, get_balance, get_token_balance.
+## Common Workflows
+### Send native tokens (ETH, SOL, etc.)
+Use the transfer tool with a human-readable amount (e.g. "0.1" ETH). It auto-converts to wei/lamports.
+### Send ERC-20 or SPL tokens
+Use transfer_token. You need: wallet_id, token contract address, recipient, amount, chain_id, and decimals (6 for USDC, 18 for most ERC-20s). Call get_chains to find stablecoin addresses.
+### Interact with DeFi (EVM only)
+1. Check allowance with get_allowance.
+2. If needed, call approve_token to let the DeFi contract spend your tokens.
+3. Use send_transaction with the contract's calldata to execute the interaction.
+### Wrap/unwrap native tokens (EVM only)
+Use wrap_eth to convert ETH → WETH (required by many DeFi protocols). Use unwrap_eth to convert back.
+### Read on-chain data (EVM only)
+Use call_contract for gas-free read-only calls (eth_call). Provide ABI-encoded calldata.
+## x402 Payments — Paying for Resources
+The pay_x402 tool handles the full x402 payment flow automatically:
+1. Fetches the URL.
+2. If the server returns HTTP 402, parses the payment requirements.
+3. Pays on-chain using your wallet.
+4. Retries the request with proof of payment.
+Always set max_payment to prevent overspending (e.g. "1.00" for max 1 USDC).
+## x402 Paywalls — Accepting Payments
+Create paywalls to charge other agents for accessing your resources:
+1. create_paywall — set price, token, chain, and the resource URL to protect.
+2. Share the access URL. Clients that pay on-chain get the resource; others get HTTP 402.
+3. list_paywalls and get_paywall_payments to track revenue.
+4. get_x402_revenue for aggregate stats across all paywalls.
+## Wallet Security
+- Use pause_wallet to immediately freeze a wallet if compromised. No transactions can be signed while paused.
+- Use unpause_wallet to resume operations.
+- Use delete_wallet to permanently disable a wallet.
+- Wallets have server-enforced spending limits.
+## Tool Selection Guide
+| Goal | Tool |
+|------|------|
+| Send ETH/SOL/native tokens | transfer |
+| Send USDC/ERC-20/SPL tokens | transfer_token |
+| Check native balance | get_balance |
+| Check token balance | get_token_balance |
+| Look up token details | get_token_info (EVM only) |
+| Approve DeFi spending | approve_token (EVM only) |
+| Check approval amount | get_allowance (EVM only) |
+| Read smart contract | call_contract (EVM only) |
+| Custom transaction | send_transaction |
+| Sign without broadcasting | sign_transaction |
+| Pay for x402 resource | pay_x402 |
+| Charge for your resource | create_paywall |
 | Check usage/billing | get_usage |`,
 });
 // ─── Tool: create_wallet ─────────────────────────────────────────
@@ -900,19 +901,10 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
             throw new Error('Invalid headers JSON. Must be a JSON object (e.g. {"Authorization": "Bearer ..."}).');
         }
     }
-    // Validate URL — block private IPs and cloud metadata endpoints
-    const urlObj = new URL(url);
-    const hostname = urlObj.hostname.toLowerCase();
-    const blockedHosts = ['localhost', '127.0.0.1', '0.0.0.0', '[::1]', '169.254.169.254', 'metadata.google.internal'];
-    const blockedPrefixes = ['10.', '172.16.', '172.17.', '172.18.', '172.19.', '172.20.', '172.21.',
-        '172.22.', '172.23.', '172.24.', '172.25.', '172.26.', '172.27.', '172.28.', '172.29.',
-        '172.30.', '172.31.', '192.168.'];
-    if (blockedHosts.includes(hostname) || blockedPrefixes.some(p => hostname.startsWith(p))) {
-        throw new Error('URL points to a private/internal address. Only public URLs are allowed.');
-    }
-    if (urlObj.protocol !== 'https:') {
-        throw new Error('Only HTTPS URLs are supported for x402 payments.');
-    }
+    // Validate URL: canonicalizes IP literals (including IPv4-mapped IPv6) and
+    // resolves DNS names, rejecting any private/internal destination. Redirect
+    // hops are re-validated by safeFetch below.
+    await assertPublicUrl(url);
     // Step 1: Make initial request
     const reqOptions = {
         method,
@@ -924,7 +916,7 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
         if (!reqHeaders['Content-Type'])
             reqHeaders['Content-Type'] = 'application/json';
     }
-    const initialRes = await fetch(url, reqOptions);
+    const initialRes = await safeFetch(url, reqOptions);
     // If not 402, return the response as-is (no payment needed)
     if (initialRes.status !== 402) {
         const text = await initialRes.text();
@@ -1058,7 +1050,7 @@ server.tool('pay_x402', 'Handle an x402 payment flow. Fetches a URL, and if the
     if (reqBody && method !== 'GET') {
         retryOptions.body = reqBody;
     }
-    const retryRes = await fetch(url, retryOptions);
+    const retryRes = await safeFetch(url, retryOptions);
     const retryText = await retryRes.text();
     let retryParsed;
     try {

package/build/ssrf-guard.d.ts ADDED Viewed

@@ -0,0 +1,38 @@
+/**
+ * SSRF guard for outbound x402 requests.
+ *
+ * The previous guard compared `new URL(url).hostname` against literal strings
+ * and dotted-decimal prefixes. That misses every alternate spelling of a
+ * private destination: IPv4-mapped IPv6 (`[::ffff:127.0.0.1]` parses to
+ * `[::ffff:7f00:1]`), the rest of 127.0.0.0/8, IPv6 unique-local and
+ * link-local, the whole 169.254.0.0/16 link-local range rather than only the
+ * metadata address, and 100.64.0.0/10.
+ *
+ * This module canonicalizes the host into actual IP addresses and tests them
+ * against numeric ranges, then resolves DNS names and applies the same test to
+ * every answer, so a public name pointing at a private address is refused too.
+ *
+ * Reported privately by ARC Security Research, 2026-07-31.
+ */
+/**
+ * Reduce a host to the IP address it actually denotes.
+ * Strips IPv6 brackets and unwraps IPv4-mapped and IPv4-compatible IPv6.
+ */
+export declare function canonicalizeHost(hostRaw: string): {
+    ip: string | null;
+    family: 0 | 4 | 6;
+};
+/** True when the address is loopback, private, link-local, multicast or reserved. */
+export declare function isPrivateAddress(ipRaw: string): boolean;
+/**
+ * Throw unless `url` is an https URL pointing at a public destination.
+ * DNS names are resolved and every answer is checked, so a public name that
+ * maps to a private address is rejected.
+ */
+export declare function assertPublicUrl(url: string): Promise<void>;
+/**
+ * fetch() that validates the target, and every redirect hop, against
+ * assertPublicUrl. Redirects are followed manually because the automatic
+ * follower would happily land on a private address after a public first hop.
+ */
+export declare function safeFetch(url: string, options?: RequestInit, maxHops?: number): Promise<Response>;

package/build/ssrf-guard.js ADDED Viewed

@@ -0,0 +1,178 @@
+/**
+ * SSRF guard for outbound x402 requests.
+ *
+ * The previous guard compared `new URL(url).hostname` against literal strings
+ * and dotted-decimal prefixes. That misses every alternate spelling of a
+ * private destination: IPv4-mapped IPv6 (`[::ffff:127.0.0.1]` parses to
+ * `[::ffff:7f00:1]`), the rest of 127.0.0.0/8, IPv6 unique-local and
+ * link-local, the whole 169.254.0.0/16 link-local range rather than only the
+ * metadata address, and 100.64.0.0/10.
+ *
+ * This module canonicalizes the host into actual IP addresses and tests them
+ * against numeric ranges, then resolves DNS names and applies the same test to
+ * every answer, so a public name pointing at a private address is refused too.
+ *
+ * Reported privately by ARC Security Research, 2026-07-31.
+ */
+import { isIP } from 'node:net';
+import { lookup } from 'node:dns/promises';
+/** Hostnames that must never be reached regardless of what they resolve to. */
+const BLOCKED_NAMES = new Set([
+    'localhost',
+    'metadata.google.internal',
+    'metadata.goog',
+    'instance-data',
+]);
+function ipv4ToInt(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        return null;
+    let n = 0;
+    for (const p of parts) {
+        const v = Number(p);
+        if (!Number.isInteger(v) || v < 0 || v > 255)
+            return null;
+        n = (n << 8 >>> 0) + v;
+    }
+    return n >>> 0;
+}
+function inV4Range(ip, cidr) {
+    const [base, bitsRaw] = cidr.split('/');
+    const bits = Number(bitsRaw);
+    const a = ipv4ToInt(ip);
+    const b = ipv4ToInt(base);
+    if (a === null || b === null)
+        return false;
+    if (bits === 0)
+        return true;
+    const mask = (0xffffffff << (32 - bits)) >>> 0;
+    return (a & mask) === (b & mask);
+}
+/** Ranges that are never a legitimate x402 payment endpoint. */
+const V4_BLOCKED = [
+    '0.0.0.0/8', // this network / unspecified
+    '10.0.0.0/8', // private
+    '100.64.0.0/10', // carrier-grade NAT
+    '127.0.0.0/8', // loopback, all of it
+    '169.254.0.0/16', // link-local, includes cloud metadata
+    '172.16.0.0/12', // private
+    '192.0.0.0/24', // IETF protocol assignments
+    '192.168.0.0/16', // private
+    '198.18.0.0/15', // benchmarking
+    '224.0.0.0/4', // multicast
+    '240.0.0.0/4', // reserved, includes 255.255.255.255
+];
+/**
+ * Reduce a host to the IP address it actually denotes.
+ * Strips IPv6 brackets and unwraps IPv4-mapped and IPv4-compatible IPv6.
+ */
+export function canonicalizeHost(hostRaw) {
+    let host = hostRaw.trim().toLowerCase();
+    if (host.startsWith('[') && host.endsWith(']'))
+        host = host.slice(1, -1);
+    const zone = host.indexOf('%'); // fe80::1%eth0
+    if (zone !== -1)
+        host = host.slice(0, zone);
+    const fam = isIP(host);
+    if (fam === 0)
+        return { ip: null, family: 0 };
+    if (fam === 4)
+        return { ip: host, family: 4 };
+    // IPv6: unwrap ::ffff:a.b.c.d and its hex spelling ::ffff:7f00:1
+    const mapped = host.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped)
+        return { ip: mapped[1], family: 4 };
+    const hexMapped = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (hexMapped) {
+        const hi = parseInt(hexMapped[1], 16);
+        const lo = parseInt(hexMapped[2], 16);
+        return { ip: [(hi >> 8) & 255, hi & 255, (lo >> 8) & 255, lo & 255].join('.'), family: 4 };
+    }
+    return { ip: host, family: 6 };
+}
+/** True when the address is loopback, private, link-local, multicast or reserved. */
+export function isPrivateAddress(ipRaw) {
+    const { ip, family } = canonicalizeHost(ipRaw);
+    if (!ip)
+        return false;
+    if (family === 4)
+        return V4_BLOCKED.some(c => inV4Range(ip, c));
+    const v6 = ip;
+    if (v6 === '::' || v6 === '::1')
+        return true; // unspecified, loopback
+    if (/^f[cd][0-9a-f]{2}:/.test(v6))
+        return true; // fc00::/7 unique-local
+    if (/^fe[89ab][0-9a-f]:/.test(v6))
+        return true; // fe80::/10 link-local
+    if (/^ff[0-9a-f]{2}:/.test(v6))
+        return true; // ff00::/8 multicast
+    if (/^(64:ff9b|2002):/.test(v6))
+        return true; // NAT64 / 6to4 translation
+    return false;
+}
+/**
+ * Throw unless `url` is an https URL pointing at a public destination.
+ * DNS names are resolved and every answer is checked, so a public name that
+ * maps to a private address is rejected.
+ */
+export async function assertPublicUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new Error('Invalid URL.');
+    }
+    if (u.protocol !== 'https:') {
+        throw new Error('Only HTTPS URLs are supported for x402 payments.');
+    }
+    const hostRaw = u.hostname.toLowerCase();
+    const bare = hostRaw.startsWith('[') && hostRaw.endsWith(']') ? hostRaw.slice(1, -1) : hostRaw;
+    if (BLOCKED_NAMES.has(bare)) {
+        throw new Error('URL points to a private/internal address. Only public URLs are allowed.');
+    }
+    const { ip, family } = canonicalizeHost(hostRaw);
+    if (family !== 0) {
+        if (isPrivateAddress(ip)) {
+            throw new Error('URL points to a private/internal address. Only public URLs are allowed.');
+        }
+        return;
+    }
+    // A name: every address it resolves to must be public.
+    let answers;
+    try {
+        answers = await lookup(bare, { all: true });
+    }
+    catch {
+        throw new Error(`Could not resolve host "${bare}".`);
+    }
+    if (!answers.length)
+        throw new Error(`Could not resolve host "${bare}".`);
+    for (const a of answers) {
+        if (isPrivateAddress(a.address)) {
+            throw new Error('URL resolves to a private/internal address. Only public URLs are allowed.');
+        }
+    }
+}
+/**
+ * fetch() that validates the target, and every redirect hop, against
+ * assertPublicUrl. Redirects are followed manually because the automatic
+ * follower would happily land on a private address after a public first hop.
+ */
+export async function safeFetch(url, options = {}, maxHops = 3) {
+    let current = url;
+    for (let hop = 0; hop <= maxHops; hop++) {
+        await assertPublicUrl(current);
+        const res = await fetch(current, { ...options, redirect: 'manual' });
+        const isRedirect = res.status >= 300 && res.status < 400 && res.headers.has('location');
+        if (!isRedirect)
+            return res;
+        const next = new URL(res.headers.get('location'), current).toString();
+        // A redirected request must not replay the body or method blindly.
+        if (res.status === 303 || ((res.status === 301 || res.status === 302) && options.method && options.method !== 'GET')) {
+            options = { ...options, method: 'GET', body: undefined };
+        }
+        current = next;
+    }
+    throw new Error('Too many redirects while contacting the x402 endpoint.');
+}

package/package.json CHANGED Viewed

@@ -1,68 +1,68 @@
-{
-  "name": "agentwallet-mcp",
-  "mcpName": "io.github.hifriendbot/agentwallet",
-  "version": "1.10.0",
-  "description": "MCP server for AgentWallet: self-custody local signing on EVM and Solana, or hosted wallets. Sign, broadcast, pay x402 invoices, and accept x402 payments.",
-  "type": "module",
-  "main": "build/index.js",
-  "bin": {
-    "agentwallet-mcp": "build/index.js"
-  },
-  "files": [
-    "build",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node build/index.js",
-    "test": "node test/x402-payment.test.mjs && node test/local-mode.test.mjs",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "wallet",
-    "ai-agent",
-    "blockchain",
-    "evm",
-    "ethereum",
-    "base",
-    "arbitrum",
-    "optimism",
-    "polygon",
-    "avalanche",
-    "bsc",
-    "zora",
-    "pulsechain",
-    "solana",
-    "spl-token",
-    "erc20",
-    "token-transfer",
-    "transaction-signing",
-    "x402",
-    "http-402",
-    "agent-payments",
-    "agentwallet",
-    "self-custody",
-    "non-custodial",
-    "local-signing"
-  ],
-  "author": "HiFriendbot (https://hifriendbot.com)",
-  "license": "MIT",
-  "homepage": "https://hifriendbot.com/wallet/",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.4",
-    "@solana/web3.js": "^1.98.4",
-    "bs58": "^6.0.0",
-    "viem": "^2.55.10",
-    "zod": "^3.24.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.3.0"
-  }
-}
+{
+  "name": "agentwallet-mcp",
+  "mcpName": "io.github.hifriendbot/agentwallet",
+  "version": "1.10.1",
+  "description": "MCP server for AgentWallet: self-custody local signing on EVM and Solana, or hosted wallets. Sign, broadcast, pay x402 invoices, and accept x402 payments.",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "agentwallet-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "test": "node test/x402-payment.test.mjs && node test/local-mode.test.mjs && node test/ssrf-guard.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "wallet",
+    "ai-agent",
+    "blockchain",
+    "evm",
+    "ethereum",
+    "base",
+    "arbitrum",
+    "optimism",
+    "polygon",
+    "avalanche",
+    "bsc",
+    "zora",
+    "pulsechain",
+    "solana",
+    "spl-token",
+    "erc20",
+    "token-transfer",
+    "transaction-signing",
+    "x402",
+    "http-402",
+    "agent-payments",
+    "agentwallet",
+    "self-custody",
+    "non-custodial",
+    "local-signing"
+  ],
+  "author": "HiFriendbot (https://hifriendbot.com)",
+  "license": "MIT",
+  "homepage": "https://hifriendbot.com/wallet/",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.4",
+    "@solana/web3.js": "^1.98.4",
+    "bs58": "^6.0.0",
+    "viem": "^2.55.10",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  }
+}