walletconnect

WalletConnect CLI

目标

使用 walletconnect CLI 二进制文件，通过二维码连接钱包、查看会话、签名消息、发送交易、跨链桥接／兑换代币（swidge）以及断开连接。

使用时机

• 用户要求连接钱包或扫描二维码
• 用户要求检查当前连接的钱包（whoami）
• 用户要求使用钱包签名消息
• 用户要求签署 EIP-712 类型化数据
• 用户要求使用钱包发送交易
• 用户要求跨链桥接或兑换代币
• 用户要求断开钱包会话
• 用户在钱包操作相关的上下文中提到 walletconnect CLI

不适用时机

• 用户想质押、解除质押或领取 WCT 奖励（使用 walletconnect-staking skill）
• 用户想创建或结算 WalletConnect Pay 付款（使用 walletconnect-pay skill）
• 用户正在处理 SDK 源代码本身（直接正常编辑即可）

前置条件

• connect、sign、send-transaction 和 swidge 命令必须配置项目 ID（见下文）
• 二进制文件位于 packages/cli-sdk/dist/cli.js（或已全局链接为 walletconnect）
• 如有需要，先构建：npm run build -w @walletconnect/cli-sdk

项目 ID 配置

项目 ID 按以下优先级解析：WALLETCONNECT_PROJECT_ID 环境变量 > ~/.walletconnect-cli/config.json。

# Set globally (persists across sessions)
walletconnect config set project-id <id>

# Check current value
walletconnect config get project-id

# Or override per-command via env var
WALLETCONNECT_PROJECT_ID=<id> walletconnect connect

命令

# Connect a wallet (displays QR code in terminal)
walletconnect connect

# Connect via browser UI instead of terminal QR
walletconnect connect --browser

# Connect with specific chain
walletconnect connect --chain eip155:10

# Check current session
walletconnect whoami
walletconnect whoami --json

# Sign a message
walletconnect sign "Hello, World!"

# Sign EIP-712 typed data
walletconnect sign-typed-data '{"types":...}'

# Send a transaction (EVM)
walletconnect send-transaction '{"to":"0x...","value":"0x...","data":"0x..."}'

# Send a transaction on a specific chain
walletconnect send-transaction '{"to":"0x...","value":"0x...","chainId":"eip155:10"}'

# Send a Solana transaction
walletconnect send-transaction '{"transaction":"base64...","chainId":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"}'

# Bridge/swap tokens across chains (swidge)
walletconnect swidge --from-chain eip155:10 --to-chain eip155:1 --from-token WCT --to-token WCT --amount 5

# Disconnect
walletconnect disconnect

# Manage config
walletconnect config set project-id <value>
walletconnect config get project-id

Swidge（跨链桥接／兑换）

swidge 命令通过 LI.FI 跨链桥接或兑换代币。它会使用已连接的钱包批准并执行桥接交易。

必需标志

• --from-chain <id> — 源链（CAIP-2，例如 eip155:8453）
• --to-chain <id> — 目标链（CAIP-2，例如 eip155:10）
• --amount <n> — 桥接数量（人类可读格式，例如 5、0.1）

可选标志

• --from-token <sym> — 源代币符号（默认：ETH）
• --to-token <sym> — 目标代币符号（默认：ETH）

send-transaction 中的自动桥接

使用 send-transaction 时，CLI 会自动检查已连接的钱包在目标链上是否有足够的 ETH。如果余额不足，它会：

• 在 TTY 模式下：提示用户从另一条链桥接
• 在管道／Agent 模式下：自动从资金最多的链进行桥接

Swidge 示例

# Bridge 5 WCT from Optimism to Ethereum mainnet
walletconnect swidge --from-chain eip155:10 --to-chain eip155:1 --from-token WCT --to-token WCT --amount 5

# Swap USDC on Base to ETH on Optimism
walletconnect swidge --from-chain eip155:8453 --to-chain eip155:10 --from-token USDC --to-token ETH --amount 10

# Bridge ETH from Ethereum to Base
walletconnect swidge --from-chain eip155:1 --to-chain eip155:8453 --amount 0.01

默认工作流

1. 检查是否已配置项目 ID：walletconnect config get project-id
2. 检查是否存在会话：walletconnect whoami
3. 如果尚未连接，则连接：walletconnect connect
4. 执行所需操作（sign、send-transaction、swidge 等）
5. 操作完成后，可选择断开连接：walletconnect disconnect

重要说明

• connect 和 sign 命令需要项目 ID — 如果尚未配置，请使用 walletconnect config set project-id <id> 设置
• 会话会在多次调用之间保留，存储于 ~/.walletconnect-cli/
• 如果不存在会话，sign、send-transaction 和 swidge 会自动连接
• --browser 标志会打开包含二维码的本地网页，而不是在终端中显示二维码
• 对于需要与钱包交互的命令（扫描二维码、签名、桥接），始终使用 60 秒以上的超时
• 未指定 --chain 标志时，connect 默认使用所有 EVM 链
• ERC-20 代币的 swidge 操作需要代币授权（会自动处理 — 用户在钱包中确认）
• 跨链桥接通常需要 1–5 分钟，资金才会到达目标链
• send-transaction 的输出以 JSON 格式写入 stdout；状态／进度信息写入 stderr

验证清单

• 已配置项目 ID（walletconnect config get project-id）
• 二进制文件已构建并链接（walletconnect --help 可正常运行）
• 命令输出已显示给用户
• 与钱包交互的超时设置充足（60 秒以上）
• 对于 swidge：已提供 --from-chain、--to-chain 和 --amount

示例

检查会话状态

User: "Am I connected to a wallet?"
Action: Run `walletconnect whoami`

签名消息

User: "Sign the message 'verify-ownership' with my wallet"
Action: Run `walletconnect sign "verify-ownership"`
Note: Inform user to confirm in their wallet app

发送交易

User: "Send 0.01 ETH to 0xABC... on Optimism"
Action: Run `walletconnect send-transaction '{"to":"0xABC...","value":"0x2386F26FC10000","chainId":"eip155:10"}'`
Note: Inform user to confirm in their wallet app. Auto-bridges ETH if insufficient.

桥接代币

User: "Bridge 5 WCT from Optimism to mainnet"
Action: Run `walletconnect swidge --from-chain eip155:10 --to-chain eip155:1 --from-token WCT --to-token WCT --amount 5`
Note: May send 2 transactions (approve + bridge). Inform user to confirm each. Funds arrive in 1-5 min.