Verifying real wallet ownership without gas: a signed-nonce pattern with viem + Express

A production walkthrough of the auth pattern powering CoinHawk's admin layer — and why "the client says they're 0xABC" is a security bug.

---

The naive way (and why it's broken)

When a user connects MetaMask to your dapp, the browser hands you their wallet address through window.ethereum.request({ method: "eth_requestAccounts" }). Tempting flow:

1. Frontend asks MetaMask for the address
2. Frontend POSTs { address: "0xABC..." } to your backend
3. Backend stores it on the session
4. Backend uses that address to gate admin features, route fees, log trades, etc.

This is completely insecure. Anyone with curl can POST any address they want. There is zero proof the requester controls the private key for 0xABC. They could claim to be Vitalik. They could claim to be your admin wallet.

You need a proof of ownership step. The standard solution is a signed-nonce challenge — and it's surprisingly easy to get wrong if you trust the client for any of the inputs.

Here's the pattern I shipped in CoinHawk, with the real production code.

The pattern in three steps

1. Server issues a fresh nonce with a short TTL, stores it on the user's session
2. Client signs a message containing that nonce via personal_sign
3. Server reconstructs the exact message from server-stored values, then verifies the signature against the address

The key word is reconstructs. The client never sends the message back. Otherwise we'd be re-introducing a trust gap — a malicious client could send a different message than the one MetaMask actually signed.

Step 1 — Issue a nonce

// routes/wallet.ts
import { Router, type Request, type Response } from "express";
import { randomBytes } from "node:crypto";
import { getSession, updateSession } from "../lib/auth";

const router = Router();
const NONCE_TTL_MS = 5 * 60 * 1000; // 5 minutes

function buildSigningMessage(nonce: string, issuedAt: Date, expiresAt: Date) {
  return [
    "Welcome to CoinHawk.",
    "",
    "Sign this message to verify ownership of your wallet.",
    "This is free and will not submit a transaction.",
    "",
    `Nonce: ${nonce}`,
    `Issued: ${issuedAt.toISOString()}`,
    `Expires: ${expiresAt.toISOString()}`,
  ].join("\n");
}

router.get("/wallet/nonce", async (req: Request, res: Response) => {
  if (!req.isAuthenticated() || !req.sessionId) {
    return res.status(401).json({ error: "Authentication required" });
  }
  const session = await getSession(req.sessionId);
  if (!session) {
    return res.status(401).json({ error: "Authentication required" });
  }

  const nonce = randomBytes(16).toString("hex");
  const issuedAt = new Date();
  const expiresAt = new Date(issuedAt.getTime() + NONCE_TTL_MS);
  const message = buildSigningMessage(nonce, issuedAt, expiresAt);

  await updateSession(req.sessionId, {
    ...session,
    pendingWalletNonce: nonce,
    pendingWalletNonceExpiresAt: expiresAt.getTime(),
  });

  res.setHeader("Cache-Control", "no-store");
  res.json({ nonce, message, issuedAt, expiresAt });
});

Three things to notice:

• The user must already be authenticated (logged in via your normal auth, in our case Replit OIDC). Wallet verification binds a wallet to an existing user — it's not a replacement for login.
• The nonce lives on the server session, not in a cookie or localStorage. Storing it on the client would defeat the entire point.
• Cache-Control: no-store because nonce responses should never be cached by intermediaries.

Step 2 — Client signs

// hooks/useWallet.ts (frontend)
async function connectWallet() {
  const [address] = await window.ethereum.request({
    method: "eth_requestAccounts",
  });
  const chainId = await window.ethereum.request({ method: "eth_chainId" });

  // Ask the server for a fresh challenge
  const { message } = await fetch("/api/wallet/nonce").then((r) => r.json());

  // Sign it via MetaMask. No gas, no transaction.
  const signature = await window.ethereum.request({
    method: "personal_sign",
    params: [message, address],
  });

  // Send the signature + claimed address back
  await fetch("/api/wallet/register", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ address, signature, chainId }),
  });
}

Note we never send the message text back. That's deliberate.

Step 3 — Server reconstructs and verifies

import { verifyMessage, isAddress } from "viem";

router.post("/wallet/register", async (req, res) => {
  if (!req.isAuthenticated() || !req.sessionId) {
    return res.status(401).json({ error: "Authentication required" });
  }

  const { address, signature, chainId } = req.body;
  const session = await getSession(req.sessionId);

  const nonce = session?.pendingWalletNonce;
  const expiresAt = session?.pendingWalletNonceExpiresAt;
  if (!nonce || !expiresAt || Date.now() > expiresAt) {
    return res.status(400).json({
      error: "No active signing challenge. Request a new nonce and try again.",
    });
  }
  if (!isAddress(address)) {
    return res.status(400).json({ error: "Invalid wallet address" });
  }

  // CRITICAL: reconstruct the exact message from SERVER-stored values.
  // Never accept the message text from the client.
  const issuedAt = new Date(expiresAt - NONCE_TTL_MS);
  const message = buildSigningMessage(nonce, issuedAt, new Date(expiresAt));

  let valid = false;
  try {
    valid = await verifyMessage({ address, message, signature });
  } catch {
    valid = false;
  }
  if (!valid) {
    return res.status(400).json({ error: "Wallet signature verification failed" });
  }

  // Bind the wallet to the session and burn the nonce so it can't be replayed.
  await updateSession(req.sessionId, {
    ...session,
    walletAddress: address.toLowerCase(),
    walletChainId: chainId,
    pendingWalletNonce: undefined,
    pendingWalletNonceExpiresAt: undefined,
  });

  res.json({ walletAddress: address.toLowerCase() });
});

viem's verifyMessage handles both EOA and ERC-1271 smart contract wallet signatures, which means smart accounts (Safe, Argent, etc.) work transparently. That's worth a lot.

The five things people get wrong

After reviewing a dozen open-source dapps, here are the bugs I see most often:

1. Trusting the client-supplied message. The signature is for a specific message. If the client picks the message, they pick the meaning. Always reconstruct server-side.
2. Storing the nonce in a cookie or localStorage. The whole point is the server holds the secret. A client-controlled nonce is no nonce at all.
3. No TTL. A nonce that lives forever can be replayed forever. 5 minutes is a good default.
4. No "burn after use". Once verified, delete the nonce. Otherwise a replay attack works the second time too.
5. Lowercasing inconsistently. EVM addresses are case-insensitive but checksums are case-significant. Pick one form (lowercase) and use it everywhere — comparisons, storage, env config.

Why I bothered

CoinHawk routes a 1% fee per trade on-chain to a verified admin wallet. The admin dashboard exposes server-side controls (nuke trades, surface alerts, run AI sentinel scans). If the wallet check were spoofable, anyone could promote themselves to admin by claiming to be the admin wallet's address. Game over.

With the signed-nonce pattern, the server has cryptographic proof — at the moment of binding — that the requester controls the private key for the address they're claiming. That proof gates everything downstream.

Try it

CoinHawk is live at https://71554e3f-e544-4c13-9297-83c480d696c1-00-3dqa8py4myltw.worf.replit.dev/ — connect your wallet, watch the MetaMask sign prompt, and you've just experienced the flow above.

Source patterns and the full implementation walkthrough live in the previous post: How I built an AI crypto trading dashboard in a weekend with Replit + Base.

---

Built with viem, Express, and a healthy paranoia about clients.