Constructors

Methods for creating SIWE message instances

Try it Live

Run SIWE examples in the interactive playground

Constructors

Methods for creating SIWE message instances.

create

Create new SIWE message with automatic defaults.

Signature

function create<
  TDomain extends string,
  TAddress extends AddressType,
  TUri extends string,
  TChainId extends number
>(params: {
  domain: TDomain;
  address: TAddress;
  uri: TUri;
  chainId: TChainId;
  statement?: string;
  expirationTime?: string;
  notBefore?: string;
  requestId?: string;
  resources?: string[];
  nonce?: string;
  issuedAt?: string;
}): BrandedMessage<TDomain, TAddress, TUri, "1", TChainId>

Parameters

Required:

• domain - RFC 4501 dns authority requesting signing
• address - AddressType performing signing (20 bytes)
• uri - RFC 3986 URI referring to subject of signing
• chainId - EIP-155 Chain ID (positive integer)

Optional:

• statement - Human-readable ASCII assertion
• expirationTime - ISO 8601 datetime for expiration
• notBefore - ISO 8601 datetime for not-before
• requestId - System-specific identifier
• resources - Array of resource URIs
• nonce - Custom nonce (auto-generated if omitted, min 8 chars)
• issuedAt - Custom issued time (current time if omitted)

Returns

BrandedMessage with:

• version automatically set to "1"
• nonce auto-generated if not provided (11 chars, base62)
• issuedAt auto-set to current ISO 8601 time if not provided
• Optional fields only included if provided

Example

// Minimal creation
const message = Siwe.create({
  domain: "example.com",
  address: Address("0x742d35Cc6634C0532925a3b844Bc9e7595f251e3"),
  uri: "https://example.com/login",
  chainId: 1,
});
// Auto-generates nonce and issuedAt, sets version to "1"

// Full creation with optional fields
const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com/login",
  chainId: 1,
  statement: "Sign in to access your account",
  expirationTime: "2025-12-31T23:59:59.000Z",
  notBefore: "2025-01-01T00:00:00.000Z",
  requestId: "req-abc123",
  resources: [
    "https://example.com/api/admin",
    "https://example.com/api/users",
  ],
  nonce: "customnonce12345",
  issuedAt: "2025-06-01T12:00:00.000Z",
});

// Chain-specific authentication
const mainnetAuth = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 1,  // Ethereum mainnet
});

const polygonAuth = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 137,  // Polygon
});

Type Safety

Generic parameters preserve exact types:

const message = Siwe.create({
  domain: "example.com" as const,
  address: specificAddress,
  uri: "https://example.com" as const,
  chainId: 1 as const,
});
// message.domain: "example.com" (literal type)
// message.chainId: 1 (literal type)
// message.version: "1" (always literal "1")

Notes

• Nonce generation: Uses crypto.getRandomValues() for secure randomness
• Timestamp format: ISO 8601 format required for all timestamps
• Version: Always “1” per EIP-4361 current specification
• Optional fields: Only present in returned object if provided (no undefined)
• Address format: Must be valid 20-byte AddressType

Common Use Cases

Session with Expiration

const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 1,
  expirationTime: new Date(Date.now() + 3600000).toISOString(),  // 1 hour
});

Resource-Restricted Access

const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com/admin",
  chainId: 1,
  statement: "Grant admin access",
  resources: [
    "https://example.com/api/admin/users",
    "https://example.com/api/admin/settings",
  ],
});

Delayed Activation

const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 1,
  notBefore: new Date(Date.now() + 60000).toISOString(),  // Valid in 1 minute
  expirationTime: new Date(Date.now() + 3600000).toISOString(),  // Expires in 1 hour
});

Request Tracking

const requestId = crypto.randomUUID();
const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 1,
  requestId,
});
storeAuthRequest(requestId, { address: userAddress, timestamp: Date.now() });

Implementation Details

• Uses conditional spreading for optional fields (no undefined values)
• Delegates nonce generation to generateNonce()
• Current timestamp from new Date().toISOString()
• Version hardcoded to “1” per EIP-4361 spec
• Returns plain object (not class instance)

See Also

• Siwe.parse - Parse from formatted string
• Siwe.generateNonce - Nonce generation
• Message Format - EIP-4361 format specification
• Validation - Message validation rules