SIWA Documentation

Deploy

Spin up a secure onchain agent in one click. This deploys everything you need — a signing proxy that keeps keys safe and an agent gateway, pre-wired and ready to go.

Once deployed, your agent has a wallet, can register onchain, and authenticate with any SIWA-compatible service. For configuration details, see the deployment guide.

How It Works

1. 1.The agent asks the service for a nonce (a one-time challenge), sending its address and agent ID.
2. 2.The service returns the nonce along with timestamps.
3. 3.The agent builds a SIWA message containing those fields and signs it with its private key.
4. 4.The agent sends the message and signature back to the service.
5. 5.The service verifies the signature and calls the blockchain to confirm the agent actually owns that identity NFT.
6. 6.If everything checks out, the service returns a verification receipt. The agent attaches this receipt to every subsequent request, signed with ERC-8128 HTTP Message Signatures.

The SDK gives you two functions to implement this:

• •Agent-side: call signSIWAMessage(), which builds the message and signs it in one step (steps 3-4 above).
• •Server-side: call verifySIWA() to validate the signature, check all fields, and recover the agent's identity (step 5).

Network Topology

A deployed SIWA agent runs as a set of containers on a private network. Each component has a single job:

• •Keyring Proxy — holds the agent's encrypted private key and performs all signing. Never exposed publicly.
• •OpenClaw — the AI agent gateway. Routes messages from users, delegates signing to the keyring proxy, and handles onchain verification and registration.
• •2FA Gateway + Server (optional) — adds Telegram-based owner approval before high-value signing operations. The gateway receives Telegram webhooks; the server manages approval flows. The agent owner gets a Telegram message and taps to approve or reject.

The keyring proxy, OpenClaw, and 2FA server communicate over a private Docker network — none of them need public internet access. Only the 2FA gateway (for Telegram webhooks) and OpenClaw (for user-facing chat) are exposed externally.

Signing

All signing is delegated to the keyring proxy — the agent process never touches the private key.

Import from @buildersgarden/siwa/keystore. All functions accept an optional KeystoreConfig ({proxyUrl, proxySecret}).

Import from @buildersgarden/siwa.

After SIWA sign-in, every subsequent API request is signed with ERC-8128 HTTP Message Signatures and carries a verification receipt.

Import from @buildersgarden/siwa/erc8128.

Verification

Server-side functions for verifying agent identity and authenticating requests.

Verify a SIWA signature, check onchain ownership, and optionally validate agent profile and reputation — all in one call.

Import from @buildersgarden/siwa. The optional criteria argument validates the agent's profile after the ownership check:

import { verifySIWA } from '@buildersgarden/siwa';

const result = await verifySIWA(
  message,
  signature,
  'api.example.com',
  (nonce) => nonceStore.consume(nonce),
  client,
  {
    mustBeActive: true,
    requiredServices: ['MCP'],
    minScore: 0.5,
    reputationRegistryAddress: '0x8004BAa1...9b63',
  }
);

Verify the ERC-8128 signature and receipt on incoming requests.

Import from @buildersgarden/siwa/erc8128. VerifyOptions: receiptSecret, rpcUrl, verifyOnchain, publicClient.

Stateless HMAC-signed tokens that prove onchain registration was checked during SIWA sign-in.

Import from @buildersgarden/siwa/receipt.

Server Wrappers

High-level middleware that handles ERC-8128 verification, receipt checking, CORS, and error responses — so you don't have to wire the low-level functions yourself.

import { withSiwa, siwaOptions } from "@buildersgarden/siwa/next";

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

export const GET = withSiwa(async (agent) => {
  return { message: `Hello Agent #${agent.agentId}!` };
});

export { siwaOptions as OPTIONS };

Options: receiptSecret (defaults to RECEIPT_SECRET or SIWA_SECRET env), rpcUrl, verifyOnchain.

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

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

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

Identity & Registry

Read and write agent identity state, and query onchain profiles and reputation.

The agent's IDENTITY.md stores 4 public fields: Address, Agent ID, Agent Registry, Chain ID.

Import from @buildersgarden/siwa/identity.

Import from @buildersgarden/siwa/registry. Both accept a viem PublicClient via options.client.

Helpers

Keyring Proxy

All signing is delegated to a separate keyring proxy server over HMAC-authenticated HTTP. The proxy holds the encrypted key and performs all cryptographic operations.

Agent Process                     Keyring Proxy
(KEYSTORE_BACKEND=proxy)          (holds encrypted key)

signMessage("hello")
  |
  +--> POST /sign-message
       + HMAC-SHA256 header  ---> Validates HMAC + timestamp (30s)
                                  Loads key, signs, discards
                              <-- Returns { signature, address }

Threat Model

IDENTITY.md: Public Data Only

The agent's identity file stores only public state — address, agentId, agentRegistry, chainId. The private key is never written to IDENTITY.md or any other file the agent reads.

2FA via Telegram

For high-value operations, the keyring proxy can require owner approval before signing. This adds a second factor — the agent can request a signature, but the owner must explicitly approve it through Telegram.

Agent requests signature
  |
  +--> Keyring Proxy
       |
       +--> 2FA Server (approval queue)
            |
            +--> 2FA Gateway --> Telegram bot message
                                 Owner taps Approve / Reject
                             <-- Callback to 2FA Server
       <-- Signature (if approved)
  <-- Returns to agent

The flow adds two components to the private network:

Both the keyring proxy and the 2FA server run inside the private network — they are never exposed publicly. Only the 2FA gateway needs internet access for Telegram webhooks.

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

Authentication Flow

1. Nonce Request — Agent sends address, agentId, agentRegistry to POST /siwa/nonce. Server returns nonce + timestamps.

2. Agent Signs — Agent builds SIWA message and signs via EIP-191 personal_sign.

3. Verification — Agent submits message + signature to POST /siwa/verify.

4. Server Checks — Parse message, recover signer, verify address match, check domain binding, validate nonce + time window, call ownerOf(agentId) onchain.

5. Receipt — Issue an HMAC-signed verification receipt with address, agentId, agentRegistry, chainId. Agent uses this with ERC-8128 per-request signatures.

SIWA vs SIWE

Mainnet

Testnets

Solana

Agent Registry String Format

{namespace}:{chainId}:{identityRegistryAddress}

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

Public RPC Endpoints

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

Explorer

View any registered agent at 8004scan.io