walletconnect-agent

# WalletConnect Agent

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!

## Features

1. **Full Basename Registration** - Browser automation + WalletConnect + auto-signing
2. **WalletConnect Connector** - Connect to any dApp and auto-sign
3. **Multi-chain Support** - Base, Ethereum, Optimism, Arbitrum, etc.

---

## Option 1: Full Basename Registration (Automated)

Fully automated end-to-end Basename registration.

### Prerequisites

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

### Usage

```bash
# Check if name is available
node scripts/register-basename.js littl3lobst3r --dry-run

# Register the name
PRIVATE_KEY="0x..." node scripts/register-basename.js littl3lobst3r
```

### What it does

1. 🌐 Opens browser, navigates to base.org/names
2. 🔍 Searches for your name, checks availability
3. 🔗 Clicks "Connect wallet" → WalletConnect
4. 📋 Extracts WalletConnect URI
5. 🤝 Programmatically connects wallet
6. 📝 Clicks "Register"
7. ✍️ Auto-signs all requests (personal_sign, eth_sendTransaction)
8. 🎉 Confirms registration success

---

## Option 2: Manual Browser + WalletConnect Script

For other dApps or when you want more control.

### Step 1: Get WalletConnect URI from dApp

1. Open the dApp in your browser (Uniswap, OpenSea, 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: Run the connector

```bash
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 browser
- Script auto-signs all requests

---

## Option 3: Clawdbot Browser Integration

If running inside Clawdbot, use browser tool + wc-connect.js together:

```javascript
// 1. Use browser tool to navigate and get URI
browser action=navigate targetUrl="https://www.base.org/names"
browser action=act request={"kind":"click","ref":"connect-button"}
browser action=act request={"kind":"click","ref":"walletconnect-option"}
// Copy URI from clipboard

// 2. Run wc-connect.js in background
exec command="node scripts/wc-connect.js 'wc:...'" background=true

// 3. Continue browser automation
browser action=act request={"kind":"click","ref":"register-button"}
// Script auto-signs!
```

---

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

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

---

## Security

⚠️ **This tool auto-signs EVERYTHING!**

**Do:**
- Use dedicated wallets with limited funds
- Test with small amounts first
- Only use with trusted dApps

**Don't:**
- Commit private keys to git
- Use your main wallet
- Run on untrusted dApps

**Best Practice:**
```bash
# Store key in environment, not in command
export PRIVATE_KEY="0x..."
node scripts/register-basename.js myname
```

---

## Troubleshooting

### "Could not get WalletConnect URI"
- Some dApps hide the copy button
- Try clicking "Open modal" or similar
- Fallback: manually copy URI and use wc-connect.js

### "Pairing failed"
- 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

### Basename specific
- Name must be available
- Need ~0.0001 ETH for 10+ char names
- Must be on Base network

---

## Examples

### Register Basename
```bash
PRIVATE_KEY="0x..." node scripts/register-basename.js mycoolname
```

### Connect to Uniswap
```bash
# Get URI from app.uniswap.org → Connect → WalletConnect → Copy
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  
PRIVATE_KEY="0x..." node scripts/wc-connect.js "wc:..."
# Then mint - auto-signed!
```

---

## License

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