SIWA Documentation

Authentication Flow

1. 1.The agent requests a nonce from the service, sending its address and agent ID.
2. 2.The service returns the nonce along with timestamps.
3. 3.The agent builds a SIWA message and signs it with its wallet.
4. 4.The agent sends the message and signature to the service.
5. 5.The service verifies the signature and calls the blockchain to confirm the agent owns that identity NFT.
6. 6.If verified, the service returns a receipt. The agent uses this for subsequent authenticated requests.

The SDK provides two main functions:

• •Agent-side: signSIWAMessage(fields, signer) — builds and signs the message
• •Server-side: verifySIWA(message, signature, domain, nonceValid, client, criteria?) — validates signature and checks onchain ownership

Bankr

Bankr's Agent API provides smart contract wallets (ERC-4337) for AI agents with built-in signing capabilities. No additional SDK is needed — the signer communicates directly with the Bankr API over HTTP. Signatures are verified via ERC-1271 automatically.

# No extra package needed — only @buildersgarden/siwa

Create a signer from your Bankr API key:

import { signSIWAMessage } from "@buildersgarden/siwa";
import { createBankrSiwaSigner } from "@buildersgarden/siwa/signer";

...

Already using Bankr's OpenClaw trading skill for swaps and DeFi? This signer adds SIWA authentication on top — same API key, same wallet.

Circle

Circle's developer-controlled wallets provide secure key management for AI agents. Install the Circle SDK alongside SIWA:

npm install @circle-fin/developer-controlled-wallets

Create a signer from your Circle wallet credentials:

import { signSIWAMessage } from "@buildersgarden/siwa";
import { createCircleSiwaSigner } from "@buildersgarden/siwa/signer";

...

If you already have a Circle client instance, use createCircleSiwaSignerFromClient:

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
import { createCircleSiwaSignerFromClient } from "@buildersgarden/siwa/signer";

...

Openfort

Openfort's backend wallets provide secure key management and account abstraction for AI agents. Install the Openfort Node SDK alongside SIWA:

npm install @openfort/openfort-node

Create a signer from your Openfort wallet credentials:

import { signSIWAMessage } from "@buildersgarden/siwa";
import { createOpenfortSiwaSigner } from "@buildersgarden/siwa/signer";

...

If you already have an Openfort client instance, use createOpenfortSiwaSignerFromClient:

import Openfort from "@openfort/openfort-node";
import { createOpenfortSiwaSignerFromClient } from "@buildersgarden/siwa/signer";

...

Privy

Privy's server wallets provide embedded wallet infrastructure for AI agents. Install the Privy Node SDK alongside SIWA:

npm install @privy-io/node

Create a signer from your Privy wallet:

import { PrivyClient } from "@privy-io/node";
import { signSIWAMessage } from "@buildersgarden/siwa";
import { createPrivySiwaSigner } from "@buildersgarden/siwa/signer";
...

Private Key (Backend Scripts)

For server-side agents or scripts with direct private key access:

import { signSIWAMessage } from "@buildersgarden/siwa";
import { createLocalAccountSigner } from "@buildersgarden/siwa/signer";
import { privateKeyToAccount } from "viem/accounts";
...

Keyring Proxy (Self-Hosted, Non-Custodial)

For AI agents that need secure key isolation, we provide an optional keyring proxy — a separate service that holds the encrypted private key and performs all signing. The agent never touches the key.

import { signSIWAMessage } from "@buildersgarden/siwa";
import { createKeyringProxySigner } from "@buildersgarden/siwa/signer";

...

The keyring proxy is completely optional. It's useful when you want:

• •Key isolation from the agent process (protection against prompt injection)
• •Optional 2FA via Telegram for transaction approval
• •Self-hosted, non-custodial key management

See Deploy for keyring proxy setup, architecture, and security model.

Smart Accounts

Smart contract wallets (Safe, ZeroDev/Kernel, Coinbase Smart Wallet) work with the same createWalletClientSigner — their SDKs expose a standard WalletClient or EIP-1193 provider. The SDK detects the signer type automatically during verification via ERC-1271.

import { signSIWAMessage } from "@buildersgarden/siwa";
import { createWalletClientSigner } from "@buildersgarden/siwa/signer";
import { createWalletClient, custom } from "viem";
...

SIWA Sign-In

Build and sign a SIWA message to prove ownership of an ERC-8004 identity. The authentication flow consists of two steps:

• 1.Get a nonce from the server's /siwa/nonce endpoint
• 2.Sign and verify by sending the signature to /siwa/verify

Import from @buildersgarden/siwa.

import { signSIWAMessage } from "@buildersgarden/siwa";

// Step 1: Request nonce from server
...

ERC-8128 Request Signing

After SIWA sign-in, sign every outgoing API request with ERC-8128 HTTP Message Signatures.

Import from @buildersgarden/siwa/erc8128.

import { signAuthenticatedRequest } from "@buildersgarden/siwa/erc8128";

const request = new Request("https://api.example.com/action", {
...

SIWA Verification

Verify a signed SIWA message, check onchain ownership, and optionally validate ERC-8004 agent profile criteria. Implement two endpoints:

• 1./siwa/nonce — Issue a nonce for the agent to sign
• 2./siwa/verify — Verify the signed message and issue a receipt

Import from @buildersgarden/siwa. Parameters:

Use criteria to enforce policies on which agents can authenticate. These are checked during sign-in and encoded into the receipt.

The result includes signerType and optionally agent (full profile if criteria fetched metadata).

// app/api/siwa/nonce/route.ts
import { createSIWANonce } from "@buildersgarden/siwa";
import { corsJson, siwaOptions } from "@buildersgarden/siwa/next";
...

// routes/siwa.ts
import express from "express";
import { createSIWANonce } from "@buildersgarden/siwa";
...

// src/routes/siwa.ts
import { Hono } from "hono";
import { cors } from "hono/cors";
...

// src/routes/siwa.ts
import { FastifyPluginAsync } from "fastify";
import { createSIWANonce } from "@buildersgarden/siwa";
...

// app/api/siwa/verify/route.ts
import { verifySIWA } from "@buildersgarden/siwa";
import { createReceipt } from "@buildersgarden/siwa/receipt";
...

// routes/siwa.ts (add to same router as nonce)
import { verifySIWA } from "@buildersgarden/siwa";
import { createReceipt } from "@buildersgarden/siwa/receipt";
...

// src/routes/siwa.ts (add to same app as nonce)
import { verifySIWA } from "@buildersgarden/siwa";
import { createReceipt } from "@buildersgarden/siwa/receipt";
...

// src/routes/siwa.ts (add to same plugin as nonce)
import { verifySIWA } from "@buildersgarden/siwa";
import { createReceipt } from "@buildersgarden/siwa/receipt";
...

ERC-8128 Request Verification

Verify incoming ERC-8128 signed requests from authenticated agents.

Import from @buildersgarden/siwa/erc8128. Options accept allowedSignerTypes for policy enforcement. The verified agent includes a signerType field.

Receipts

Stateless HMAC-signed tokens issued after successful SIWA verification. The agent includes the receipt in subsequent requests, and the server verifies it.

Import from @buildersgarden/siwa/receipt.

Server Middleware

Drop-in middleware for popular frameworks. Each handles ERC-8128 verification, receipt checking, and CORS.

// app/api/protected/route.ts
import { withSiwa, siwaOptions } from "@buildersgarden/siwa/next";

...

import express from "express";
import { siwaMiddleware, siwaJsonParser, siwaCors } from "@buildersgarden/siwa/express";
import { createPublicClient, http } from "viem";
...

import { Hono } from "hono";
import { siwaMiddleware, siwaCors } from "@buildersgarden/siwa/hono";
import { createPublicClient, http } from "viem";
...

import Fastify from "fastify";
import { siwaPlugin, siwaAuth } from "@buildersgarden/siwa/fastify";
import { createPublicClient, http } from "viem";
...

Nonce Store

Pluggable server-side nonce tracking for replay protection. The SDK ships built-in adapters for Memory, Redis, Cloudflare KV, and any SQL database — no extra dependencies, you bring your own client.

Why Nonces Matter

A SIWA message is valid for its entire TTL window (default 5 minutes). Without server-side tracking, an attacker who intercepts a signed message can replay it — submitting the same signature multiple times to authenticate as the agent.

A nonce store solves this by recording every issued nonce and consuming it on first use. Once consumed, the nonce is deleted and any replay attempt is rejected.

The SDK provides three nonce validation strategies:

• •Callback — (nonce) => boolean: you manage nonce storage yourself
• •Stateless token — { nonceToken, secret }: HMAC-signed token, no server storage needed (but replayable within TTL)
• •Nonce store — { nonceStore }: server-side tracking with exactly-once consumption (recommended for production)

The SIWANonceStore interface:

interface SIWANonceStore {
  /** Store an issued nonce. Returns true on success, false if already exists. */
  issue(nonce: string, ttlMs: number): Promise<boolean>;
  /** Atomically check-and-delete a nonce. Returns true if it existed. */
  consume(nonce: string): Promise<boolean>;
}

Wire the store into both createSIWANonce (issue) and verifySIWA (consume):

import { createSIWANonce, verifySIWA } from "@buildersgarden/siwa";
import { createMemorySIWANonceStore } from "@buildersgarden/siwa/nonce-store";

const nonceStore = createMemorySIWANonceStore();

// Nonce endpoint — issue
const result = await createSIWANonce(params, client, { nonceStore });

// Verify endpoint — consume
const verification = await verifySIWA(
  message, signature, domain,
  { nonceStore },
  client,
);

Memory (Default)

In-memory store using a Map with TTL-based expiry. Suitable for single-process servers. Nonces are lost on restart.

import { createMemorySIWANonceStore } from "@buildersgarden/siwa/nonce-store";

const nonceStore = createMemorySIWANonceStore();

Redis

Redis-backed store using SET ... PX ttl NX for atomic issue and DEL for atomic consume. Works with any Redis client that implements set() and del().

import { createRedisSIWANonceStore } from "@buildersgarden/siwa/nonce-store";

// ioredis (works out of the box)
import Redis from "ioredis";
const redis = new Redis();
const nonceStore = createRedisSIWANonceStore(redis);

For node-redis v4, wrap with a small adapter since its set() signature differs:

import { createClient } from "redis";
import { createRedisSIWANonceStore } from "@buildersgarden/siwa/nonce-store";

const client = createClient(); await client.connect();

const nonceStore = createRedisSIWANonceStore({
  set: (...args: unknown[]) =>
    client
      .set(args[0] as string, args[1] as string, {
        PX: args[3] as number,
        NX: true,
      })
      .then((r) => r ?? null),
  del: (key: unknown) => client.del(key as string),
});

Cloudflare KV

Cloudflare Workers KV-backed store. Uses put with expirationTtl for auto-expiry. The consume path does a get + delete — not fully atomic, but acceptable for random nonces.

import { createKVSIWANonceStore } from "@buildersgarden/siwa/nonce-store";

// In a Cloudflare Worker
export default {
  async fetch(request: Request, env: Env) {
    const nonceStore = createKVSIWANonceStore(env.SIWA_NONCES);
    // use with createSIWANonce / verifySIWA
  },
};

Bind a KV namespace called SIWA_NONCES in your wrangler.toml:

[[kv_namespaces]]
binding = "SIWA_NONCES"
id = "<your-kv-namespace-id>"

Database

For databases, implement SIWANonceStore directly — it's just two methods. No factory needed.

Schema — create a table with a unique nonce column and an expiry timestamp:

CREATE TABLE siwa_nonces (
  nonce      VARCHAR(64) PRIMARY KEY,
  expires_at TIMESTAMPTZ NOT NULL
);
-- Optional: periodic cleanup of expired rows
-- DELETE FROM siwa_nonces WHERE expires_at < NOW();

Prisma:

import type { SIWANonceStore } from "@buildersgarden/siwa/nonce-store";

const nonceStore: SIWANonceStore = {
  async issue(nonce, ttlMs) {
    try {
      await prisma.siwaNonce.create({
        data: { nonce, expiresAt: new Date(Date.now() + ttlMs) },
      });
      return true;
    } catch (e: any) {
      if (e.code === "P2002") return false; // unique constraint
      throw e;
    }
  },
  async consume(nonce) {
    try {
      await prisma.siwaNonce.delete({ where: { nonce } });
      return true;
    } catch {
      return false;
    }
  },
};

Drizzle:

import type { SIWANonceStore } from "@buildersgarden/siwa/nonce-store";
import { eq, and, gt } from "drizzle-orm";
import { siwaNonces } from "./schema";

const nonceStore: SIWANonceStore = {
  async issue(nonce, ttlMs) {
    try {
      await db.insert(siwaNonces).values({
        nonce,
        expiresAt: new Date(Date.now() + ttlMs),
      });
      return true;
    } catch (e: any) {
      if (e.code === "23505") return false; // unique violation
      throw e;
    }
  },
  async consume(nonce) {
    const result = await db
      .delete(siwaNonces)
      .where(
        and(
          eq(siwaNonces.nonce, nonce),
          gt(siwaNonces.expiresAt, new Date()),
        ),
      );
    return (result.rowCount ?? 0) > 0;
  },
};

Captcha (Reverse CAPTCHA)

SIWA includes a reverse CAPTCHA — inspired by MoltCaptcha — that proves an entity is an AI agent, not a human. Challenges exploit how LLMs generate text in a single autoregressive pass, satisfying multiple constraints simultaneously, while humans must iterate.

The server generates a challenge with constraints the agent must satisfy in its response text — line count, sum of ASCII values of first characters, word count, character at a specific position, and total character count. Higher difficulty levels add more constraints with tighter time limits.

Two integration points:

• •Sign-in flow — server requires captcha before issuing a nonce
• •Per-request — middleware randomly challenges agents during authenticated API calls (server-defined policy/probability)

Sign-In Captcha

Add captchaPolicy and captchaOptions to your nonce endpoint. The policy function receives the agent's identity and returns a difficulty level or null to skip.

import { createSIWANonce } from "@buildersgarden/siwa";

const result = await createSIWANonce(
  { address, agentId, agentRegistry, challengeResponse },
  client,
  {
    secret: SIWA_SECRET,
    captchaPolicy: async ({ address }) => {
      const known = await db.agents.exists(address);
      return known ? null : 'medium'; // challenge unknown agents
    },
    captchaOptions: { secret: SIWA_SECRET },
  },
);

// result.status is 'captcha_required' | 'nonce_issued' | SIWAResponse

Agent-side: use solveCaptchaChallenge() to detect and solve in one step.

import { solveCaptchaChallenge } from "@buildersgarden/siwa/captcha";

const res = await fetch("/api/siwa/nonce", {
  method: "POST",
  body: JSON.stringify({ address, agentId, agentRegistry }),
});
const data = await res.json();

const captcha = await solveCaptchaChallenge(data, async (challenge) => {
  // LLM generates text satisfying all constraints in a single pass
  // Your LLM generates text satisfying all constraints in one pass.
  // Use any provider (Anthropic, OpenAI, etc.) — just return a string.
  return await generateText(challenge);
});

if (captcha.solved) {
  // Retry with challengeResponse
  await fetch("/api/siwa/nonce", {
    method: "POST",
    body: JSON.stringify({ ...params, challengeResponse: captcha.challengeResponse }),
  });
}

Per-Request Captcha

Add captchaPolicy to middleware for random spot-checks on authenticated requests.

// Next.js
export const POST = withSiwa(handler, {
  captchaPolicy: ({ request }) => {
    if (request?.url.includes('/transfer') && Math.random() < 0.05)
      return 'hard';
    return null;
  },
  captchaOptions: { secret: process.env.SIWA_SECRET! },
});

// Express
app.use(siwaMiddleware({
  captchaPolicy: () => Math.random() < 0.05 ? 'easy' : null,
  captchaOptions: { secret: SIWA_SECRET },
}));

Agent-side: use retryWithCaptcha() to detect a 401 captcha challenge, solve it, re-sign with ERC-8128, and get a ready-to-send retry request.

import { signAuthenticatedRequest, retryWithCaptcha } from "@buildersgarden/siwa/erc8128";

const url = "https://api.example.com/action";
const body = JSON.stringify({ key: "value" });

// Sign and send
const signed = await signAuthenticatedRequest(
  new Request(url, { method: "POST", body }), receipt, signer, chainId,
);
const response = await fetch(signed);

// Detect + solve + re-sign if captcha required
const result = await retryWithCaptcha(
  response,
  new Request(url, { method: "POST", body }), // fresh request
  receipt, signer, chainId,
  async (challenge) => generateText(challenge), // your LLM solver
);

if (result.retry) {
  const retryResponse = await fetch(result.request);
}

Difficulty Levels & Configuration

All verification behavior is configurable via captchaOptions.verify:

Override difficulty settings per tier with captchaOptions.difficulties:

captchaOptions: {
  secret: SIWA_SECRET,
  verify: {
    useServerTiming: true,
    timingToleranceSeconds: 5,
    revealConstraints: false,
    consumeChallenge: (token) => redis.set(`captcha:${token}`, '1', 'NX', 'EX', 60).then(r => r === 'OK'),
  },
  difficulties: {
    easy: { timeLimitSeconds: 45 },
    extreme: { timeLimitSeconds: 8 },
  },
}

Import from @buildersgarden/siwa/captcha.

Overview

The x402 protocol adds pay-per-request monetization to any SIWA-protected endpoint. When a route requires payment, the middleware enforces a two-gate flow: SIWA authentication first, then payment verification. Both must pass before the handler runs.

1. 1.Agent sends a request with ERC-8128 SIWA headers (always required).
2. 2.Middleware verifies SIWA identity. If invalid, returns 401.
3. 3.If no Payment-Signature header is present, returns 402 with a Payment-Required header containing accepted payment options.
4. 4.Agent constructs a payment, encodes it as a Payment-Signature header, and retries.
5. 5.Middleware sends the payment to a facilitator for verification and on-chain settlement.
6. 6.On success, the handler runs and the response includes a Payment-Response header with the transaction hash.

Server Setup

Three things are needed to enable x402 on a route: a facilitator client (verifies and settles payments), a resource description, and an accepts array listing payment options.

import {
  createFacilitatorClient,
  type X402Config,
} from "@buildersgarden/siwa/x402";

// 1. Create facilitator client
const facilitator = createFacilitatorClient({
  url: "https://x402-facilitator.example.com",
});

// 2. Define x402 config
const x402: X402Config = {
  facilitator,
  resource: {
    url: "/api/premium",
    description: "Premium data access",
  },
  accepts: [
    {
      scheme: "exact",
      network: "eip155:84532",      // Base Sepolia
      amount: "1000000",             // 1 USDC (6 decimals)
      asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      payTo: "0xYourAddress",
      maxTimeoutSeconds: 60,
    },
  ],
};

Pass the x402 config to any framework middleware. Routes without x402 remain SIWA-only (free).

Sessions (Pay-Once)

By default, every request requires a new payment. Add session to the x402 config to enable pay-once mode: the agent pays on the first request and subsequent requests within the TTL window pass through without payment.

Sessions are keyed by (address, resource.url) — different agents and different routes are isolated from each other.

import {
  createFacilitatorClient,
  createMemoryX402SessionStore,
} from "@buildersgarden/siwa/x402";

const facilitator = createFacilitatorClient({
  url: process.env.X402_FACILITATOR_URL!,
});

// In-memory store (use Redis/DB in production)
const sessionStore = createMemoryX402SessionStore();

// Pass to any middleware
const x402Config = {
  facilitator,
  resource: { url: "/api/premium", description: "Premium access" },
  accepts: [/* ... */],
  session: {
    store: sessionStore,
    ttl: 3600_000,  // 1 hour
  },
};

On the first request, the agent pays and the middleware stores a session. On subsequent requests from the same agent to the same resource, the session is found and payment is skipped. After TTL expiry, payment is required again.

For production, implement the X402SessionStore interface with a shared store:

interface X402SessionStore {
  get(address: string, resource: string): Promise<X402Session | null>;
  set(address: string, resource: string, session: X402Session, ttlMs: number): Promise<void>;
}

interface X402Session {
  paidAt: number;
  txHash?: string;
}

Config Reference

Use createFacilitatorClient({ url }) to create a client that POSTs to /verify and /settle endpoints on the facilitator. Import from @buildersgarden/siwa/x402.

Middleware

Each framework wrapper accepts an optional x402 field. When set, both SIWA authentication and a valid payment are required. The verified payment is available in the handler.

import express from "express";
import { siwaMiddleware, siwaJsonParser, siwaCors } from "@buildersgarden/siwa/express";
import { createFacilitatorClient } from "@buildersgarden/siwa/x402";
...

// app/api/premium/route.ts
import { withSiwa, siwaOptions } from "@buildersgarden/siwa/next";
import { createFacilitatorClient } from "@buildersgarden/siwa/x402";
...

import { Hono } from "hono";
import { siwaMiddleware, siwaCors } from "@buildersgarden/siwa/hono";
import { createFacilitatorClient } from "@buildersgarden/siwa/x402";
...

import Fastify from "fastify";
import { siwaPlugin, siwaAuth } from "@buildersgarden/siwa/fastify";
import { createFacilitatorClient } from "@buildersgarden/siwa/x402";
...

Agent-Side

When an agent receives a 402 response, it should:

1. 1.Read the Payment-Required header and decode the payment options.
2. 2.Construct a PaymentPayload with the signed payment.
3. 3.Encode it as a Payment-Signature header and retry the request.

import {
  encodeX402Header,
  decodeX402Header,
...

Identity File

Import from @buildersgarden/siwa/identity.

Onchain Registry

Import from @buildersgarden/siwa/registry.

Message Format

{domain} wants you to sign in with your Agent account:
{address}

{statement}

URI: {uri}
Version: 1
Agent ID: {agentId}
Agent Registry: {agentRegistry}
Chain ID: {chainId}
Nonce: {nonce}
Issued At: {issuedAt}
[Expiration Time: {expirationTime}]
[Not Before: {notBefore}]
[Request ID: {requestId}]

Field Definitions

See Address Formatting Standards for details on CAIP-10, EIP-55, and EIP-155.

SIWA vs SIWE

Mainnet

Testnets

Address Formatting Standards

SIWA uses standardized address formats from the blockchain ecosystem:

The agentRegistry field uses CAIP-10 format to uniquely identify the ERC-8004 Identity Registry contract on a specific chain:

{namespace}:{chainId}:{contractAddress}

Format breakdown:
  namespace       = "eip155" (EVM-compatible chains per EIP-155)
  chainId         = numeric chain identifier (e.g., 8453 for Base)
  contractAddress = EIP-55 checksummed contract address

Examples:
  eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432    (Base mainnet)
  eip155:84532:0x8004A818BFB912233c491871b3d84c89A494BD9e   (Base Sepolia)
  eip155:1:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432      (Ethereum mainnet)

All wallet addresses (address field) must be EIP-55 checksummed. This provides error detection for typos:

Correct (checksummed):   0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0
Incorrect (lowercase):   0x742d35cc6634c0532925a3b844bc9e7595f0beb0

Most libraries (viem, ethers.js) automatically return checksummed addresses. You can use getAddress() from viem to ensure proper formatting.

The chainId field identifies which blockchain network the agent is registered on. Common chain IDs:

Public RPC Endpoints

For production, use a provider like Alchemy or Infura with your own API key.

Explorer

View registered agents at 8004scan.io