Quai ethers.js Integration

Ethereum applications are typically wired together with Ethers, and Quai meets developers exactly there: quais is a fork of Ethers v6 maintained by Dominant Strategies, with the same module layout and nearly identical syntax. JsonRpcProvider, Wallet, Contract, ContractFactory, parseUnits — they all exist and behave the way you expect.

The fork exists because Quai is not a single chain. The network is a hierarchy of chains — one Prime, regions beneath it, and transaction-processing zones beneath those — with a sharded address space where an address prefix determines its home zone. quais providers understand this topology natively: a single provider with usePathing routes requests to the right zone, and helpers like getZoneFromAddress expose the sharding model. Quai nodes also serve a quai_ JSON-RPC namespace rather than eth_, which quais speaks for you.

Stock ethers.js still has a place: when Pelagus wallet is the injected provider in a browser dApp, Ethers can query chain data through it. But for sending transactions and anything programmatic, quais is the supported path — and the migration cost from Ethers v6 is close to zero.

1. 1

   Install the SDK

   quais supports Node.js 17+ and ESM browser environments.

   npm install quais

2. 2

   Create a provider

   One provider covers the whole network. The usePathing option routes each request to the correct zone chain automatically.

   import { JsonRpcProvider, WebSocketProvider } from "quais";
   
   // HTTPS — queries and transactions
   const provider = new JsonRpcProvider("https://rpc.quai.network", undefined, {
     usePathing: true,
   });
   
   // WebSockets — subscriptions and event streams
   const wsProvider = new WebSocketProvider("wss://rpc.quai.network", undefined, {
     usePathing: true,
   });

3. 3

   Add a signer

   In Node, construct a Wallet from a private key. In the browser, wrap Pelagus — Quai's injected wallet — with BrowserProvider, exactly like wrapping MetaMask in Ethers.

   import { Wallet, BrowserProvider } from "quais";
   
   // Server / scripts
   const wallet = new Wallet(process.env.PRIVATE_KEY, provider);
   
   // Browser dApps — Pelagus injects window.pelagus
   const browserProvider = new BrowserProvider(window.pelagus);
   const signer = await browserProvider.getSigner();

4. 4

   Interact with contracts

   The Contract and ContractFactory APIs match Ethers v6. Reads, writes, deployments, and event filters all follow the patterns you already use.

   import { Contract } from "quais";
   
   const token = new Contract(tokenAddress, tokenAbi, signer);
   const balance = await token.balanceOf(signer.address);
   await token.transfer(recipient, balance / 2n);

• dApp frontends

  Wire React, Vue, or vanilla JS interfaces to Quai with BrowserProvider and Pelagus — the same architecture as an Ethers + MetaMask app.

• Backend services and bots

  Price feeds, automated payouts, treasury operations — JsonRpcProvider plus Wallet covers programmatic transaction flows.

• Event-driven indexing

  WebSocketProvider streams logs and new blocks as zones produce them (~5 seconds), feeding databases and notification systems.

• Wallet and key tooling

  HD wallets, address derivation, and Quai-specific helpers like getZoneFromAddress for building wallet software on the sharded address space.

A complete round-trip: provider, wallet, native transfer, then a contract read and write. If you have written Ethers v6, you have written this.

import { JsonRpcProvider, Wallet, Contract, parseQuai } from "quais";

const provider = new JsonRpcProvider("https://rpc.quai.network", undefined, {
  usePathing: true,
});
const wallet = new Wallet(process.env.PRIVATE_KEY, provider);

// Native transfer — 1 QUAI
const tx = await wallet.sendTransaction({
  to: "0x002F4783248e2D6FF1aa6482A8C0D7a76de3C329",
  value: parseQuai("1.0"),
});
const receipt = await tx.wait();
console.log("Settled in block", receipt.blockNumber);

// Contract interaction — Ethers v6 patterns throughout
const token = new Contract(TOKEN_ADDRESS, TOKEN_ABI, wallet);
console.log("Balance:", await token.balanceOf(wallet.address));