walletconnect-requester

name	walletconnect-requester
description	Secure WalletConnect integration for AI agents. Connect to user wallets as a DApp (Proposer) without ever handling private keys. Request transactions and signatures - users approve everything in their wallet. Zero custody, maximum security. Use when you need to interact with user wallets securely via WalletConnect v2.

WalletConnect Requester

Zero custody. Maximum security. User always in control.

Why This Skill?

Unlike walletconnect-agent which holds private keys and auto-signs, this skill takes a fundamentally different approach:

	walletconnect-agent	walletconnect-requester (this skill)
Private Keys	⚠️ Stored in agent	✅ Never touches agent
Signing	⚠️ Auto-signs everything	✅ User approves each tx
Security Model	Custodial (agent has full control)	Non-custodial (user has full control)
If Agent is Compromised	⚠️ Funds can be stolen	✅ Funds are safe - no keys to steal

This is the safest way for AI agents to interact with Web3.

What This Does

• Connect to user wallets via WalletConnect v2
• Request transactions - user approves in their wallet
• Request signatures - user signs in their wallet
• Zero private key exposure - keys never leave the user's wallet

Security Guarantees

┌─────────────────┐                    ┌─────────────────┐
│   AI Agent      │                    │   User Wallet   │
│   (Requester)   │ ◄── WalletConnect ──► │   (Signer)      │
│                 │     Session          │                 │
└─────────────────┘                    └─────────────────┘
         │                                    │
         │  1. Request transaction            │
         │ ─────────────────────────────────► │
         │                                    │
         │  2. User reviews & approves        │
         │    (in wallet UI)                  │
         │                                    │
         │  3. Signed transaction             │
         │ ◄───────────────────────────────── │
         │                                    │
         ▼                                    ▼
    NO PRIVATE KEYS                      PRIVATE KEYS
    NO AUTO-SIGN                         USER APPROVES
    USER IN CONTROL                      EVERYTHING

Installation

Step 1: Install Dependencies

This skill requires Node.js dependencies. Install them globally or locally:

# Install dependencies
npm install @walletconnect/sign-client @walletconnect/core qrcode

Step 2: Get WalletConnect Project ID

1. Go to WalletConnect Cloud
2. Create a new project
3. Copy your Project ID

Step 3: Set Environment Variable

export WC_PROJECT_ID="your_project_id_here"

Step 4: Run the Skill

node scripts/wc-requester.js connect

---

Quick Start

Step 1: Create a Session

export WC_PROJECT_ID="your_project_id"
node scripts/wc-requester.js connect

Output:

WalletConnect URI: wc:abc123...@2?relay-protocol=irn&symKey=xyz

Scan this QR code with your wallet:
[QR CODE]

Waiting for wallet to connect...

Step 2: Request a Transaction

node scripts/wc-requester.js request-tx \
  --to 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --data 0xa9059cbb... \
  --value 0 \
  --chain 8453

User sees in wallet:

Send 10 USDC to 0x1F3A...?
[Approve] [Reject]

Step 3: Request a Signature

node scripts/wc-requester.js request-sign \
  --message "Sign this message to verify ownership" \
  --chain 8453

Commands

connect - Create WalletConnect Session

node scripts/wc-requester.js connect [options]

Options:
  --chains <ids>     Comma-separated chain IDs (default: 8453,1)
  --methods <list>   Comma-separated methods (default: eth_sendTransaction,personal_sign)
  --qr <path>        Generate QR code to file
  --json             Output as JSON

request-tx - Request Transaction

node scripts/wc-requester.js request-tx --to <address> --data <hex> --value <wei> --chain <id>

request-sign - Request Signature

node scripts/wc-requester.js request-sign --message <text> --chain <id>
# or for typed data
node scripts/wc-requester.js request-sign --typed-data <json> --chain <id>

sessions - List Active Sessions

node scripts/wc-requester.js sessions

disconnect - End Session

node scripts/wc-requester.js disconnect --topic <topic>

Security Model

What Agent CAN Do

• ✅ Request transactions (user must approve)
• ✅ Request signatures (user must approve)
• ✅ View connected wallet address
• ✅ View session metadata

What Agent CANNOT Do

• ❌ Hold private keys
• ❌ Auto-sign anything
• ❌ Execute transactions without approval
• ❌ Access funds directly

If Agent is Compromised

• ✅ Attacker cannot steal funds (no keys)
• ✅ Attacker cannot auto-sign transactions
• ✅ User can reject any suspicious request
• ✅ User can disconnect session anytime

Local Data Persistence

This skill writes files to ~/.walletconnect-requester/:

File	Purpose	Sensitivity
sessions.json	Active WalletConnect sessions	⚠️ Contains session topics
audit.log	Transaction audit log	⚠️ Contains masked tx hashes

Security recommendations:

• Review audit.log before sharing
• Delete sessions.json when no longer needed
• Set appropriate file permissions: chmod 600 ~/.walletconnect-requester/*

Sensitive Data Handling

Data Type	How It's Handled
WalletConnect URI	Contains symKey - displayed once during connection, not logged
Session tokens	Stored locally in sessions.json, not transmitted externally
Transaction hashes	Logged in audit.log with masked addresses
Private keys	❌ Never handled by this skill

Privacy Considerations

• WalletConnect URI (with symKey) is printed to stdout for QR code generation
• Audit logs mask full addresses (e.g., 0x8335... instead of full address)
• No data is sent to external servers except WalletConnect relay network

Configuration

Environment Variables

Variable	Required	Description
WC_PROJECT_ID	Yes	WalletConnect Cloud Project ID
WC_METADATA_NAME	No	DApp name shown in wallet
WC_METADATA_URL	No	DApp URL
WC_METADATA_ICONS	No	DApp icon URL

Namespaces Configuration

The skill requests minimal permissions by default:

{
  "eip155": {
    "chains": ["eip155:8453", "eip155:1"],
    "methods": ["eth_sendTransaction", "personal_sign"],
    "events": ["accountsChanged", "chainChanged"]
  }
}

Example Workflows

Connect and Request Payment

# 1. Create session
node scripts/wc-requester.js connect --qr /tmp/qr.png
# User scans QR with MetaMask

# 2. Request USDC transfer
node scripts/wc-requester.js request-tx \
  --to 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --data 0xa9059cbb0000... \
  --chain 8453

# User sees: "Send 10 USDC?" → Approves in wallet
# Returns: tx_hash

Verify Wallet Ownership

# 1. Connect
node scripts/wc-requester.js connect

# 2. Request signature
node scripts/wc-requester.js request-sign \
  --message "I own this wallet on March 9, 2026"

# User signs in wallet
# Returns: signature

Comparison with Other Solutions

Feature	This Skill	walletconnect-agent	MetaMask SDK
Private Key Storage	❌ Never	⚠️ In Agent	❌ Never
Auto-sign	❌ Never	✅ Yes	❌ No
User Approval Required	✅ Always	❌ No	✅ Always
Multi-wallet Support	✅ Any WC wallet	✅ Any WC wallet	❌ MetaMask only
Security Level	Highest	Medium	High
Best For	User-controlled tx	Automated trading	MetaMask users

Supported Wallets

Any wallet that supports WalletConnect v2:

• MetaMask Mobile
• Rainbow
• Trust Wallet
• Coinbase Wallet
• Ledger Live
• And 500+ more...

Troubleshooting

"No active session"

Run connect first to create a session.

"User rejected request"

User declined in their wallet. Ask if they want to retry.

"Session expired"

Sessions last 7 days by default. Reconnect to create a new session.

"Unsupported chain"

User's wallet doesn't support the requested chain. Ask them to switch networks.

Audit Log

All requests are logged (without sensitive data):

~/.walletconnect-requester/audit.log

{
  "timestamp": "2026-03-09T02:00:00Z",
  "action": "request_transaction",
  "chain": 8453,
  "to": "0x8335...",
  "status": "approved",
  "tx_hash": "0xabc123..."
}

When to Use This vs walletconnect-agent

Use This Skill When	Use walletconnect-agent When
User must approve every tx	Fully automated trading
Maximum security required	You trust the agent completely
One-time or occasional tx	24/7 unattended operation
User wants full control	User wants set-and-forget
Agent runs in untrusted env	Agent runs in secure env

When in doubt, use this skill. It's always safer.

---

License

MIT — Built with security as the #1 priority.

---

Maintainer: Web3 Investor Team
Registry: https://clawhub.com/skills/walletconnect-requester