Quai viem Integration

Quai's official position is pragmatic: tools like viem, WAGMI, and Ethers work out of the box for web-based dApp development as long as Pelagus wallet is the injected provider. In that architecture, viem's wallet client hands requests to the wallet over EIP-1193, and Pelagus — built for Quai — translates them for the network. Your TypeScript stays viem-flavored: typed, tree-shakeable, modern.

The boundary appears when viem talks to a Quai node directly. A public client over plain HTTP transport issues eth_ namespace calls, but Quai nodes serve quai_ methods across a hierarchy of zone chains with sharded addresses. For those paths — backend scripts, transaction construction outside a wallet, multi-zone routing — the quais SDK (a maintained Ethers v6 fork) is the supported tool, and viem's own viem-to-ethers migration guide maps the concepts almost mechanically.

In practice, teams capture the best of both: viem for the wallet-connected frontend surface, quais for everything that touches the node directly.

1. 1

   Install viem

   Standard installation — your existing viem version works.

   npm install viem

2. 2

   Define the Quai chain

   Quai isn't bundled in viem/chains yet, so declare it with defineChain. Use chain ID 9 for mainnet or 15000 for the Orchard testnet.

   import { defineChain } from "viem";
   
   export const quai = defineChain({
     id: 9,
     name: "Quai Network",
     nativeCurrency: { name: "Quai", symbol: "QUAI", decimals: 18 },
     rpcUrls: {
       default: { http: ["https://rpc.quai.network/cyprus1"] },
     },
     blockExplorers: {
       default: { name: "Quaiscan", url: "https://quaiscan.io" },
     },
   });

3. 3

   Create a wallet client over Pelagus

   Use custom() transport with the injected window.pelagus provider — the same pattern as custom(window.ethereum) on Ethereum.

   import { createWalletClient, custom } from "viem";
   import { quai } from "./chains/quai";
   
   const client = createWalletClient({
     chain: quai,
     transport: custom(window.pelagus),
   });
   
   const [account] = await client.requestAddresses();

4. 4

   Add quais for programmatic flows

   For transaction construction outside the wallet, backend jobs, or multi-zone routing, install quais alongside viem and let each do what it does best.

   npm install quais

• Modern dApp frontends

  Keep viem's typed contract interfaces and composable clients for the user-facing layer, with Pelagus handling Quai-specific signing.

• Migrating existing viem apps

  A viem codebase reaches Quai by swapping the chain definition and transport — UI logic and types stay intact.

• TypeScript-first teams

  viem's inference over ABIs keeps end-to-end type safety in the frontend while quais covers node-level operations.

• Hybrid stacks

  Wallet UX in viem, settlement and indexing in quais — a clean seam that mirrors how the tools are built.

Chain definition plus wallet client over the Pelagus injected provider — the complete connection path for a Quai dApp frontend.

import { createWalletClient, custom, defineChain } from "viem";

export const quai = defineChain({
  id: 9,
  name: "Quai Network",
  nativeCurrency: { name: "Quai", symbol: "QUAI", decimals: 18 },
  rpcUrls: { default: { http: ["https://rpc.quai.network/cyprus1"] } },
  blockExplorers: { default: { name: "Quaiscan", url: "https://quaiscan.io" } },
});

export async function connect() {
  if (typeof window.pelagus === "undefined") {
    window.open("https://pelaguswallet.io", "_blank");
    throw new Error("Pelagus wallet not installed");
  }

  const client = createWalletClient({
    chain: quai,
    transport: custom(window.pelagus),
  });

  const [account] = await client.requestAddresses();
  return { client, account };
}