Connect a wallet with Reown AppKit

Reown AppKit (formerly WalletConnect) gives a dapp a connect modal, a wallet session, and a wagmi config in one setup. This page covers what is specific to Whitechain: which chain to import, how to repoint the RPC, the build alias Next needs, and the AppKit features that do not work here. It assumes you are adding AppKit to an app you already have. To start from a working app instead, clone the Next dapp template or the Vite dapp template; both ship this wiring, along with the providers and the connect button this page does not repeat.

Core connect, sign, and transact work today on Whitechain Sepolia. AppKit features that depend on the Reown Blockchain API do not. See What Reown does not support on Whitechain.

Whitechain networks in the package

@reown/appkit/networks re-exports viem/chains, so Whitechain Sepolia is available from AppKit with no custom chain definition of your own:

Export	Chain ID	Network	Default RPC in the definition
`whitechainSepolia`	`1874`	Whitechain Sepolia, the Layer 2 (L2) testnet	`https://rpc.testnet.whitechain.io`

Configure AppKit

Install the packages:

Terminal

npm install @reown/appkit @reown/appkit-adapter-wagmi wagmi viem @tanstack/react-query

Then get a project id from dashboard.reown.com. The project id identifies your app to the WalletConnect relays, so it is public by design and belongs in a client-side variable such as NEXT_PUBLIC_REOWN_PROJECT_ID. Never put a server secret in one of those: everything in a client bundle ships to the browser. Import whitechainSepolia, hand it to the wagmi adapter, and call createAppKit once at module scope:

src/lib/wagmi.ts

import { WagmiAdapter } from '@reown/appkit-adapter-wagmi';
import { whitechainSepolia } from '@reown/appkit/networks';
import { createAppKit } from '@reown/appkit/react';

const projectId = process.env.NEXT_PUBLIC_REOWN_PROJECT_ID ?? '';

const networks: [typeof whitechainSepolia] = [whitechainSepolia];

const adapter = new WagmiAdapter({ projectId, networks, ssr: true });

createAppKit({
  adapters: [adapter],
  projectId,
  networks,
  features: { email: false, socials: false, analytics: false },
});

export const wagmiConfig = adapter.wagmiConfig;
export { useAppKit } from '@reown/appkit/react';

createAppKit takes a non-empty tuple rather than a plain array, so type the networks constant instead of letting TypeScript widen it. No type assertion is needed beyond that: a viem chain from @reown/appkit/networks satisfies AppKit’s AppKitNetwork type directly. Set ssr: true only for a server-rendered app such as Next; drop it in a client-only single-page app. features turns off email and social login. Both route through Reown’s embedded wallet, which does not support Whitechain, so the login completes and signing then fails. Leave them off unless you have confirmed otherwise for your users. Hand wagmiConfig to WagmiProvider and open the modal with useAppKit. Both are standard AppKit and wagmi, so follow the Next dapp template for the provider and panel code. One Whitechain-specific detail when you render a balance: useBalance in wagmi v3 returns value, decimals, and symbol. It has no formatted field, which wagmi v2 did have, so format it yourself with viem’s formatUnits(balance.value, balance.decimals). This configuration is compiled and run as a Next app against Whitechain Sepolia on the current releases:

Package	Version
`@reown/appkit`	1.8.23
`@reown/appkit-adapter-wagmi`	1.8.23
`wagmi`	3.7.6
`viem`	2.55.13
`@tanstack/react-query`	5.101.4

Build under Next and Turbopack

wagmi’s connector barrel pulls in wallet SDKs your app never uses. One of them declares optional peer dependencies of its own, which package managers skip by design. Turbopack resolves every import it can reach, so next build fails on packages nothing calls at runtime:

Build error

Module not found: Can't resolve '@x402/core/client'
Module not found: Can't resolve '@x402/evm'

Installing them resolves the build:

Terminal

npm install @x402/core @x402/evm @x402/extensions @x402/svm

They add about 28 MB to node_modules and nothing to the browser bundle, since no code path reaches them. The failing set tracks the connector packages rather than your code, so it changes when they do. Read the specifiers in your own build output rather than assuming this list. If a future version names packages this page does not, either install those or alias them to an empty module with Turbopack’s resolveAlias, which is the workaround the wagmi maintainers point to in wevm/wagmi#4906. Vite and Rollup builds are unaffected.

Point the app at a different RPC endpoint

The whitechainSepolia definition already defaults to the official endpoint https://rpc.testnet.whitechain.io, so most apps need no override. Override it when you run your own node, a local development chain, or a private gateway. Set the transport on the wagmi adapter. Every read and write your app makes through wagmi hooks then goes to that endpoint:

src/lib/wagmi.ts

import { http } from 'viem';

const adapter = new WagmiAdapter({
  projectId,
  networks,
  transports: {
    [whitechainSepolia.id]: http('https://rpc.testnet.whitechain.io'),
  },
});

AppKit also has a customRpcUrls option, which does not redirect wagmi’s own calls. With customRpcUrls set and no transport, useBalance, useReadContract, and every other wagmi hook still reach the chain’s default endpoint. Passing it to both the adapter and createAppKit does not change that. Use transports for anything your app reads or writes.

The public endpoint is rate limited per client IP address. See Rate limits on Whitechain endpoints before pointing a production app at it.

What Reown does not support on Whitechain

Reown’s Blockchain API is a separate hosted service from the WalletConnect relays, and it is what powers AppKit’s value-added features. Whitechain is not in its chain list: the list at https://rpc.walletconnect.org/v1/supported-chains contains neither eip155:1874 nor eip155:1875.

AppKit feature	On Whitechain Sepolia	What to do instead
Connect over WalletConnect, injected wallets	Works	Nothing. This is the setup above.
Sign messages, send transactions, call contracts	Works	Nothing. wagmi and viem talk to the Whitechain RPC directly.
Identity and ENS resolution	Not available	Resolve names yourself with a second viem client pointed at Ethereum mainnet.
Embedded wallets (email and social login)	Login completes, transactions may fail	Set `features: { email: false, socials: false }` and ship external wallets only.
Swaps	Not available on any testnet	Use a dapp on Whitechain.
Transaction history in the account view	Not available on any testnet	Read it from the explorer API. See Wallet indexing example.
On-Ramp	Not available	Send WBT from WhiteBIT, or claim test WBT from the faucet.

At L2 Mainnet the test-network limitation no longer applies, and Whitechain is working toward these features being available there. The remaining step is the chain being listed in Reown’s Blockchain API. Whitechain publishes the Mainnet chain ID and endpoints in the Network reference before launch, so check the supported-chain list against that chain ID once it is published.

Wallet

Dapps

Deploy

Bridge

Block Explorer

Ecosystem

Connect a wallet with Reown AppKit

Whitechain networks in the package

Configure AppKit

Build under Next and Turbopack

Point the app at a different RPC endpoint

What Reown does not support on Whitechain

​Whitechain networks in the package

​Configure AppKit

​Build under Next and Turbopack

​Point the app at a different RPC endpoint

​What Reown does not support on Whitechain

​Related

Whitechain networks in the package

Configure AppKit

Build under Next and Turbopack

Point the app at a different RPC endpoint

What Reown does not support on Whitechain

Related