Sign in with a Wallet Signature

This Guide will go through our custom implementation of wallet sign-in. It will provide you with examples on how to:

• Implement register/login on the frontend

• Logout usage

• Currently logged in user /me endpoint usage

• Payload format, backend flow, and security details

---

Summary

Frontend does next things:

• build a timestamped payload JSON

• stringify it

• encode it with base64

• sign it with the user's Ethereum wallet (eth_sign)

• send encoded payload and signature to the BE

Backend:

• verifies signature

• validates timestamp and origin

• then logs-in or registers the user

---

1. Login/Register flow

First, we need to generate the payload and sign it

The payload is an object containing a Unix timestamp in seconds. On the backend, moment.js is used, so we recommend it being used on JS frontends as well.

For signing, this is a barebones/raw example using primitive library functions for the sake of the example.

import { ethers } from "ethers";
import moment from "moment";

async function signPayload() {
  const provider = new ethers.BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();
  const address = await signer.getAddress();

  const payload = { timestamp: moment().unix };
  const payloadB64 = btoa(JSON.stringify(payload));

  const signature = await provider.send('eth_sign', [address, payloadB64]);
  return { payloadB64, signature };
}

---

After we have data ready, we can send a request to the backend

The same endpoint (POST /auth/ethereum) handles both registration and login deterministically. If the Ethereum address is new → register. If it exists → login.

async function authenticate() {
  const { payloadB64, signature } = await signPayload();

  const response = await fetch('/auth/ethereum', {
    method: 'POST',
    body: { 
      payload: payloadB64, 
      signature: signature
    }
  });
}

---

2. Logout flow

Logging out simply calls the /auth/logout endpoint, which clears the session on the server and removes the session cookie.

If the user is not logged in, this call will simply return 401

async function logout() {
  await fetch('/auth/logout', {
    method: 'POST'
  });
  console.log('Logged out');
}

---

3. Current logged in user data /auth/me/session

The /auth/me/session route serves two purposes:

1. To check if a user is currently logged in.

2. To return session data of the logged-in user

Frontend

async function getCurrentUser() {
  const response = await fetch('/auth/me', {
    method: 'GET',
  });

  if (response.status === 401) {
    console.log('Not logged in');
    return null;
  }

  const data = await response.json();
  console.log('Current user:', data);
  return data;
}

---

6. Endpoints Overview

Route	Method	Description
/auth/ethereum	POST	Unified login + register via Ethereum signature
/auth/logout	POST	Logs user out and clears session
/auth/me/session	GET	Returns current user session info if logged in