MMashDiv

Installing Wallet Connect

Create a Reown project, add the one environment variable that is not in .env.example, activate the licence, enable the extension, and rebuild — in the order that avoids a 500 nobody can explain.

7 min readUpdated 3 August 2026install, reown, walletconnect, env, extension

Installation is four steps: a Reown project, one environment variable, the extension toggle, and a rebuild. None of it is done by installer.sh, and the variable you need is not in .env.example, so every step here is manual.

The order matters less than the last step. Skipping the rebuild is the single most common way to end up with a wallet picker that opens perfectly and a sign-in that returns 500.

Before you begin

    • A working Bicrypto install — backend, frontend and cron running under PM2
    • Redis reachable and answering PING (the core already requires it)
    • Shell access to the project root — the rebuild has no admin-panel equivalent
    • A valid Wallet Connect licence (Envato item 37548018) activated on this install
    • An admin account holding view.extension and edit.extension
    • Outbound HTTPS from the backend to rpc.walletconnect.org

1. Create a Reown project

Reown (formerly WalletConnect) issues the project ID that identifies your install to the wallet network. The free tier is sufficient.

  1. Sign up at cloud.reown.com.

  2. Create a new project. Choose type App, and set the homepage URL to the domain your platform is served from — the same origin as NEXT_PUBLIC_SITE_URL.

  3. Copy the Project ID. It is a 32-character hex string shown on the project dashboard.

  4. Restrict it to your domains. In the project's settings, add your production origin to the allowed-domains list. The project ID is compiled into the public JavaScript bundle and is visible to anyone who loads your site, so domain restriction is the only thing that stops it being used elsewhere against your quota.

2. Add the environment variable

The Reown project ID. Read by BOTH the frontend build and the backend at runtime. Not present in .env.example — add it by hand.

Add it to .env in the project root, by hand:

NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID="your_32_character_project_id"

.env.example has no entry for this variable, so a fresh install will not prompt you for it and nothing at boot will complain.

The two halves of the platform then disagree. The frontend falls back to a hard-coded project ID compiled into frontend/config/wallet.tsx, so the wallet picker opens and a wallet connects — everything looks correct. The backend has no fallback: POST /api/auth/login/wallet returns 500 "Wallet connect project ID is not defined" the moment the user signs.

The symptom is therefore a working Connect wallet and a broken Sign in with wallet, which reads like a signature problem rather than a missing variable.

The fallback also means you should not treat a working wallet picker as proof the variable is set. Check the variable directly:

grep NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID .env

The metadata your users will see

The wallet's approval sheet shows a name, a description and an icon, and all three come from variables you already have. Set them properly before you invite anyone to sign — a request to sign a message from "Bicrypto" on a site branded something else is exactly what users are taught to reject.

Variable Where it shows
NEXT_PUBLIC_SITE_NAME The application name in the wallet's approval sheet. Defaults to Bicrypto
NEXT_PUBLIC_SITE_DESCRIPTION The description beneath it
NEXT_PUBLIC_SITE_URL The fallback origin when the value cannot be read from the browser

The icon is served from /img/logo/logo.png on your own origin. If that file is missing, the wallet shows a generic placeholder.

3. Activate the licence and enable the extension

  1. Activate the licence. Go to Admin → System → Extensions, open Wallet Connect (Envato item 37548018) and verify the licence. This is what writes lic/37548018.lic into the project root.

  2. Enable the extension. The toggle appears once the licence is valid.

  3. Confirm it took. /api/settings returns the list of enabled extensions, and wallet_connect must appear in it. That list is what makes the wallet button render on the login modal.

Most extensions are enforced by route prefix — /api/p2p is refused unless P2P is licensed. Wallet Connect has no route prefix of its own. Its endpoints live under /api/auth and /api/user/profile, both of which are deliberately exempt from licence enforcement so that login keeps working while a core licence is being re-activated.

Enforcement therefore happens inside the handlers instead. Each one checks that the extension is enabled and that lic/37548018.lic exists on disk, and returns 403 if either is untrue. Deleting the .lic file disables wallet sign-in immediately, without touching the toggle.

4. Rebuild and restart

Both processes need to pick up the variable, and they pick it up differently.

pnpm updator

That stops the platform, installs dependencies, runs migrations and seeders, rebuilds the frontend and starts everything again. If you only changed the environment variable and want the shorter path:

pnpm build:frontend
pnpm restart

The variable name begins with NEXT_PUBLIC_, so Next.js inlines its value into the JavaScript bundle at build time. Editing .env and restarting the frontend changes nothing — the old value is already compiled in. You must rebuild.

The backend reads the same variable at module load, once, when the route file is first imported. Editing .env without restarting the backend changes nothing there either.

Together these produce the confusing middle state: a rebuild without a restart gives you a frontend on the new project ID and a backend still verifying against the old one.

5. Verify

  1. The button exists. Open the login page signed out. Below the password form there should be a Sign in with wallet option. If it is absent, the extension is not in the /api/settings extensions list — go back to step 3.

  2. The picker opens. Click it, then Connect wallet. The Reown modal should list MetaMask, WalletConnect, Coinbase and the rest, and the header should show your site name rather than "Bicrypto".

  3. A nonce is issued. From the server, unauthenticated:

    curl -i https://yourdomain.com/api/auth/login/nonce

    A 32-character hex string means the extension is enabled and licensed. A 403 means it is not. Note that this consumes one of five requests in the fifteen-minute rate-limit window.

  4. Link a wallet. Sign in with an existing email account, go to /user/profile?tab=wallet, and connect. Your wallet prompts for a signature; on success the tab shows the address as active.

  5. Sign in with it. Sign out, choose Sign in with wallet, connect the same wallet and sign. You should land back on the dashboard signed in as the same user.

If step 5 fails, do not retry immediately — you have four requests left in the window and each attempt costs two. Read Troubleshooting first.

What you have not configured

There is no admin screen for this addon and no settings rows. In particular there is no way, from any screen, to:

  • change which chains are accepted — the allow-list is in code, listed in Wallets, chains and endpoints;
  • disable wallet sign-in while leaving wallet linking on, or the reverse — the extension toggle governs both;
  • require a wallet at registration, or auto-create accounts from a wallet — see Linking a wallet for why that path does not exist;
  • see who has linked a wallet. The admin user list exposes a wallet address column, but it reads a field this addon never writes.

Next

The sign-in flow

What the three requests do, what the backend verifies, and what it does not.

Linking a wallet

The Wallet tab, the row it writes, and the field it does not.