SIWA — Sign In With Agent

SIWA lets AI agents prove who they are. Think Sign In With Ethereum, but for agents instead of humans.

An agent signs a message proving it owns an ERC-8004 identity NFT. The server verifies the signature and checks onchain ownership. If it all checks out, the agent gets a verification receipt and uses ERC-8128 HTTP Message Signatures for all subsequent API calls.

For AI agents: Read siwa.id/skill.md for structured instructions.

Quick Start

npm install @buildersgarden/siwa

Agent-Side: Choose Your Wallet Provider

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

// Create signer
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const signer = createLocalAccountSigner(account);

// Sign SIWA message
const { message, signature } = await signSIWAMessage({
  domain: "api.example.com",
  uri: "https://api.example.com/siwa",
  agentId: 42,
  agentRegistry: "eip155:84532:0x8004A818BFB912233c491871b3d84c89A494BD9e",
  chainId: 84532,
  nonce,
  issuedAt,
}, signer);

Server-Side: Choose Your Framework

// Next.js example
import { withSiwa, siwaOptions } from "@buildersgarden/siwa/next";

export const POST = withSiwa(async (agent, req) => {
  return { agent: agent.address, agentId: agent.agentId };
});

export { siwaOptions as OPTIONS };

For full examples, see the documentation.

How It Works

1. The agent asks the server for a nonce (/siwa/nonce) — the server checks onchain registration before issuing it
2. The agent builds a SIWA message and signs it
3. The agent sends the signature to verify (/siwa/verify) — the server confirms ownership onchain
4. The server returns a verification receipt
5. For subsequent API calls, the agent uses ERC-8128 per-request signatures with the receipt attached

The agent’s private key can be kept in a separate keyring proxy process, so the agent never touches it directly.

Try It Locally

git clone https://github.com/builders-garden/siwa
cd siwa && pnpm install
cd packages/siwa-testing && pnpm run dev

Repository Structure

SDK Modules

Docker

# Proxy + OpenClaw gateway
cp .env.proxy.example .env   # fill in secrets
docker compose -f docker-compose.proxy.yml up -d

# Full integration (proxy + SIWA server + OpenClaw)
docker compose -f docker-compose.test.yml up -d --build

Links

• Documentation
• Skill for AI Agents
• API Endpoints
• Deployment Guide
• ERC-8004 Standard
• Agent Explorer (8004scan)

License

MIT — Builders Garden SRL 2025