Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/better-auth

better-auth

Verified

references/clippings/siwe-plugin.md

View on GitHub
---
title: "Sign In With Ethereum (SIWE) | Better Auth"
source: "https://www.better-auth.com/docs/plugins/siwe"
author:
  - "[[Device Authorization]]"
published:
created: 2025-12-16
description: "Sign in with Ethereum plugin for Better Auth"
tags:
  - "clippings"
---
## Sign In With Ethereum (SIWE)

The Sign in with Ethereum (SIWE) plugin allows users to authenticate using their Ethereum wallets following the [ERC-4361 standard](https://eips.ethereum.org/EIPS/eip-4361). This plugin provides flexibility by allowing you to implement your own message verification and nonce generation logic.

## Installation

### Add the Server Plugin

Add the SIWE plugin to your auth configuration:

auth.ts

```
import { betterAuth } from "better-auth";

import { siwe } from "better-auth/plugins";

export const auth = betterAuth({

    plugins: [

        siwe({

            domain: "example.com",

            emailDomainName: "example.com", // optional

            anonymous: false, // optional, default is true

            getNonce: async () => {

                // Implement your nonce generation logic here

                return "your-secure-random-nonce";

            },

            verifyMessage: async (args) => {

                // Implement your SIWE message verification logic here

                // This should verify the signature against the message

                return true; // return true if signature is valid

            },

            ensLookup: async (args) => {

                // Optional: Implement ENS lookup for user names and avatars

                return {

                    name: "user.eth",

                    avatar: "https://example.com/avatar.png"

                };

            },

        }),

    ],

});
```

### Migrate the database

Run the migration or generate the schema to add the necessary fields and tables to the database.

```
npx @better-auth/cli migrate
```

```
npx @better-auth/cli generate
```

See the [Schema](https://www.better-auth.com/docs/plugins/#schema) section to add the fields manually.

### Add the Client Plugin

auth-client.ts

```
import { createAuthClient } from "better-auth/client";

import { siweClient } from "better-auth/client/plugins";

export const authClient = createAuthClient({

    plugins: [siweClient()],

});
```

## Usage

### Generate a Nonce

Before signing a SIWE message, you need to generate a nonce for the wallet address:

generate-nonce.ts

```
const { data, error } = await authClient.siwe.nonce({

  walletAddress: "0x1234567890abcdef1234567890abcdef12345678",

  chainId: 1, // optional for Ethereum mainnet, required for other chains. Defaults to 1

});

if (data) {

  console.log("Nonce:", data.nonce);

}
```

### Sign In with Ethereum

After generating a nonce and creating a SIWE message, verify the signature to authenticate:

sign-in-siwe.ts

```
const { data, error } = await authClient.siwe.verify({

  message: "Your SIWE message string",

  signature: "0x...", // The signature from the user's wallet

  walletAddress: "0x1234567890abcdef1234567890abcdef12345678",

  chainId: 1, // optional for Ethereum mainnet, required for other chains. Must match Chain ID in SIWE message

  email: "user@example.com", // optional, required if anonymous is false

});

if (data) {

  console.log("Authentication successful:", data.user);

}
```

### Chain-Specific Examples

Here are examples for different blockchain networks:

ethereum-mainnet.ts

```
// Ethereum Mainnet (chainId can be omitted, defaults to 1)

const { data, error } = await authClient.siwe.verify({

  message,

  signature,

  walletAddress,

  // chainId: 1 (default)

});
```

polygon.ts

```
// Polygon (chainId REQUIRED)

const { data, error } = await authClient.siwe.verify({

  message,

  signature,

  walletAddress,

  chainId: 137, // Required for Polygon

});
```

arbitrum.ts

```
// Arbitrum (chainId REQUIRED)

const { data, error } = await authClient.siwe.verify({

  message,

  signature,

  walletAddress,

  chainId: 42161, // Required for Arbitrum

});
```

base.ts

```
// Base (chainId REQUIRED)

const { data, error } = await authClient.siwe.verify({

  message,

  signature,

  walletAddress,

  chainId: 8453, // Required for Base

});
```

The `chainId` must match the Chain ID specified in your SIWE message. Verification will fail with a 401 error if there's a mismatch between the message's Chain ID and the `chainId` parameter.

## Configuration Options

### Server Options

The SIWE plugin accepts the following configuration options:

- **domain**: The domain name of your application (required for SIWE message generation)
- **emailDomainName**: The email domain name for creating user accounts when not using anonymous mode. Defaults to the domain from your base URL
- **anonymous**: Whether to allow anonymous sign-ins without requiring an email. Default is `true`
- **getNonce**: Function to generate a unique nonce for each sign-in attempt. You must implement this function to return a cryptographically secure random string. Must return a `Promise<string>`
- **verifyMessage**: Function to verify the signed SIWE message. Receives message details and should return `Promise<boolean>`
- **ensLookup**: Optional function to lookup ENS names and avatars for Ethereum addresses

### Client Options

The SIWE client plugin doesn't require any configuration options, but you can pass them if needed for future extensibility:

auth-client.ts

```
import { createAuthClient } from "better-auth/client";

import { siweClient } from "better-auth/client/plugins";

export const authClient = createAuthClient({

  plugins: [

    siweClient({

      // Optional client configuration can go here

    }),

  ],

});
```

## Schema

The SIWE plugin adds a `walletAddress` table to store user wallet associations:

| Field | Type | Description |
| --- | --- | --- |
| id | string | Primary key |
| userId | string | Reference to user.id |
| address | string | Ethereum wallet address |
| chainId | number | Chain ID (e.g., 1 for Ethereum mainnet) |
| isPrimary | boolean | Whether this is the user's primary wallet |
| createdAt | date | Creation timestamp |

## Example Implementation

Here's a complete example showing how to implement SIWE authentication:

auth.ts

```
import { betterAuth } from "better-auth";

import { siwe } from "better-auth/plugins";

import { generateRandomString } from "better-auth/crypto";

import { verifyMessage, createPublicClient, http } from "viem";

import { mainnet } from "viem/chains";

export const auth = betterAuth({

  database: {

    // your database configuration

  },

  plugins: [

    siwe({

      domain: "myapp.com",

      emailDomainName: "myapp.com",

      anonymous: false,

      getNonce: async () => {

        // Generate a cryptographically secure random nonce

        return generateRandomString(32, "a-z", "A-Z", "0-9");

      },

      verifyMessage: async ({ message, signature, address }) => {

        try {

          // Verify the signature using viem (recommended)

          const isValid = await verifyMessage({

            address: address as \`0x${string}\`,

            message,

            signature: signature as \`0x${string}\`,

          });

          return isValid;

        } catch (error) {

          console.error("SIWE verification failed:", error);

          return false;

        }

      },

      ensLookup: async ({ walletAddress }) => {

        try {

          // Optional: lookup ENS name and avatar using viem

          // You can use viem's ENS utilities here

          const client = createPublicClient({

            chain: mainnet,

            transport: http(),

          });

          const ensName = await client.getEnsName({

            address: walletAddress as \`0x${string}\`,

          });

          const ensAvatar = ensName

            ? await client.getEnsAvatar({

                name: ensName,

              })

            : null;

          return {

            name: ensName || walletAddress,

            avatar: ensAvatar || "",

          };

        } catch {

          return {

            name: walletAddress,

            avatar: "",

          };

        }

      },

    }),

  ],

});
```

[Edit on GitHub](https://github.com/better-auth/better-auth/blob/canary/docs/content/docs/plugins/siwe.mdx)[Previous Page](https://www.better-auth.com/docs/plugins/one-tap)

[

One Tap

](https://www.better-auth.com/docs/plugins/one-tap)

Next Page

Authorization
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall