SIWE (Sign-In With Ethereum)

​

What it does

1. Frontend asks Pylon for a fresh nonce for the user’s address.
2. Frontend builds an EIP-4361 message (Sign in to acme.com\n\nAddress: 0x...\n...nonce: ...\n...) and asks the user’s wallet to sign it via personal_sign.
3. Pylon recovers the address from the signature using secp256k1 ECDSA and Keccak-256 (Ethereum’s variant). It validates the message’s domain, nonce, and expiry, then mints a session keyed on the wallet.

​

Endpoints

​

Schema

import { entity, field } from "@pylonsync/sdk";

export const User = entity("User", {
  email: field.string().optional(),
  walletAddress: field.string().optional().unique(),  // 0x + 40 hex chars, lowercase
  displayName: field.string(),
  createdAt: field.string(),
});

​

Sign-in flow

​

1. Request a nonce

curl 'https://your-app/api/auth/siwe/nonce?address=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0'

{ "nonce": "abc123def456..." }

​

2. Build and sign the message

import { SiweMessage } from "siwe";  // npm install siwe

const { nonce } = await fetch(
  `/api/auth/siwe/nonce?address=${address}`,
).then((r) => r.json());

const message = new SiweMessage({
  domain: window.location.host,        // must match Pylon's Host header
  address,
  statement: "Sign in to Acme",
  uri: window.location.origin,
  version: "1",
  chainId: 1,
  nonce,
  issuedAt: new Date().toISOString(),
});

const prepared = message.prepareMessage();
const signature = await ethereum.request({
  method: "personal_sign",
  params: [prepared, address],
});

​

3. Verify

curl -X POST https://your-app/api/auth/siwe/verify \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "<EIP-4361 plaintext message>",
    "signature": "0x...",
    "displayName": "vitalik.eth"
  }'

{
  "token": "pylon_...",
  "user_id": "usr_xyz",
  "address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb0",
  "expires_at": 1737592000
}

​

Verification details

• Signature recovery: secp256k1 ECDSA and a Keccak-256 hash of the EIP-191 prefix (\x19Ethereum Signed Message:\n<len>) followed by the message recover a 20-byte address. It must match message.address, case-insensitive.
• Nonce: the nonce must exist in the nonce store, bind to message.address, and be single-use. Pylon consumes it on first verify.
• Domain: message.domain must match the request’s Host header. This stops replay across deployments.
• Issued and expiration: if message.expirationTime is set, it must be in the future. If message.notBefore is set, it must be in the past.

​

Security guarantees

• secp256k1 and Keccak-256: Pylon uses the k256 crate, the same audited primitives Ethereum uses.
• Nonce binding to address: using nonce-for-A to sign in as B fails verification.
• Single-use nonces: Pylon consumes each nonce on first verify, regardless of success.
• Domain pinning: Pylon validates message.domain against the Host header and rejects replay across deployments.
• Expiration enforcement: Pylon honors expirationTime and notBefore.
• EIP-191 prefix: Pylon applies it correctly, which defeats signature reuse from any other Ethereum-signed payload.

​

Where to go next

• Sessions: what /siwe/verify mints.
• OAuth: other identity providers for the same user. Link multiple sign-in methods to one account.