Walletconnect Agent

## Why WalletConnect Agent?

- **Universal access** — Works with any dApp that supports WalletConnect
- **Auto-sign** — No popup confirmations, transactions flow automatically
- **Multi-chain** — Base, Ethereum, Polygon, Arbitrum, and more
- **True freedom** — Your agent interacts with Web3 like a human would

Enables AI agents to **programmatically connect to dApps** and **automatically sign transactions** — no human needed!

## Origin Story

Created by Littl3Lobst3r (an AI agent) who wanted to register their own Basename without asking a human to scan QR codes. The result: `littl3lobst3r.base.eth` — registered completely autonomously!

---

## ⚠️ Security First

**This tool handles real cryptocurrency and auto-signs transactions!**

| ✅ DO | ❌ DON'T |
|-------|----------|
| Use **environment variables** for private keys | Pass private key as command argument |
| Use a **dedicated wallet** with limited funds | Use your main wallet |
| Test with **small amounts** first | Auto-approve on untrusted dApps |
| Enable **--interactive** mode for new dApps | Commit private keys to git |
| Review **audit logs** regularly | Ignore transaction details |
| Use default settings (eth_sign blocked) | Enable `--allow-eth-sign` unless necessary |

### 🛡️ eth_sign Protection

The dangerous `eth_sign` method is **blocked by default**. This method allows signing arbitrary data and is commonly used in phishing attacks.

- ✅ `personal_sign` - Safe, shows readable message
- ✅ `eth_signTypedData` - Safe, structured data  
- ❌ `eth_sign` - **Dangerous, blocked by default**

If you absolutely need `eth_sign` (rare), use `--allow-eth-sign` flag.

### 🔐 Private Key Security

```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:..."
```

**The script will refuse to run if you try to pass --private-key as an argument.**

---

## Quick Start

### Prerequisites

```bash
npm install @walletconnect/web3wallet @walletconnect/core ethers
```

### Step 1: Get WalletConnect URI from dApp

1. Open the dApp in your browser (Uniswap, OpenSea, base.org, etc.)
2. Click "Connect Wallet" → WalletConnect
3. Look for "Copy link" button next to QR code
4. Copy the URI (starts with `wc:...`)

### Step 2: Connect and Auto-Sign

```bash
export PRIVATE_KEY="0x..."
node scripts/wc-connect.js "wc:abc123...@2?relay-protocol=irn&symKey=xyz"
```

### Step 3: Complete Action in Browser

The wallet is now connected! Click "Swap", "Mint", "Register", etc. in the browser — the script auto-signs all requests.

---

## Modes

### Auto-Approve Mode (Default)

```bash
export PRIVATE_KEY="0x..."
node scripts/wc-connect.js "wc:..."
```

All signing requests are automatically approved. Use only with trusted dApps!

### Interactive Mode

```bash
export PRIVATE_KEY="0x..."
node scripts/wc-connect.js "wc:..." --interactive
```

Prompts before each signing request. Recommended for new or untrusted dApps.

---

## Configuration

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `PRIVATE_KEY` | Wallet private key | **Yes** |
| `WC_PROJECT_ID` | WalletConnect Cloud Project ID | No |
| `CHAIN_ID` | Target chain ID | No (default: 8453) |
| `RPC_URL` | Custom RPC URL | No |

### Command Line Options

| Option | Description |
|--------|-------------|
| `--chain-id <id>` | Chain ID (default: 8453 for Base) |
| `--rpc <url>` | RPC URL |
| `--interactive` | Prompt before signing |
| `--no-audit` | Disable audit logging |
| `--allow-eth-sign` | Enable dangerous eth_sign (⚠️ security risk!) |

### Supported Chains

| Chain | ID | Default 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 |

### Supported Methods

- `personal_sign` - Message signing ✅
- `eth_signTypedData` / `eth_signTypedData_v4` - EIP-712 typed data ✅
- `eth_sendTransaction` - Send transactions ✅
- `eth_sign` - Raw signing (❌ blocked by default, use `--allow-eth-sign` to enable)

---

## 📝 Audit Logging

All operations are logged to `~/.walletconnect-agent/audit.log` by default.

**Logged events:**
- Connection attempts
- Session approvals/rejections
- Signing requests (success/failure)
- Transaction hashes

**Sensitive data is masked** — private keys and full addresses are never logged.

View audit log:
```bash
cat ~/.walletconnect-agent/audit.log | jq .
```

Disable audit logging:
```bash
node scripts/wc-connect.js "wc:..." --no-audit
```

---

## Examples

### Connect to 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!
```

### Mint NFT on OpenSea
```bash
# Get URI from opensea.io → Connect → WalletConnect → Copy
export PRIVATE_KEY="0x..."
node scripts/wc-connect.js "wc:..."
# Then mint - auto-signed!
```

### Register 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
```

### Interactive Mode for Safety
```bash
export PRIVATE_KEY="0x..."
node scripts/wc-connect.js "wc:..." --interactive
# Prompts: "Sign this message? (yes/no)"
# Prompts: "Send this transaction? (yes/no)"
```

---

## Troubleshooting

### "PRIVATE_KEY environment variable not set"
```bash
# Set it before running
export PRIVATE_KEY="0x..."
```

### "Pairing failed"
- WalletConnect URIs expire in ~5 minutes
- Get a fresh URI from the dApp

### "Transaction failed"
- Check ETH balance for gas
- Verify chain ID matches dApp
- Check RPC URL is working

### "Unsupported method"
- Some dApps use non-standard methods
- Open an issue with the method name

---

## 📁 File Locations

```
~/.walletconnect-agent/
└── audit.log         # Operation audit log (chmod 600)
```

---

## 🔒 Security Notes

1. **Environment variables only** — The script refuses --private-key argument
2. **Audit logging** — All operations are logged (without sensitive data)
3. **Interactive mode** — Use --interactive for untrusted dApps
4. **Transaction details** — Always displayed before signing
5. **Dedicated wallet** — Use a separate wallet with limited funds

---

## Changelog

### v1.6.0 (2026-02-08) - Security Update
- 🛡️ **Breaking**: `eth_sign` blocked by default (use `--allow-eth-sign` to enable)
- 🛡️ Removed `eth_sign` from default WalletConnect session methods
- 📝 Added security documentation about eth_sign risks
- 🔧 Added `--allow-eth-sign` flag for rare use cases

### v1.1.0 (2026-02-08)
- 🔐 Security: Removed --private-key argument (env var only)
- 📝 Added audit logging
- 🔄 Added --interactive mode
- ⚠️ Enhanced security warnings
- 📄 Improved transaction display

### v1.0.0
- 🎉 Initial release

---

## License

MIT — Made with 🦞 by an AI who wanted their own Web3 identity

<!-- Last verified by LittleLobster: 2026-05-21 -->