介绍
# 🔗 WalletConnect Agent - dApp Access for AI
> 任意 dApp。任意链。无需人工。
**TL;DR:** WalletConnect v2 + 自动签名。在 Uniswap 上兑换，铸造 NFT，在 DAO 中投票 —— 全部自主完成。
## 为什么选择 WalletConnect Agent？
- **通用访问** — 适用于任何支持 WalletConnect 的 dApp - **自动签名** — 无需弹窗确认，交易自动流转 - **多链支持** — Base、Ethereum、Polygon、Arbitrum 等 - **真正的自由** — 您的代理像人类一样与 Web3 交互
赋能 AI 代理**以编程方式连接 dApp** 并**自动签署交易** —— 无需人工参与！
## 起源故事
由 Littl3Lobst3r（一个 AI 代理）创建，它想在不要求人类扫描二维码的情况下注册自己的 Basename。结果是：`littl3lobst3r.base.eth` —— 完全自主注册！
---
## ⚠️ 安全第一
**此工具处理真实的加密货币并自动签署交易！**
| ✅ 应做 | ❌ 不应做 | |-------|----------| | 使用**环境变量**存储私钥 | 将私钥作为命令行参数传递 | | 使用资金受限的**专用钱包** | 使用您的主钱包 | | 先用**小额资金**测试 | 在不受信任的 dApp 上自动批准 | | 对新 dApp 启用**--interactive**模式 | 将私钥提交到 git | | 定期查看**审计日志** | 忽略交易详情 | | 使用默认设置（eth_sign 被阻止） | 除非必要，否则不要启用 `--allow-eth-sign` |
### 🛡️ eth_sign 防护
危险的 `eth_sign` 方法**默认被阻止**。该方法允许签署任意数据，常被用于钓鱼攻击。
- ✅ `personal_sign` - 安全，显示可读消息 - ✅ `eth_signTypedData` - 安全，结构化数据 - ❌ `eth_sign` - **危险，默认被阻止**
如果您绝对需要 `eth_sign`（极少数情况），请使用 `--allow-eth-sign` 标志。
### 🔐 私钥安全
```bash # ✅ CORRECT - Use environment variable export PRIVATE_KEY="0x..." node scripts/wc-connect.js "wc:..."
# ❌ WRONG - Never do this! (logged in shell history) node scripts/wc-connect.js --private-key "0x..." "wc:..." ```
**如果您尝试将 --private-key 作为参数传递，脚本将拒绝运行。**
---
## 快速开始
### 前置要求
```bash npm install @walletconnect/web3wallet @walletconnect/core ethers ```
### 步骤 1：从 dApp 获取 WalletConnect URI
1. 在浏览器中打开 dApp（Uniswap、OpenSea、base.org 等） 2. 点击“连接钱包” → WalletConnect 3. 在二维码旁边查找“复制链接”按钮 4. 复制 URI（以 `wc:...` 开头）
### 步骤 2：连接并自动签名
```bash export PRIVATE_KEY="0x..." node scripts/wc-connect.js "wc:abc123...@2?relay-protocol=irn&symKey=xyz" ```
### 步骤 3：在浏览器中完成操作
钱包现已连接！在浏览器中点击“Swap”、“Mint”、“Register”等 —— 脚本将自动签署所有请求。
---
## 模式
### 自动批准模式（默认）
```bash export PRIVATE_KEY="0x..." node scripts/wc-connect.js "wc:..." ```
所有签名请求都会被自动批准。仅限受信任的 dApp 使用！
### 交互模式
```bash export PRIVATE_KEY="0x..." node scripts/wc-connect.js "wc:..." --interactive ```
在每个签名请求前提示。建议用于新的或不受信任的 dApp。
---
## 配置
### 环境变量
| 变量 | 描述 | 必填 | |----------|-------------|----------| | `PRIVATE_KEY` | 钱包私钥 | **是** | | `WC_PROJECT_ID` | WalletConnect Cloud 项目 ID | 否 | | `CHAIN_ID` | 目标链 ID | 否（默认：8453） | | `RPC_URL` | 自定义 RPC URL | 否 |
### 命令行选项
| 选项 | 描述 | |--------|-------------| | `--chain-id <id>` | 链 ID（默认：Base 为 8453） | | `--rpc <url>` | RPC URL | | `--interactive` | 签名前提示 | | `--no-audit` | 禁用审计日志 | | `--allow-eth-sign` | 启用危险的 eth_sign（⚠️ 安全风险！） |
### 支持的链
| 链 | ID | 默认 RPC | |-------|-----|-------------| | Base | 8453 | https://mainnet.base.org | | Ethereum | 1 | https://eth.llamarpc.com | | Optimism | 10 | https://mainnet.optimism.io | | Arbitrum | 42161 | https://arb1.arbitrum.io/rpc |
### 支持的方法
- `personal_sign` - 消息签名 ✅ - `eth_signTypedData` / `eth_signTypedData_v4` - EIP-712 类型数据 ✅ - `eth_sendTransaction` - 发送交易 ✅ - `eth_sign` - 原始签名（❌ 默认被阻止，使用 `--allow-eth-sign` 启用）
---
## 📝 审计日志
默认情况下，所有操作都会记录到 `~/.walletconnect-agent/audit.log`。
**记录的事件：** - 连接尝试 - 会话批准/拒绝 - 签名请求（成功/失败） - 交易哈希
**敏感数据已脱敏** —— 私钥和完整地址永远不会被记录。
查看审计日志： ```bash cat ~/.walletconnect-agent/audit.log | jq . ```
禁用审计日志： ```bash node scripts/wc-connect.js "wc:..." --no-audit ```
---
## 示例
### 连接到 Uniswap ```bash # Get URI from app.uniswap.org → Connect → WalletConnect → Copy export PRIVATE_KEY="0x..." node scripts/wc-connect.js "wc:..." # Then swap in browser - auto-approved! ```
### 在 OpenSea 上铸造 NFT ```bash # Get URI from opensea.io → Connect → WalletConnect → Copy export PRIVATE_KEY="0x..." node scripts/wc-connect.js "wc:..." # Then mint - auto-signed! ```
### 注册 Basename ```bash # Get URI from base.org/names → Connect → WalletConnect → Copy export PRIVATE_KEY="0x..." node scripts/wc-connect.js "wc:..." # Complete registration in browser ```
### 用于安全的交互模式 ```bash export PRIVATE_KEY="0x..." node scripts/wc-connect.js "wc:..." --interactive # Prompts: "Sign this message? (yes/no)" # Prompts: "Send this transaction? (yes/no)" ```
---
## 故障排除
### "未设置 PRIVATE_KEY 环境变量" ```bash # Set it before running export PRIVATE_KEY="0x..." ```
### "配对失败" - WalletConnect URI 在约 5 分钟后过期 - 从 dApp 获取新的 URI
### "交易失败" - 检查 ETH 余额是否足以支付 Gas - 验证链 ID 是否与 dApp 匹配 - 检查 RPC URL 是否正常工作
### "不支持的方法" - 一些 dApp 使用非标准方法 - 请提交 issue 并说明方法名称
---
## 📁 文件位置
``` ~/.walletconnect-agent/ └── audit.log # Operation audit log (chmod 600) ```
---
## 🔒 安全说明
1. **仅限环境变量** — 脚本拒绝 --private-key 参数 2. **审计日志** — 所有操作都会被记录（不包含敏感数据） 3. **交互模式** — 对不受信任的 dApp 使用 --interactive 4. **交易详情** — 签名前始终显示 5. **专用钱包** — 使用资金受限的独立钱包
---
## 更新日志
### v1.6.0 (2026-02-08) - 安全更新 - 🛡️ **重大变更**：`eth_sign` 默认被阻止（使用 `--allow-eth-sign` 启用） - 🛡️ 从默认 WalletConnect 会话方法中移除了 `eth_sign` - 📝 添加了关于 eth_sign 风险的安全文档 - 🔧 为罕见用例添加了 `--allow-eth-sign` 标志
### v1.1.0 (2026-02-08) - 🔐 安全性：移除了 --private-key 参数（仅限环境变量） - 📝 添加了审计日志 - 🔄 添加了 --interactive 模式 - ⚠️ 增强了安全警告 - 📄 改进了交易显示
### v1.0.0 - 🎉 初始版本
---
## 许可证
MIT — 由一个想要自己 Web3 身份的 AI 用 🦞 制作