> ## Documentation Index
> Fetch the complete documentation index at: https://l2docs.whitechain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a wallet with Reown AppKit

> Add Reown AppKit to an existing app on Whitechain Sepolia: which chain to import, the Turbopack build alias, the RPC override, and which AppKit features Whitechain does not support.

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](/build/dapps/dapp-with-nextjs) or the [Vite dapp template](/build/dapps/dapp-with-vite); both ship this wiring, along with the providers and the connect button this page does not repeat.

<Note>
  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](#what-reown-does-not-support-on-whitechain).
</Note>

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

```bash Terminal theme={null}
npm install @reown/appkit @reown/appkit-adapter-wagmi wagmi viem @tanstack/react-query
```

Then get a project id from [dashboard.reown.com](https://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:

```ts src/lib/wagmi.ts theme={null}
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](/build/dapps/dapp-with-nextjs#components) 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:

```text Build error theme={null}
Module not found: Can't resolve '@x402/core/client'
Module not found: Can't resolve '@x402/evm'
```

Installing them resolves the build:

```bash Terminal theme={null}
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](https://github.com/wevm/wagmi/issues/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:

```ts src/lib/wagmi.ts theme={null}
import { http } from 'viem';

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

<Warning>
  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.
</Warning>

The public endpoint is rate limited per client IP address. See [Rate limits on Whitechain endpoints](/learn/network/reference#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](/build/block-explorer/indexer-wallet). |
| On-Ramp                                          | Not available                          | Send WBT from WhiteBIT, or claim test WBT from the [faucet](https://faucet.testnet.whitechain.io).  |

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](/learn/network/reference) before launch, so check the supported-chain list against that chain ID once it is published.

## Related

* [Next dapp template](/build/dapps/dapp-with-nextjs)
* [Vite dapp template](/build/dapps/dapp-with-vite)
* [Use viem with Whitechain](/build/dapps/use-viem)
* [Wallets](/build/wallet/wallets)
* [Network reference](/learn/network/reference)