Quai WalletConnect Integration

WalletConnect popularized a simple contract between dApps and wallets: the dApp asks an EIP-1193 provider for accounts and signatures, and the wallet decides how to fulfill them. Quai dApps are built on exactly that contract. Pelagus, the browser-extension wallet built for Quai, injects window.pelagus — an EIP-1193 provider that understands Quai's quai_ RPC namespace, sharded addresses, and both the QUAI and QI ledgers.

The quais SDK wraps this in one line: new BrowserProvider(window.pelagus) gives you a provider whose getSigner() prompts the user to connect, just as Ethers does with MetaMask. Account-change and disconnect events follow the standard provider event model, so session handling code ports directly from Ethereum dApps.

WalletConnect's relay protocol itself is not yet officially supported on Quai. The practical guidance: implement your connect layer behind a small provider abstraction — detect injected providers today, surface install prompts for new users, and leave a slot where a WalletConnect connector can register when wallet support lands. The wallet surface is already broader than the browser: Blip covers mobile payments in beta, Tangem covers hardware, and a MetaMask Snap handles QUAI transfers.

1. 1

   Detect the injected provider

   Pelagus injects window.pelagus. Treat its absence as an onboarding moment, not an error — link new users to the install page.

   function getInjectedProvider() {
     if (typeof window !== "undefined" && window.pelagus) {
       return window.pelagus;
     }
     return null; // prompt: "Install Pelagus to continue"
   }

2. 2

   Request a connection

   Wrap the injected provider with quais BrowserProvider. Requesting a signer triggers the wallet's connection prompt.

   import { BrowserProvider } from "quais";
   
   const provider = new BrowserProvider(window.pelagus);
   const signer = await provider.getSigner(); // user approves in Pelagus
   const address = await signer.getAddress();

3. 3

   Handle session changes

   Subscribe to standard provider events so the UI tracks account switches and disconnects.

   window.pelagus.on("accountsChanged", (accounts) => {
     if (accounts.length === 0) handleDisconnect();
     else setActiveAccount(accounts[0]);
   });

4. 4

   Send a transaction through the wallet

   Signers route transactions through Pelagus for user approval — value transfers and contract calls alike.

   import { parseQuai } from "quais";
   
   const tx = await signer.sendTransaction({
     to: recipientAddress,
     value: parseQuai("0.5"),
   });
   await tx.wait();

5. 5

   Keep the connector layer pluggable

   Register connectors in a map keyed by wallet type. When WalletConnect support arrives on Quai wallets, it becomes one more entry — not a refactor.

• User onboarding

  Detect, prompt, connect: a first-run flow that installs Pelagus and funds a wallet is the front door to every Quai dApp.

• Payments and checkout

  Signer-routed QUAI transfers with wallet approval make point-of-sale and tipping flows auditable and self-custodial.

• Token-gated experiences

  Verify holdings after connection to unlock content, communities, or features — read calls flow through the same provider.

• Multi-surface apps

  Desktop users connect via the Pelagus extension while mobile payment flows hand off to Blip — one abstraction, several wallets.

Detection, connection, session events, and graceful onboarding for users without a wallet — the full pattern in one function.

import { BrowserProvider } from "quais";

export async function connectWallet({ onAccountsChanged }) {
  // 1. Detect — no wallet is an onboarding moment
  if (typeof window.pelagus === "undefined") {
    window.open("https://pelaguswallet.io", "_blank");
    return null;
  }

  // 2. Connect — wrapping the injected provider prompts approval
  const provider = new BrowserProvider(window.pelagus);
  const signer = await provider.getSigner();
  const address = await signer.getAddress();

  // 3. Track the session
  window.pelagus.on("accountsChanged", onAccountsChanged);

  return { provider, signer, address };
}