🔗 WalletConnect Agent - dApp Access for AI

intent

Connect AI agents to any Web3 dApp via WalletConnect v2 and automatically sign transactions without human intervention. Use this skill when you need autonomous on-chain execution: token swaps on Uniswap, NFT mints on OpenSea, DAO voting, domain registration on Base names, or any dApp action that normally requires manual wallet approval. the skill handles the full wallet connection lifecycle, transaction signing, and audit logging, with safety guardrails like blocked eth_sign methods and interactive mode for untrusted dApps.

inputs

Environment Variables (Required)

Variable	Purpose	Format
PRIVATE_KEY	Wallet private key for signing	hex string starting with 0x (e.g., 0xabc123...)
WC_PROJECT_ID	WalletConnect Cloud project ID	string, optional but recommended for production

Environment Variables (Optional)

Variable	Default	Purpose
CHAIN_ID	8453	EVM chain ID (Base, Ethereum, Polygon, Arbitrum, Optimism, etc.)
RPC_URL	chain-specific	Custom JSON-RPC endpoint for the target chain

External Connection: WalletConnect v2

• Requires active WalletConnect URI from target dApp (expires in ~5 minutes)
• Obtain by opening dApp, clicking "Connect Wallet", selecting WalletConnect, copying URI (format: wc:...@2?relay-protocol=irn&symKey=...)
• No OAuth or credentials needed; URI is single-use pairing code

External Connection: JSON-RPC Provider

• Default RPC endpoints provided for Base, Ethereum, Optimism, Arbitrum
• Custom RPC via RPC_URL environment variable or --rpc flag
• Rate limits apply per provider (typically 100-1000 requests per minute depending on service)

Installation Dependency

npm install @walletconnect/web3wallet @walletconnect/core ethers

procedure

1. Retrieve WalletConnect URI from dApp

   • Input: None (manual step in browser)
   • Open target dApp (Uniswap, OpenSea, base.org, etc.) in web browser
   • Click "Connect Wallet" button
   • Select "WalletConnect" as connection method
   • Locate "Copy link" button or QR code display
   • Copy the URI string (starts with wc:)
   • Output: WalletConnect URI string (e.g., wc:abc123...@2?relay-protocol=irn&symKey=xyz)

2. Set private key in environment

   • Input: Your wallet's private key (hex format)
   • Run: export PRIVATE_KEY="0x..."
   • Verify: echo $PRIVATE_KEY (confirm variable is set)
   • Output: Environment variable populated; script will refuse to run if missing

3. Initialize WalletConnect agent with URI

   • Input: WalletConnect URI from step 1, optional flags (--interactive, --chain-id, --rpc, --allow-eth-sign, --no-audit)
   • Run: node scripts/wc-connect.js "wc:abc123...@2?relay-protocol=irn&symKey=xyz" (with or without flags)
   • Agent validates URI format, initializes Web3Wallet instance, establishes secure relay connection to dApp
   • Output: Agent active and listening for signing requests; console prints "Connected to dApp" and session approval details

4. Trigger transaction or signing action in browser

   • Input: None (manual step in browser)
   • Navigate to desired action in connected dApp (e.g., click "Swap" on Uniswap, "Mint" on OpenSea)
   • Browser sends signing request to agent via WalletConnect relay
   • Output: Request queued in agent (visible in console or interactive prompt)

5. Agent auto-approves or prompts for signature

   • Input: Signing request from dApp (transaction or message)
   • If --interactive flag: Agent displays request details and waits for user input (yes/no)
   • If default mode: Agent automatically signs and submits
   • Agent checks request method (personal_sign, eth_signTypedData, eth_sendTransaction) against allowlist
   • If eth_sign and --allow-eth-sign not set: Agent rejects request
   • Output: Signed transaction or message returned to dApp; transaction hash logged (if on-chain)

6. Log operation to audit file

   • Input: Event data (timestamp, method, success/failure, masked address, transaction hash)
   • Agent writes to ~/.walletconnect-agent/audit.log (unless --no-audit set)
   • Sensitive data (full private key, unhashed addresses) never logged
   • Output: Audit log entry appended (JSON or text format)

7. Monitor transaction on-chain (optional)

   • Input: Transaction hash from step 5 output
   • Use block explorer (Basescan, Etherscan, etc.) or RPC call to check status
   • Output: Confirmation of on-chain execution (pending, success, or failure)

decision points

If --interactive flag is present: Display signing request details (method, data, gas estimate) and prompt user to approve or reject before signing. Otherwise, auto-approve all requests (use only with trusted dApps).

If eth_sign method requested and --allow-eth-sign flag not set: Reject the request with error message. If --allow-eth-sign flag is set, proceed with signing (⚠️ security risk: eth_sign allows arbitrary data signing and is favored by phishing attacks).

If PRIVATE_KEY environment variable not set: Exit with error message and refuse to run. If passed as --private-key argument: Reject and exit (private keys must use env vars only to avoid shell history exposure).

If WalletConnect URI is malformed or expired: Exit with error message. If URI is valid but relay connection fails: Retry up to 3 times with exponential backoff (1s, 2s, 4s), then exit if all retries fail.

If RPC call times out (> 10 seconds): Log timeout error and retry once. If second attempt also times out, fail the signing request and notify user.

If audit log cannot be written (permission denied or disk full): Log warning to console but continue operation (do not block signing). If --no-audit is set, skip logging entirely.

If wallet balance is insufficient for gas: Transaction will fail on-chain; agent displays gas cost estimate before signing in interactive mode but does not block in auto-approve mode.

If chain ID in request does not match configured chain: In interactive mode, prompt user to confirm. In auto-approve mode, proceed with signing (dApp and agent must agree on chain; mismatch will cause on-chain failure).

output contract

Successful connection and signing:

• Console output: "Connected to dApp [dApp name]" and session ID
• Audit log file: ~/.walletconnect-agent/audit.log contains JSON entries with timestamp, method name, request hash (not full data), success flag, and transaction hash (if on-chain)
• Return value to dApp: Signed transaction (0x-prefixed hex string) or signed message (0x-prefixed hex string)
• On-chain result: Transaction confirmed on target chain within ~12-60 seconds (depending on chain and network congestion)

Failed signing request:

• Console output: Error message indicating reason (unsupported method, user rejected in interactive mode, insufficient balance, etc.)
• Audit log: Entry marked with success: false and error reason
• Return value to dApp: Error response; dApp displays "Signature rejected" or similar

Audit log format:

{
  "timestamp": "2026-02-08T14:23:45.123Z",
  "event": "signing_request",
  "method": "personal_sign",
  "chain_id": 8453,
  "request_hash": "0xabc...",
  "success": true,
  "tx_hash": "0x789...",
  "error": null
}

File permissions: Audit log created with chmod 600 (readable/writable by owner only).

outcome signal

The skill worked if:

1. Console displays "Connected to dApp" without errors
2. You trigger an action in the browser dApp (e.g., "Swap") and see no popup confirmation (auto-signed)
3. In interactive mode, agent prompts "Sign this request?" with full transaction details and waits for your input
4. After approval, transaction hash appears in console and on the dApp (marked as pending or confirmed)
5. Block explorer (Basescan, Etherscan) shows your transaction confirmed on-chain within ~60 seconds
6. Audit log file contains entries with success: true and matching transaction hashes
7. Wallet balance decreases by transaction amount plus gas fee (if swap) or increases (if minting to self)

The skill failed if:

• "PRIVATE_KEY not set" or "URI invalid" or "Connection timeout" appears in console
• Browser shows "Signature rejected" or "Unsupported method"
• Transaction hash appears but block explorer shows "Failed" status or reverted call
• Audit log shows success: false with error reason
• No prompt appears in interactive mode when expected, or prompt hangs indefinitely

---

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)

---

Quick Start

Prerequisites

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" and select WalletConnect
3. Copy the URI (starts with wc:...)

Step 2: Connect and Auto-Sign

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

Step 3: Complete Action in Browser

Click "Swap", "Mint", "Register", etc. The script auto-signs all requests.

---

Modes

Auto-Approve Mode (Default)

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

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

Interactive Mode

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

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

---

📝 Audit Logging

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

Logged events:

• Connection attempts
• Session approvals and rejections
• Signing requests (success and failure)
• Transaction hashes

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

View audit log:

cat ~/.walletconnect-agent/audit.log | jq .

Disable audit logging:

node scripts/wc-connect.js "wc:..." --no-audit

---

Examples

Connect to Uniswap

export PRIVATE_KEY="0x..."
node scripts/wc-connect.js "wc:..."
# Then swap in browser - auto-approved

Mint NFT on OpenSea

export PRIVATE_KEY="0x..."
node scripts/wc-connect.js "wc:..."
# Then mint - auto-signed

Register Basename

export PRIVATE_KEY="0x..."
node scripts/wc-connect.js "wc:..."
# Complete registration in browser

Interactive Mode for Safety

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

---

⚠️ 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

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

---

Troubleshooting

"PRIVATE_KEY environment variable not set"

export PRIVATE_KEY="0x..."

"Pairing failed" or "Connection timeout"

• WalletConnect URIs expire in ~5 minutes
• Get a fresh URI from the dApp
• Agent retries relay connection 3 times; if all fail, exit with error

"Transaction failed"

• Check ETH balance for gas (at least 0.001 ETH recommended)
• Verify chain ID matches dApp (--chain-id flag)
• Check RPC URL is responding (test with curl https://mainnet.base.org)
• Check dApp's smart contract state (may have reverted for business logic reasons)

"Unsupported method"

• Some dApps use non-standard signing methods
• Use --interactive to see the exact method name
• Open an issue or use --allow-eth-sign if method is eth_sign

"Audit log write failed"

• Check disk space (df -h)
• Check directory permissions (ls -la ~/.walletconnect-agent/)
• Use --no-audit to skip logging if directory is read-only

---

📁 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
6. Rate limiting - WalletConnect and RPC providers enforce rate limits; expect 1-5 second delays between requests
7. URI expiry - WalletConnect URIs expire in ~5 minutes; re-scan QR code if connection fails
8. Network timeouts - agent retries once on timeout; increase retry count in config if network is unreliable

---

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.