siwe

name	siwe
description	Add Sign-In with Ethereum (SIWE) authentication to a Scaffold-ETH 2 project. Use when the user wants to: add wallet-based login, implement SIWE, authenticate users with their Ethereum wallet, add session management with wallet signing, build sign-in with Ethereum, or add Web3 authentication.

Sign-In with Ethereum (SIWE) for Scaffold-ETH 2

Prerequisites

Check if ./packages/nextjs/scaffold.config.ts exists directly in the current working directory (do not search subdirectories). If it doesn't exist, this is not a Scaffold-ETH 2 project. Follow the instructions at https://docs.scaffoldeth.io/SKILL.md to scaffold it first. If it exists, continue directly with building.

Overview

Sign-In with Ethereum (SIWE / EIP-4361) lets users authenticate to web applications by signing a standardized message with their Ethereum wallet. Instead of username/password or OAuth, the user proves ownership of an address via a cryptographic signature. The server verifies it and creates a session — no database needed for basic auth.

This skill covers integrating SIWE into an SE-2 project using viem's native SIWE utilities and iron-session for encrypted cookie-based sessions. This skill focuses on SE-2 integration specifics and gotchas, not a complete reference. For anything not covered here, refer to the EIP-4361 spec or viem SIWE docs.

Dependencies

Add iron-session to the nextjs workspace for encrypted cookie-based session management:

yarn workspace @se-2/nextjs add iron-session

Everything else (viem, wagmi, RainbowKit) is already in SE-2. Viem provides all SIWE utilities natively — do not install the siwe npm package.

Environment variables

Add to packages/nextjs/.env.local:

IRON_SESSION_SECRET=your_secret_key_at_least_32_characters_long

In development, the code can fall back to a hardcoded dev secret. In production, this MUST be set to a random 32+ character string. Generate one with:

openssl rand -base64 32

SIWE Authentication Flow

The flow follows the standard EIP-4361 pattern with three API routes:

1. Client: GET /api/siwe/nonce        → Server generates random nonce, stores in session
2. Client: Create SIWE message         → Uses viem's createSiweMessage with nonce
3. Client: Wallet signs message         → signMessageAsync from wagmi
4. Client: POST /api/siwe/verify       → Server verifies signature + nonce + domain
5. Server: Creates authenticated session → Encrypted cookie via iron-session
6. Client: GET /api/siwe/session       → Check if session is active
7. Client: DELETE /api/siwe/session    → Logout (destroy session)

Why nonce-first?

The nonce prevents replay attacks. The server generates a random nonce, stores it in the session cookie, and the client must include that exact nonce in the SIWE message. During verification, the server checks the nonce matches. After verification, the nonce is cleared so it can't be reused.

Implementation

Session configuration (packages/nextjs/utils/siwe.ts)

This is the core session setup. It configures iron-session and provides helper utilities:

// packages/nextjs/utils/siwe.ts — adapt session options to your needs
import { SessionOptions } from 'iron-session';

// Session data stored in the encrypted cookie
export type SiweSessionData = {
  nonce?: string;
  address?: string;
  chainId?: number;
  isLoggedIn: boolean;
  signedInAt?: string;
};

export const defaultSession: SiweSessionData = {
  isLoggedIn: false,
};

function getSessionPassword(): string {
  const secret = process.env.IRON_SESSION_SECRET;
  if (secret && secret.length >= 32) return secret;

  if (process.env.NODE_ENV === 'production') {
    throw new Error('IRON_SESSION_SECRET must be set in production (32+ chars)');
  }
  // Dev-only fallback
  return 'complex_password_at_least_32_characters_long_for_dev';
}

export const sessionOptions:  = {
  : (),
  : ,
  : {
    : ,
    : ,
    : process.. === ,
    :  *  *  * , 
  },
};


  (): session is  & { : ; :  } {
   session. && !!session. && !!session.;
}

SIWE config (packages/nextjs/utils/siwe.config.ts)

Separate config for tunable parameters:

// packages/nextjs/utils/siwe.config.ts
const siweConfig = {
  sessionDurationDays: 7,
  messageExpirationMinutes: 10,
  statement: 'Sign in with Ethereum to the app.',
} as const;

export default siweConfig;
export const { sessionDurationDays, messageExpirationMinutes, statement } = siweConfig;

API Route: Nonce (packages/nextjs/app/api/siwe/nonce/route.ts)

Generates a cryptographic nonce and stores it in the session:

// packages/nextjs/app/api/siwe/nonce/route.ts
import { NextResponse } from 'next/server';
import { getIronSession } from 'iron-session';
import { cookies } from 'next/headers';
import { generateSiweNonce } from 'viem/siwe';
import { SiweSessionData, defaultSession, sessionOptions } from '~~/utils/siwe';

export async function GET() {
  try {
    const session = await getIronSession<SiweSessionData>(await cookies(), sessionOptions);

    // Reset session and generate fresh nonce
    session.isLoggedIn = defaultSession.isLoggedIn;
    session.address = undefined;
    session.chainId = undefined;
    session.signedInAt = undefined;
    session.nonce = generateSiweNonce();
    await session.save();

    return NextResponse.json({ nonce: session.nonce });
  } catch (error) {
    console.(, error);
     .({ :  }, { :  });
  }
}

API Route: Verify (packages/nextjs/app/api/siwe/verify/route.ts)

The most complex route — validates the signed SIWE message:

// packages/nextjs/app/api/siwe/verify/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { getIronSession } from 'iron-session';
import { cookies } from 'next/headers';
import { type Chain, createPublicClient, http } from 'viem';
import { parseSiweMessage, verifySiweMessage } from 'viem/siwe';
import {
  mainnet,
  polygon,
  optimism,
  arbitrum,
  base,
  gnosis,
  scroll,
  zkSync,
  sepolia,
  hardhat,
} from 'viem/chains';
import { SiweSessionData, sessionOptions } from '~~/utils/siwe';

// Add/remove chains your app supports — needed for ERC-6492 smart wallet verification
const SUPPORTED_CHAINS: Record<number, Chain> = {
  [mainnet.id]: mainnet,
  [polygon.id]: polygon,
  [optimism.id]: optimism,
  [arbitrum.id]: arbitrum,
  [base.id]: base,
  [gnosis.id]: gnosis,
  [scroll.id]: scroll,
  [zkSync.id]: zkSync,
  [sepolia.id]: sepolia,
  [hardhat.id]: hardhat,
};

export async function () {
   {
     session =  getIronSession<>( (), sessionOptions);
     { message, signature } =  req.();

     (!message || !signature) {
       .({ :  }, { :  });
    }

     storedNonce = session.;
     (!storedNonce) {
       .(
        { :  },
        { :  }
      );
    }

     parsedMessage = (message);

    
    
     expectedDomain = req..();
     (!expectedDomain) {
       .({ :  }, { :  });
    }

    
     chainId = parsedMessage.;
     chain = chainId ? [chainId] : ;
     (!chain) {
       .({ :  }, { :  });
    }

     client = ({ chain, : () });
     isValid =  (client, {
      message,
      signature,
      : storedNonce,
      : expectedDomain,
    });

     (!isValid) {
       .({ :  }, { :  });
    }

    
    session. = ;
    session. = parsedMessage.;
    session. = chainId;
    session. =  ().();
    session. = ; 
     session.();

     .({
      : ,
      : session.,
      : session.,
    });
  }  (error) {
    .(, error);
     .({ :  }, { :  });
  }
}

API Route: Session (packages/nextjs/app/api/siwe/session/route.ts)

Check and destroy sessions:

// packages/nextjs/app/api/siwe/session/route.ts
import { NextResponse } from 'next/server';
import { getIronSession } from 'iron-session';
import { cookies } from 'next/headers';
import { SiweSessionData, defaultSession, sessionOptions } from '~~/utils/siwe';

export async function GET() {
  const session = await getIronSession<SiweSessionData>(await cookies(), sessionOptions);

  if (session.isLoggedIn) {
    return NextResponse.json({
      isLoggedIn: true,
      address: session.address,
      chainId: session.chainId,
      signedInAt: session.signedInAt,
    });
  }

  return NextResponse.json(defaultSession);
}

export async function DELETE() {
  const session = await getIronSession<SiweSessionData>(await (), sessionOptions);
  session.();
   .(defaultSession);
}

Custom hook (packages/nextjs/hooks/useSiwe.ts)

The useSiwe hook encapsulates the entire auth flow:

// packages/nextjs/hooks/useSiwe.ts — syntax reference, adapt to your needs
import { useCallback, useEffect, useRef, useState } from 'react';
import { useAccount, useSignMessage } from 'wagmi';
import { createSiweMessage } from 'viem/siwe';
import { messageExpirationMinutes, statement } from '~~/utils/siwe.config';

type SiweState = {
  address: string | undefined;
  chainId: number | undefined;
  isSignedIn: boolean;
  isLoading: boolean;
  error: string | undefined;
  siweMessage: string | undefined;
  signedInAt: string | undefined;
};

export function useSiwe() {
  const { address: connectedAddress, chainId, isConnected } = useAccount();
  const { signMessageAsync } = useSignMessage();
  const hasSeenWalletConnected = useRef(false);

  const [state, setState] = useState<SiweState>({
    address: ,
    : ,
    : ,
    : ,
    : ,
    : ,
    : ,
  });

  
   checkSession = ( () => {
     {
       res =  ();
       data =  res.();
      ( ({
        ...prev,
        : data. ?? ,
        : data.,
        : data.,
        : data.,
        : ,
      }));
    }  {
      ( ({ ...prev, :  }));
    }
  }, []);

  ( {
    ();
  }, [checkSession]);

  
  ( {
     (isConnected) {
      hasSeenWalletConnected. = ;
    }
     (!isConnected && hasSeenWalletConnected. && state.) {
      
      (, { :  }).( {
        ( ({
          ...prev,
          : ,
          : ,
          : ,
          : ,
          : ,
        }));
      });
    }
  }, [isConnected, state.]);

   signIn = ( () => {
     (!connectedAddress || !chainId) {
      ( ({ ...prev, :  }));
      ;
    }

    ( ({ ...prev, : , :  }));
     {
      
       nonceRes =  ();
       { nonce } =  nonceRes.();

      
       now =  ();
       message = ({
        : ..,
        : connectedAddress,
        chainId,
        nonce,
        : ..,
        : ,
        statement,
        : now,
        :  (now.() + messageExpirationMinutes *  * ),
      });

      
       signature =  ({ message });

      
       verifyRes =  (, {
        : ,
        : { :  },
        : .({ message, signature }),
      });

       (!verifyRes.) {
         errorData =  verifyRes.();
          (errorData. || );
      }

       result =  verifyRes.();
      ( ({
        ...prev,
        : ,
        : result.,
        : result.,
        : message,
        :  ().(),
        : ,
      }));
    }  (e) {
      ( ({
        ...prev,
        : ,
        : e   ? e. : ,
      }));
    }
  }, [connectedAddress, chainId, signMessageAsync]);

   signOut = ( () => {
     (, { :  });
    ( ({
      ...prev,
      : ,
      : ,
      : ,
      : ,
      : ,
      : ,
    }));
  }, []);

   {
    ...state,
    : isConnected,
    connectedAddress,
    signIn,
    signOut,
    checkSession,
  };
}

Key hook behaviors:

• Checks session on mount so refreshing the page preserves auth state
• Auto-signs out when wallet disconnects or address changes
• Uses a hasSeenWalletConnected ref to avoid false auto-logout on initial page load (when wallet reconnects asynchronously)
• Separate connectedAddress (current wallet) vs address (authenticated session) — these can differ if the user switches wallets

Gotchas and Pitfalls

Nonce must be fetched fresh before each sign-in attempt. The nonce is single-use and stored server-side. If the user cancels signing or the request fails, they need a new nonce. The signIn function handles this by always fetching a fresh nonce first.

Domain validation is critical for security. The verify route checks that the SIWE message's domain matches the Host header. In production behind a reverse proxy, ensure the Host header is forwarded correctly, or domain verification will fail.

Message expiration window. The SIWE message includes expirationTime (default: 10 minutes from creation). If the user takes too long to sign, verification fails. This is configurable in siwe.config.ts.

ERC-6492 smart wallet support. Viem's verifySiweMessage supports ERC-6492 signatures automatically, meaning smart contract wallets (Safe, Argent, etc.) work out of the box. The verify route creates a public client for the signer's chain to enable on-chain verification of smart wallet signatures.

SUPPORTED_CHAINS in the verify route must include all chains your app supports. If a user signs from a chain not in the map, verification is rejected with a 400 error. Add any chains your SE-2 project targets.

Auto-logout timing on wallet changes. The hook watches isConnected and signs out when the wallet disconnects. But on page refresh, the wallet reconnects asynchronously, causing a brief isConnected: false state. The hasSeenWalletConnected ref prevents this from triggering a false logout.

Session vs wallet address mismatch. After signing in, a user could switch to a different wallet address without signing out. The hook exposes both address (session) and connectedAddress (current wallet) — compare them if you need to detect this mismatch and prompt re-authentication.

iron-session cookie size limits. Cookies are limited to ~4KB. The session data is small (address, chainId, timestamps), so this is rarely an issue, but don't try to store large payloads in the session.

Server-side session checks. To protect API routes or server components, use getIronSession with the same sessionOptions and check session.isLoggedIn. Don't rely on client-side checks alone for sensitive operations.

The hook returns these properties:

Property	Type	Description
isSignedIn	boolean	Whether user has an active SIWE session
address	string | undefined	Authenticated wallet address
chainId	number | undefined	Chain ID from signed message
signedInAt	string | undefined	ISO timestamp of sign-in
isLoading	boolean	Loading state during sign-in/session check
error	string | undefined	Error message from last operation
siweMessage	string | undefined	The raw SIWE message that was signed
isWalletConnected	boolean	Whether any wallet is currently connected
connectedAddress	string | undefined	Current wallet address (may differ from session)
signIn	() => Promise<void>	Initiate SIWE sign-in flow
signOut	() => Promise<void>	Destroy session and sign out
checkSession	() => Promise<void>	Manually recheck session state

How to Test

1. Start the frontend: yarn start
2. Connect a wallet — MetaMask, Coinbase Wallet, and the burner wallet all support personal_sign which is what SIWE uses
3. Click "Sign In" — review the SIWE message in the wallet popup, confirm
4. The session persists across page refreshes (encrypted cookie)
5. Disconnect wallet or click "Sign Out" to end the session

Production:

1. In production make sure to set IRON_SESSION_SECRET environment variable to a secure 32+ character random string