cli-sdk

🔑 @walletconnect/cli-sdk

Wallet connection, transaction signing, and cross-chain bridging for CLI applications, powered by the WalletConnect protocol and LI.FI.

Quick Start

import { WalletConnectCLI } from "@walletconnect/cli-sdk";

const wc = new WalletConnectCLI({
  projectId: "your-walletconnect-cloud-project-id",
  metadata: {
    name: "My CLI Tool",
    description: "A command-line DeFi tool",
    url: "https://example.com",
    icons: [],
  },
});

// Connect — shows QR in terminal (instant if session exists)
const { accounts } = await wc.connect();
const address = accounts[0].split(":")[2];

// Request signature
const txHash = await wc.request({
  chainId: "eip155:1",
  request: {
    method: "eth_sendTransaction",
    params: [{ from: address, to: "0x...", value: "0x0", data: "0x..." }],
  },
});

// Disconnect when done
await wc.disconnect();

withWallet Helper

For the common connect → do work → cleanup pattern:

import { withWallet } from "@walletconnect/cli-sdk";

await withWallet({ projectId: "...", metadata: { ... } }, async (wallet, { accounts }) => {
  const address = accounts[0].split(":")[2];
  const txHash = await wallet.request({
    chainId: "eip155:1",
    request: {
      method: "eth_sendTransaction",
      params: [{ from: address, to: "0x...", value: "0x0" }],
    },
  });
  console.log("TX:", txHash);
});
// Automatically disconnects and cleans up

Configuration

Option	Type	Default	Description
projectId	string	required	WalletConnect Cloud project ID
metadata	Metadata	required	App metadata (name, description, url, icons)
chains	string[]	['eip155:1']	CAIP-2 chain IDs to request
methods	string[]	EVM defaults	JSON-RPC methods to request
events	string[]	['chainChanged', 'accountsChanged']	Events to subscribe to
ui	'terminal' | 'browser'	'terminal'	Connection UI mode
port	number	auto	Port for browser UI server
storagePath	string	~/.walletconnect-cli/	Session storage directory
autoConnect	boolean	true	Auto-restore previous session
logger	'info' | 'debug' | 'silent'	'silent'	Log verbosity

Browser UI Mode

For a richer connection experience, use browser mode:

const wc = new WalletConnectCLI({
  projectId: "...",
  metadata: { ... },
  ui: "browser",
});

// Opens http://localhost:<port> with styled QR code
const { accounts } = await wc.connect();

The browser page displays a QR code, updates via SSE when connected, and auto-closes.

Events

wc.on("connect", ({ session, accounts, topic }) => { ... });
wc.on("disconnect", () => { ... });
wc.on("session_update", (session) => { ... });
wc.on("session_delete", ({ topic }) => { ... });

API

new WalletConnectCLI(options)

Creates a new CLI SDK instance. No async work happens in the constructor.

wc.connect(options?): Promise<ConnectResult>

Connects to a wallet. If a valid session exists, returns immediately. Otherwise displays QR code and waits for wallet approval.

wc.request<T>(options): Promise<T>

Sends a JSON-RPC request to the connected wallet.

wc.disconnect(): Promise<void>

Disconnects the current session. Silently succeeds if no session is active.

wc.isConnected(): boolean

Returns whether a valid session is active.

wc.getAccounts(): string[]

Returns CAIP-10 account IDs from the current session.

wc.getSession(): SessionTypes.Struct | null

Returns the raw session object.

wc.destroy(): Promise<void>

Cleans up all resources (browser server, listeners, client references).

🔀 Swidge (Cross-Chain Bridge/Swap)

The walletconnect CLI includes a swidge command for bridging and swapping tokens across EVM chains via LI.FI. Zero additional dependencies — all external calls use fetch().

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

Auto-bridge in send-transaction

When sending a transaction, the CLI checks if the wallet has sufficient ETH. If not, it automatically bridges from another chain (prompts in TTY, auto-bridges in pipe mode).