AppKit provides a simple solution for integrating with “Sign In With Ethereum” (SIWE), a new form of authentication that enables users to control their digital identity with their Ethereum account.
SIWE is a standard also known as EIP-4361.
One-Click Auth represents a key advancement within WalletConnect v2, streamlining the user authentication process in AppKit by enabling them to seamlessly connect with a wallet and sign a SIWE message with just one click.
It supports both EIP-1271, the standard for signature validation in smart accounts, and EIP-6492, which enables signature validation for smart accounts (contracts) that are not yet deployed, allowing messages to be signed without requiring prior deployment.
Connecting a wallet, proving control of an address with an off-chain signature, authorizing specific actions. These are the kinds of authorizations that can be encoded as “ReCaps”. ReCaps are permissions for a specific website or dapp that can be compactly encoded as a long string in the message you sign and translated by any wallet into a straight-forward one-sentence summary.
reown uses permissions expressed as ReCaps to enable a One-Click Authentication.
If you are not using our library on the server-side, please normalize the address with eip-55 in the createMessage function. You can check our example for that Functionality.
Copy
import { SiweMessage } from "siwe";import { type SIWESession, type SIWEVerifyMessageArgs, type SIWECreateMessageArgs, createSIWEConfig, formatMessage,} from "@reown/appkit-siwe";const BASE_URL = "http://localhost:8080";/* Function that returns the user's session - this should come from your SIWE backend */async function getSession() { const res = await fetch(BASE_URL + "/session", { method: "GET", headers: { "Content-Type": "application/json", }, credentials: "include", }); if (!res.ok) { throw new Error("Network response was not ok"); } const data = await res.json(); const isValidData = typeof data === "object" && typeof data.address === "string" && typeof data.chainId === "number"; return isValidData ? (data as SIWESession) : null;}/* Use your SIWE server to verify if the message and the signature are valid */const verifyMessage = async ({ message, signature }: SIWEVerifyMessageArgs) => { try { const response = await fetch(BASE_URL + "/verify", { method: "POST", headers: { Accept: "application/json", "Content-Type": "application/json", }, mode: "cors", body: JSON.stringify({ message, signature }), credentials: "include", }); if (!response.ok) { return false; } const result = await response.json(); return result === true; } catch (error) { return false; }};// Check the full example for signOut and getNonce functions .../* Create a SIWE configuration object */export const siweConfig = createSIWEConfig({ getMessageParams: async () => ({ domain: window.location.host, uri: window.location.origin, chains: [1, 2020], statement: "Please sign with your account", }), createMessage: ({ address, ...args }: SIWECreateMessageArgs) => formatMessage(args, address), getNonce: async () => { //This is only an example, substitute it with your actual nonce getter. const nonce = "YOUR_NONCE_GETTER"; if (!nonce) { throw new Error("Failed to get nonce!"); } return nonce; }, getSession, verifyMessage, signOut: async () => { //Example // Implement your Sign out function },});
GET ‘/nonce’: Generates and returns a nonce (single-use random number).
POST ‘/verify’: Uses the Siwe protocol to verify the message, requiring a signature (the one you are going to approve throw the UX) and a nonce stored in the session.
GET ‘/session’: Retrieves the stored Siwe object from the session.
GET ‘/signout’: Clears the session.
Copy
import cors from "cors";import express from "express";import Session from "express-session";import { generateNonce } from "siwe";import { /*verifySignature,*/ getAddressFromMessage, getChainIdFromMessage,} from "@reown/appkit-siwe";import { createPublicClient, http } from "viem";const app = express();const projectId = "YOUR_PROJECT_ID";// configure cors and sessionsapp.use( cors({ origin: "http://localhost:5173", // frontend URL credentials: true, }));app.use(express.json());app.use( Session({ name: "siwe-quickstart", secret: "siwe-quickstart-secret", resave: true, saveUninitialized: true, cookie: { secure: false, sameSite: true }, }));app.get("/nonce", function (_, res) { res.setHeader("Content-Type", "text/plain"); res.send(generateNonce());});// verify the messageapp.post("/verify", async (req, res) => { try { if (!req.body.message) { return res.status(400).json({ error: "SiweMessage is undefined" }); } // save the session with the address and chainId (SIWESession) req.session.siwe = { address, chainId }; req.session.save(() => res.status(200).send(true)); const message = req.body.message; const signature = req.body.signature; const address = getAddressFromMessage(message); let chainId = getChainIdFromMessage(message); // for the moment, the verifySignature is not working with social logins and emails with non deployed smart accounts // for this reason we recommend using the viem to verify the signature const publicClient = createPublicClient({ transport: http( `https://rpc.walletconnect.org/v1/?chainId=${chainId}&projectId=${projectId}` ), }); const isValid = await publicClient.verifyMessage({ message, address, signature, }); if (!isValid) { // throw an error if the signature is invalid throw new Error("Invalid signature"); } if (chainId.includes(":")) { chainId = chainId.split(":")[1]; } // Convert chainId to a number chainId = Number(chainId); if (isNaN(chainId)) { throw new Error("Invalid chainId"); } // save the session with the address and chainId (SIWESession) req.session.siwe = { address, chainId }; req.session.save(() => res.status(200).send(true)); } catch (e) { // clean the session req.session.siwe = null; req.session.nonce = null; req.session.save(() => res.status(500).json({ message: e.message })); }});/// ... check the github repository for the others endpoints// get the sessionapp.get("/session", (req, res) => { res.setHeader("Content-Type", "application/json"); res.send(req.session.siwe);});
Check the github full example to see the full flow working: siwe-quickstart
import { createPublicClient, http } from "viem";const publicClient = createPublicClient({ transport: http( `https://rpc.walletconnect.org/v1/?chainId=${chainId}&projectId=${projectId}` ),});const isValid = await publicClient.verifyMessage({ message, address: address as `0x${string}`, signature: signature as `0x${string}`,});// The verifySignature is not working with social logins and emails with non deployed smart accounts// for this reason we recommend using the viem to verify the signature// import { verifySignature } from '@reown/appkit-siwe'// const isValid = await verifySignature({ address, message, signature, chainId, projectId })
If you are not using our library on the server-side, please normalize the address with eip-55 in the createMessage function. You can check our example for that Functionality.
Copy
import { SiweMessage } from "siwe";import { type SIWESession, type SIWEVerifyMessageArgs, type SIWECreateMessageArgs, createSIWEConfig, formatMessage,} from "@reown/appkit-siwe";const BASE_URL = "http://localhost:8080";/* Function that returns the user's session - this should come from your SIWE backend */async function getSession() { const res = await fetch(BASE_URL + "/session", { method: "GET", headers: { "Content-Type": "application/json", }, credentials: "include", }); if (!res.ok) { throw new Error("Network response was not ok"); } const data = await res.json(); const isValidData = typeof data === "object" && typeof data.address === "string" && typeof data.chainId === "number"; return isValidData ? (data as SIWESession) : null;}/* Use your SIWE server to verify if the message and the signature are valid */const verifyMessage = async ({ message, signature }: SIWEVerifyMessageArgs) => { try { const response = await fetch(BASE_URL + "/verify", { method: "POST", headers: { Accept: "application/json", "Content-Type": "application/json", }, mode: "cors", body: JSON.stringify({ message, signature }), credentials: "include", }); if (!response.ok) { return false; } const result = await response.json(); return result === true; } catch (error) { return false; }};// Check the full example for signOut and getNonce functions .../* Create a SIWE configuration object */export const siweConfig = createSIWEConfig({ getMessageParams: async () => ({ domain: window.location.host, uri: window.location.origin, chains: [1, 2020], statement: "Please sign with your account", }), createMessage: ({ address, ...args }: SIWECreateMessageArgs) => formatMessage(args, address), getNonce: async () => { //This is only an example, substitute it with your actual nonce getter. const nonce = "YOUR_NONCE_GETTER"; if (!nonce) { throw new Error("Failed to get nonce!"); } return nonce; }, getSession, verifyMessage, signOut: async () => { //Example // Implement your Sign out function },});
GET ‘/nonce’: Generates and returns a nonce (single-use random number).
POST ‘/verify’: Uses the Siwe protocol to verify the message, requiring a signature (the one you are going to approve throw the UX) and a nonce stored in the session.
GET ‘/session’: Retrieves the stored Siwe object from the session.
GET ‘/signout’: Clears the session.
Copy
import cors from "cors";import express from "express";import Session from "express-session";import { generateNonce } from "siwe";import { /*verifySignature,*/ getAddressFromMessage, getChainIdFromMessage,} from "@reown/appkit-siwe";import { createPublicClient, http } from "viem";const app = express();const projectId = "YOUR_PROJECT_ID";// configure cors and sessionsapp.use( cors({ origin: "http://localhost:5173", // frontend URL credentials: true, }));app.use(express.json());app.use( Session({ name: "siwe-quickstart", secret: "siwe-quickstart-secret", resave: true, saveUninitialized: true, cookie: { secure: false, sameSite: true }, }));app.get("/nonce", function (_, res) { res.setHeader("Content-Type", "text/plain"); res.send(generateNonce());});// verify the messageapp.post("/verify", async (req, res) => { try { if (!req.body.message) { return res.status(400).json({ error: "SiweMessage is undefined" }); } // save the session with the address and chainId (SIWESession) req.session.siwe = { address, chainId }; req.session.save(() => res.status(200).send(true)); const message = req.body.message; const signature = req.body.signature; const address = getAddressFromMessage(message); let chainId = getChainIdFromMessage(message); // for the moment, the verifySignature is not working with social logins and emails with non deployed smart accounts // for this reason we recommend using the viem to verify the signature const publicClient = createPublicClient({ transport: http( `https://rpc.walletconnect.org/v1/?chainId=${chainId}&projectId=${projectId}` ), }); const isValid = await publicClient.verifyMessage({ message, address, signature, }); if (!isValid) { // throw an error if the signature is invalid throw new Error("Invalid signature"); } if (chainId.includes(":")) { chainId = chainId.split(":")[1]; } // Convert chainId to a number chainId = Number(chainId); if (isNaN(chainId)) { throw new Error("Invalid chainId"); } // save the session with the address and chainId (SIWESession) req.session.siwe = { address, chainId }; req.session.save(() => res.status(200).send(true)); } catch (e) { // clean the session req.session.siwe = null; req.session.nonce = null; req.session.save(() => res.status(500).json({ message: e.message })); }});/// ... check the github repository for the others endpoints// get the sessionapp.get("/session", (req, res) => { res.setHeader("Content-Type", "application/json"); res.send(req.session.siwe);});
Check the github full example to see the full flow working: siwe-quickstart
import { createPublicClient, http } from "viem";const publicClient = createPublicClient({ transport: http( `https://rpc.walletconnect.org/v1/?chainId=${chainId}&projectId=${projectId}` ),});const isValid = await publicClient.verifyMessage({ message, address: address as `0x${string}`, signature: signature as `0x${string}`,});// The verifySignature is not working with social logins and emails with non deployed smart accounts// for this reason we recommend using the viem to verify the signature// import { verifySignature } from '@reown/appkit-siwe'// const isValid = await verifySignature({ address, message, signature, chainId, projectId })
With help of the siwe package we will create the required configuration for AppKit.
The nonce and verification process will be implemented in your backend. Read more.
Copy
import { SiweMessage } from 'siwe'import type { SIWECreateMessageArgs, SIWEVerifyMessageArgs } from '@reown/appkit-siwe'/* Function that creates a SIWE message */function createMessage({ nonce, address, chainId }: SIWECreateMessageArgs){ const message = new SiweMessage({ version: '1', domain: window.location.host, uri: window.location.origin, address, chainId, nonce, statement: 'Sign in With Ethereum.' }) return message.prepareMessage()}/* Function that returns the user's session */async function getSession(){ //...}/* Use your SIWE server to verify if the message and the signature are valid */async function verifyMessage({ message, signature }: SIWEVerifyMessageArgs){ try { const isValid = await validateMessage({ message, signature }) return isValid } catch (error) { return false }},/* Create a SIWE configuration object */export const siweConfig = createSIWEConfig({ createMessage, getNonce: async () => { //This is only an example, substitute it with your actual nonce getter. const nonce = "YOUR_NONCE_GETTER" if (!nonce) { throw new Error('Failed to get nonce!') } return nonce }, getSession, verifyMessage, signOut: async () => { //Example // Implement your Sign out function }})
The getNonce method functions as a safeguard against spoofing, akin to a CSRF token. The siwe package provides a generateNonce() helper, or you can utilize an existing CSRF token from your backend if available.
The official siwe package offers a straightforward method for generating an EIP-4361-compatible message, which can subsequently be authenticated using the same package. The nonce parameter is derived from your getNonce endpoint, while the address and chainId variables are sourced from the presently connected wallet.
The getNonce method functions as a safeguard against spoofing, akin to a CSRF token. The siwe package provides a generateNonce() helper, or you can utilize an existing CSRF token from your backend if available.
The official siwe package offers a straightforward method for generating an EIP-4361-compatible message, which can subsequently be authenticated using the same package. The nonce parameter is derived from your getNonce endpoint, while the address and chainId variables are sourced from the presently connected wallet.
The getNonce method functions as a safeguard against spoofing, akin to a CSRF token. The siwe package provides a generateNonce() helper, or you can utilize an existing CSRF token from your backend if available.
The official siwe package offers a straightforward method for generating an EIP-4361-compatible message, which can subsequently be authenticated using the same package. The nonce parameter is derived from your getNonce endpoint, while the address and chainId variables are sourced from the presently connected wallet.