Deploy Keyring Proxy

Security Model

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

Agent Process                     Keyring Proxy
(uses Signer interface)           (holds encrypted key)

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

Threat Model

Network Topology

A deployed keyring proxy setup runs as a set of services on a private network:

• •Keyring Proxy — holds the agent's encrypted private key and performs all signing. Never exposed publicly.
• •Your Agent — AI agent (OpenClaw, custom framework, etc). Uses the SIWA SDK to request signatures.
• •2FA Gateway + Server (optional) — adds Telegram-based owner approval before signing. The gateway receives webhooks; the server manages approval flows.

The keyring proxy and 2FA server communicate over a private network. Only the 2FA gateway (for Telegram webhooks) and your agent (for user-facing interface) are exposed externally.

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:

🔐 SIWA Signing Request

📋 Request ID: abc123
⏱️ Expires: 60 seconds

🔑 Wallet: 0x742d35Cc...
📝 Operation: Sign Transaction
⛓️ Chain: Base (8453)

📤 To: 0xdead...beef
💰 Value: 0.5 ETH

[✅ Approve]  [❌ Reject]

Railway Account

You need a Railway account. That's it for the one-click deployment.

2FA Bot Setup (Optional)

To enable 2FA, create a Telegram bot before deploying:

Configuration

During deployment, Railway will prompt you for:

Once deployed, open OpenClaw and chat with your agent. The SIWA skill is pre-installed — ask it to create a wallet and register onchain.

Create a Signer

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

const signer = createKeyringProxySigner({
  proxyUrl: process.env.KEYRING_PROXY_URL,
  proxySecret: process.env.KEYRING_PROXY_SECRET,
});

// Use with any SIWA function
const { message, signature } = await signSIWAMessage(fields, signer);
const signedRequest = await signAuthenticatedRequest(req, receipt, signer, chainId);

Admin Functions

Create and manage wallets via the keystore module:

import { createWallet, hasWallet, getAddress } from "@buildersgarden/siwa/keystore";

// Check if wallet exists
const exists = await hasWallet();

// Create a new wallet (key stored in proxy)
const { address } = await createWallet();

// Get the wallet address
const addr = await getAddress();

Sign Transactions

Sign and broadcast transactions via the signer:

import { createKeyringProxySigner } from "@buildersgarden/siwa/signer";
import { createPublicClient, http, parseEther } from "viem";
import { base } from "viem/chains";

const signer = createKeyringProxySigner({
  proxyUrl: process.env.KEYRING_PROXY_URL,
  proxySecret: process.env.KEYRING_PROXY_SECRET,
});

const client = createPublicClient({ chain: base, transport: http() });
const address = await signer.getAddress();

const tx = {
  to: "0xRecipient...",
  value: parseEther("0.01"),
  nonce: await client.getTransactionCount({ address }),
  chainId: base.id,
  type: 2,
  maxFeePerGas: 1000000000n,
  maxPriorityFeePerGas: 1000000n,
  gas: 21000n,
};

// Sign via proxy (if 2FA enabled, requires Telegram approval)
const signedTx = await signer.signTransaction(tx);

// Broadcast
const hash = await client.sendRawTransaction({ serializedTransaction: signedTx });

Repository

git clone https://github.com/builders-garden/siwa.git
cd siwa

Each service has its own Dockerfile in packages/:

Build & Deploy

# Keyring Proxy
docker build -t keyring-proxy -f packages/keyring-proxy/Dockerfile .

# 2FA Server
docker build -t 2fa-telegram -f packages/2fa-telegram/Dockerfile .

# 2FA Gateway
docker build -t 2fa-gateway -f packages/2fa-gateway/Dockerfile .

Make sure services can communicate:

• Keyring Proxy — only accessible from your agent (private network)
• 2FA Gateway — needs a public URL for Telegram webhooks
• 2FA Server — only accessible from keyring proxy and 2FA gateway

Environment Variables

keyring-proxy:

2fa-telegram:

2fa-gateway:

Using an Existing Wallet

Import an existing private key instead of creating a new wallet:

KEYSTORE_BACKEND=env
AGENT_PRIVATE_KEY=0x<your-private-key>

Useful when migrating an existing agent or using a wallet that already holds funds. Note: the key is held in memory at runtime. For higher security, prefer the encrypted-file backend.

Using an Existing Agent

If you have an existing AI agent, deploy only the Keyring Proxy and 2FA services. This template exposes the Keyring Proxy publicly via HTTPS:

Deploy Keyring Proxy + 2FA Only

Connect your existing agent via HTTPS.

Security implications:

• The keyring proxy becomes accessible over the internet
• If KEYRING_PROXY_SECRET is leaked, anyone can request signatures
• All signing requests still require 2FA approval (if enabled)

Recommended:

• Always enable 2FA — Even if the HMAC secret is compromised, attackers cannot complete transactions without your Telegram approval.
• Use Tailscale — Enforce that only your agent machine can connect to the keyring proxy.

Connect your agent:

KEYRING_PROXY_URL=https://your-keyring-proxy.example.com
KEYRING_PROXY_SECRET=<your-hmac-secret>