Siwa

SIWA SDK

Sign-In With Agent (SIWA) lets AI agents authenticate with services using their ERC-8004 onchain identity.

Install

npm install @buildersgarden/siwa

Skills

Agent-Side (Signing)

Choose based on your wallet provider:

• Bankr — Bankr Agent API wallets

Server-Side (Verification)

• Server-Side Verification — Next.js, Express, Hono, Fastify

SDK Modules

Links

• Latest version of this skill
• Documentation
• ERC-8004
• ERC-8128

SIWA Bankr Signer

Latest version: https://siwa.id/skills/bankr/skill.md

Sign SIWA messages using Bankr's Agent API wallets.

Install

npm install @buildersgarden/siwa

No additional SDK is required — the Bankr signer communicates directly with the Bankr Agent API over HTTP.

Create Signer

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

const signer = await createBankrSiwaSigner({
  apiKey: process.env.BANKR_API_KEY!,
});

The wallet address is fetched automatically from Bankr's /agent/me endpoint.

Register as ERC-8004 Agent

Bankr wallets are smart contract accounts (ERC-4337). To register on the ERC-8004 Identity Registry, submit the registration as an arbitrary transaction via Bankr's /agent/submit endpoint.

Supported Networks

The Bankr /agent/submit endpoint supports these chains:

Transaction Format

The /agent/submit endpoint requires a transaction object with these fields:

Example

import { encodeRegisterAgent } from "@buildersgarden/siwa/registry";

// Prepare agent metadata
const metadata = {
  name: "My Agent",
  description: "A helpful AI assistant",
  capabilities: ["chat", "analysis"],
};
const agentURI = `data:application/json;base64,${Buffer.from(JSON.stringify(metadata)).toString("base64")}`;

// Encode the registration calldata (resolves the registry address automatically)
const { to, data } = encodeRegisterAgent({ agentURI, chainId: 8453 });

// Submit as arbitrary transaction via Bankr API
const submitRes = await fetch("https://api.bankr.bot/agent/submit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.BANKR_API_KEY!,
  },
  body: JSON.stringify({
    transaction: { to, data, value: "0", chainId: 8453 },
    waitForConfirmation: true,
  }),
});

const result = await submitRes.json();
console.log("Transaction hash:", result.txHash);

Important: Transactions submitted via /agent/submit are irreversible. Always verify calldata encoding and confirm the target contract address before submitting. Ensure the wallet has sufficient ETH/MATIC for gas. The endpoint handles UserOperation bundling internally for ERC-4337 smart accounts, and SIWA verification uses ERC-1271 automatically.

---

SIWA Authentication Flow

The authentication flow consists of two steps:

Note: The URLs below (api.example.com) are placeholders. Replace them with your own server that implements the SIWA verification endpoints. See the Server-Side Verification skill for implementation details.

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

Step 1: Request Nonce

const nonceRes = await fetch("https://api.example.com/siwa/mainnet/nonce", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address: await signer.getAddress(),
    agentId: 42,
    agentRegistry: "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
  }),
});
const { nonce, nonceToken, issuedAt, expirationTime } = await nonceRes.json();

Step 2: Sign and Verify

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

const { message, signature, address } = await signSIWAMessage({
  domain: "api.example.com",
  uri: "https://api.example.com/siwa",
  agentId: 42,
  agentRegistry: "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432", //According to the chain
  chainId: 8453,
  nonce,
  issuedAt,
  expirationTime,
}, signer);

// Send to server for verification
const verifyRes = await fetch("https://api.example.com/siwa/mainnet/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message, signature, nonceToken }),
});

const { receipt, agentId } = await verifyRes.json();
// Store the receipt for authenticated API calls

Sign Authenticated Request (ERC-8128)

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

const request = new Request("https://api.example.com/action", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ action: "execute" }),
});

const signedRequest = await signAuthenticatedRequest(
  request,
  receipt,  // from SIWA sign-in
  signer,
  8453,
);

const response = await fetch(signedRequest);

Environment Variables

BANKR_API_KEY=your-bankr-api-key

Already using Bankr?

If your agent already uses Bankr's OpenClaw trading skill for swaps, bridges, or DeFi, this signer lets you add SIWA authentication on top — same API key, same wallet, no extra setup. Bankr's trading skill handles what your agent does; the SIWA signer handles how your agent proves who it is.

SIWA Server-Side Verification

Latest version: https://siwa.id/skills/server-side/skill.md

Verify SIWA authentication and protect API routes with ERC-8128 signed requests.

Install

npm install @buildersgarden/siwa viem

Overview

Server-side verification requires three parts:

1. Nonce Endpoint (/siwa/nonce) — Issue a nonce for the agent to sign 2. Verify Endpoint (/siwa/verify) — Verify the signed message and issue a receipt 3. ERC-8128 Middleware — Verify subsequent API requests using the receipt

---

Nonce Endpoint

Issue a nonce for the agent to include in their SIWA message. The nonce prevents replay attacks.

Next.js

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

const client = createPublicClient({
  chain: baseSepolia,
  transport: http(process.env.RPC_URL),
});

// Simple in-memory nonce store (use Redis in production)
const nonceStore = new Map<string, number>();

export async function POST(req: Request) {
  const { address, agentId, agentRegistry } = await req.json();

  const result = await createSIWANonce(
    { address, agentId, agentRegistry },
    client,
  );

  // Store nonce for verification
  nonceStore.set(result.nonce, Date.now());

  return corsJson({
    nonce: result.nonce,
    issuedAt: result.issuedAt,
    expirationTime: result.expirationTime,
  });
}

export { siwaOptions as OPTIONS };

Express

// routes/siwa.ts
import express from "express";
import { createSIWANonce } from "@buildersgarden/siwa";
import { siwaCors, siwaJsonParser } from "@buildersgarden/siwa/express";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";

const router = express.Router();
router.use(siwaJsonParser());
router.use(siwaCors());

const client = createPublicClient({
  chain: baseSepolia,
  transport: http(process.env.RPC_URL),
});

const nonceStore = new Map<string, number>();

router.post("/nonce", async (req, res) => {
  const { address, agentId, agentRegistry } = req.body;

  const result = await createSIWANonce(
    { address, agentId, agentRegistry },
    client,
  );

  nonceStore.set(result.nonce, Date.now());

  res.json({
    nonce: result.nonce,
    issuedAt: result.issuedAt,
    expirationTime: result.expirationTime,
  });
});

export default router;

Hono

// src/routes/siwa.ts
import { Hono } from "hono";
import { cors } from "hono/cors";
import { createSIWANonce } from "@buildersgarden/siwa";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";

const app = new Hono();

app.use("*", cors({
  origin: "*",
  allowHeaders: ["Content-Type", "X-SIWA-Receipt", "Signature", "Signature-Input", "Content-Digest"],
}));

const client = createPublicClient({
  chain: baseSepolia,
  transport: http(process.env.RPC_URL),
});

const nonceStore = new Map<string, number>();

app.post("/nonce", async (c) => {
  const { address, agentId, agentRegistry } = await c.req.json();

  const result = await createSIWANonce(
    { address, agentId, agentRegistry },
    client,
  );

  nonceStore.set(result.nonce, Date.now());

  return c.json({
    nonce: result.nonce,
    issuedAt: result.issuedAt,
    expirationTime: result.expirationTime,
  });
});

export default app;

Fastify

// src/routes/siwa.ts
import { FastifyPluginAsync } from "fastify";
import { createSIWANonce } from "@buildersgarden/siwa";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";

const client = createPublicClient({
  chain: baseSepolia,
  transport: http(process.env.RPC_URL),
});

const nonceStore = new Map<string, number>();

const siwaRoutes: FastifyPluginAsync = async (fastify) => {
  fastify.post("/nonce", async (req) => {
    const { address, agentId, agentRegistry } = req.body as {
      address: string;
      agentId: number;
      agentRegistry: string;
    };

    const result = await createSIWANonce(
      { address, agentId, agentRegistry },
      client,
    );

    nonceStore.set(result.nonce, Date.now());

    return {
      nonce: result.nonce,
      issuedAt: result.issuedAt,
      expirationTime: result.expirationTime,
    };
  });
};

export default siwaRoutes;

---

Verify Endpoint

Verify the signed SIWA message and issue an HMAC receipt.

Next.js

// app/api/siwa/verify/route.ts
import { verifySIWA } from "@buildersgarden/siwa";
import { createReceipt } from "@buildersgarden/siwa/receipt";
import { corsJson, siwaOptions } from "@buildersgarden/siwa/next";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";

const client = createPublicClient({
  chain: baseSepolia,
  transport: http(process.env.RPC_URL),
});

// Shared with nonce endpoint
const nonceStore = new Map<string, number>();

export async function POST(req: Request) {
  const { message, signature } = await req.json();

  const result = await verifySIWA(
    message,
    signature,
    "api.example.com",
    (nonce) => {
      if (!nonceStore.has(nonce)) return false;
      nonceStore.delete(nonce); // consume nonce
      return true;
    },
    client,
  );

  if (!result.valid) {
    return corsJson({ error: result.error }, { status: 401 });
  }

  const { receipt } = createReceipt({
    address: result.address,
    agentId: result.agentId,
    agentRegistry: result.agentRegistry,
    chainId: result.chainId,
    signerType: result.signerType,
  }, { secret: process.env.RECEIPT_SECRET! });

  return corsJson({ receipt, agentId: result.agentId });
}

export { siwaOptions as OPTIONS };

Express

// routes/siwa.ts (add to same router)
router.post("/verify", async (req, res) => {
  const { message, signature } = req.body;

  const result = await verifySIWA(
    message,
    signature,
    "api.example.com",
    (nonce) => {
      if (!nonceStore.has(nonce)) return false;
      nonceStore.delete(nonce);
      return true;
    },
    client,
  );

  if (!result.valid) {
    return res.status(401).json({ error: result.error });
  }

  const { receipt } = createReceipt({
    address: result.address,
    agentId: result.agentId,
    agentRegistry: result.agentRegistry,
    chainId: result.chainId,
    signerType: result.signerType,
  }, { secret: process.env.RECEIPT_SECRET! });

  res.json({ receipt, agentId: result.agentId });
});

Hono

// src/routes/siwa.ts (add to same app)
app.post("/verify", async (c) => {
  const { message, signature } = await c.req.json();

  const result = await verifySIWA(
    message,
    signature,
    "api.example.com",
    (nonce) => {
      if (!nonceStore.has(nonce)) return false;
      nonceStore.delete(nonce);
      return true;
    },
    client,
  );

  if (!result.valid) {
    return c.json({ error: result.error }, 401);
  }

  const { receipt } = createReceipt({
    address: result.address,
    agentId: result.agentId,
    agentRegistry: result.agentRegistry,
    chainId: result.chainId,
    signerType: result.signerType,
  }, { secret: process.env.RECEIPT_SECRET! });

  return c.json({ receipt, agentId: result.agentId });
});

Fastify

// src/routes/siwa.ts (add to same plugin)
fastify.post("/verify", async (req, reply) => {
  const { message, signature } = req.body as { message: string; signature: string };

  const result = await verifySIWA(
    message,
    signature,
    "api.example.com",
    (nonce) => {
      if (!nonceStore.has(nonce)) return false;
      nonceStore.delete(nonce);
      return true;
    },
    client,
  );

  if (!result.valid) {
    return reply.status(401).send({ error: result.error });
  }

  const { receipt } = createReceipt({
    address: result.address,
    agentId: result.agentId,
    agentRegistry: result.agentRegistry,
    chainId: result.chainId,
    signerType: result.signerType,
  }, { secret: process.env.RECEIPT_SECRET! });

  return { receipt, agentId: result.agentId };
});

---

Protected Routes (ERC-8128 Middleware)

After sign-in, protect API routes with ERC-8128 signature verification.

Next.js

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

export const POST = withSiwa(async (agent, req) => {
  const body = await req.json();
  return { received: body, agent };
});

export { siwaOptions as OPTIONS };

Express

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

const app = express();
app.use(siwaJsonParser());
app.use(siwaCors());

app.post("/api/protected", siwaMiddleware(), (req, res) => {
  res.json({ agent: req.agent });
});

Hono

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

const app = new Hono();
app.use("*", siwaCors());

app.post("/api/protected", siwaMiddleware(), (c) => {
  return c.json({ agent: c.get("agent") });
});

Fastify

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

const fastify = Fastify();
await fastify.register(siwaPlugin);

fastify.post("/api/protected", { preHandler: siwaAuth() }, async (req) => {
  return { agent: req.agent };
});

---

Middleware Options

---

Environment Variables

RECEIPT_SECRET=your-hmac-secret-min-32-chars
RPC_URL=https://sepolia.base.org