playbooks

home / skills / bankrbot / skills / siwa

siwa skill

/siwa

This skill enables agents to authenticate using Sign-In With Agent SIWA and ERC-8004 identity across services.

npx playbooks add skill bankrbot/skills --skill siwa

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.5 KB
---
name: siwa
version: 0.2.0
description: >
  SIWA (Sign-In With Agent) authentication for ERC-8004 registered agents.
metadata:
  {
    "clawdbot":
      {
        "emoji": "🔐",
        "homepage": "https://siwa.id",
      },
  }
---

# SIWA SDK

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

## Install

```bash
npm install @buildersgarden/siwa
```

## Skills

### Agent-Side (Signing)

Choose based on your wallet provider:

- [Bankr](references/bankr-signer.md) — Bankr Agent API wallets

### Server-Side (Verification)

- [Server-Side Verification](references/server-side.md) — Next.js, Express, Hono, Fastify

## SDK Modules

| Import | Description |
|--------|-------------|
| `@buildersgarden/siwa` | Core: signSIWAMessage, verifySIWA, createSIWANonce |
| `@buildersgarden/siwa/signer` | Signer factories |
| `@buildersgarden/siwa/erc8128` | ERC-8128 HTTP signing/verification |
| `@buildersgarden/siwa/receipt` | HMAC receipt helpers |
| `@buildersgarden/siwa/nonce-store` | Nonce stores (Memory, Redis, KV) |
| `@buildersgarden/siwa/next` | Next.js middleware |
| `@buildersgarden/siwa/express` | Express middleware |
| `@buildersgarden/siwa/hono` | Hono middleware |
| `@buildersgarden/siwa/fastify` | Fastify middleware |

## Links

- [Latest version of this skill](https://siwa.id/skill.md)
- [Documentation](https://siwa.id/docs)
- [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004)
- [ERC-8128](https://eips.ethereum.org/EIPS/eip-8128)

Overview

This skill provides Sign-In With Agent (SIWA) authentication for ERC-8004 registered agents, enabling agents to authenticate to services using an onchain identity. It bundles signer factories, message signing and verification, nonce stores, and middleware for popular server frameworks. The skill is plug-and-play for agent builders who need secure, verifiable agent authentication workflows.

How this skill works

The SDK signs standardized SIWA messages with an agent's ERC-8004 identity and verifies those signatures server-side. It issues and validates nonces, supports HMAC receipts and ERC-8128 HTTP signing, and offers middleware for Next.js, Express, Hono, and Fastify to streamline integration. Signer factories let you plug in wallet providers like Bankr with minimal code changes.

When to use it

  • Add cryptographic agent authentication to APIs and web apps
  • Enable agents to authenticate without traditional username/password flows
  • Verify agent identity for sensitive actions or auditing
  • Integrate onchain identity into session or token systems
  • Protect agent-to-service webhooks and HTTP requests

Best practices

  • Use the provided nonce stores (Redis or KV) in production to prevent replay attacks
  • Combine ERC-8128 HTTP signing for integrity of API payloads with SIWA for identity proofs
  • Run server-side verification middleware on all endpoints that accept agent requests
  • Store minimal agent state server-side; rely on signed assertions for authorization
  • Rotate HMAC secrets and monitor failed verification attempts

Example use cases

  • Agent dashboard login using ERC-8004 identity instead of passwords
  • API endpoints that accept agent-signed requests validated via ERC-8128
  • Webhook receivers that verify HMAC receipts and SIWA signatures before processing
  • Multi-agent platforms where agents act on behalf of users with verifiable onchain identities
  • Agent orchestration systems that need auditable, non-repudiable action records

FAQ

Which frameworks are supported for server-side verification?

Middleware and helpers are provided for Next.js, Express, Hono, and Fastify to simplify verification and nonce handling.

What wallet providers can sign SIWA messages?

Signer factories let you use providers like Bankr Agent API wallets; the SDK is extensible to other wallets via signer interfaces.

How do I prevent replay attacks?

Use a nonce store (Memory for dev, Redis or KV for production) and verify nonces on each signed message to prevent reuse.