KeeperGuard

KeeperGuard is a policy firewall that gets an AI agent from intent to a verified onchain transaction through KeeperHub without handing the model a private key. It enforces a recipient allowlist and amount cap, locks mainnet, simulates every write, broadcasts with an idempotency key, follows KeeperHub's polling hints, and accepts success only when the final response contains an onchain transaction hash.

The first transaction executed end to end by KeeperGuard is live on Base Sepolia: 0xd61f552e...214ffab. KeeperHub sponsored the gas, so no user funds were deposited or spent.

Watch the 67-second uncut demo. It shows a fail-closed rejection, a live KeeperHub simulation, the recorded terminal proof, independent RPC verification, and the safety test suite. The recording script is available at scripts/demo.ps1.

Why this exists

KeeperHub already exposes the primitives for safe execution, but a new builder has to assemble them across account setup, wallet discovery, chain discovery, simulation, idempotency, status polling, and explorer verification. Several official onboarding paths stop at a read-only workflow rather than a real transaction. KeeperGuard turns the safe path into one reproducible agent loop and fails closed when any proof is missing.

Quick start

Requirements:

• Node.js 22 or newer
• A verified KeeperHub account
• A revocable organization API key with the kh_ prefix

Set the key only for the current shell. Do not save it in the repository.

PowerShell:

$env:KEEPERHUB_API_KEY = Read-Host 'KeeperHub API key'

Bash:

read -rsp 'KeeperHub API key: ' KEEPERHUB_API_KEY
export KEEPERHUB_API_KEY

Check that the organization wallet and Base Sepolia are ready:

npm run doctor -- --chain 84532 --json

Simulate a zero-value self-transfer. Replace the address with the organization wallet returned by doctor:

npm start -- \
  --chain 84532 \
  --to 0xYourOrganizationWallet \
  --amount 0 \
  --allow-recipient

The default is simulation only. Nothing is signed or broadcast. If the result passes, repeat the exact intent with --broadcast:

npm start -- \
  --chain 84532 \
  --to 0xYourOrganizationWallet \
  --amount 0 \
  --allow-recipient \
  --broadcast

KeeperGuard prints the final explorer link and writes a redacted JSONL audit trail to .keeperguard/audit.jsonl. If a connection is interrupted after broadcast, rerun with the idempotency key recorded in the broadcast_authorized event.

Safety model

The model can propose an intent, but it cannot relax the execution policy.

1. Discover the live chain catalog from KeeperHub.
2. Reject disabled chains and all mainnets.
3. Normalize addresses and decimal amounts without floating-point arithmetic.
4. Require an explicit recipient allowlist and enforce the amount cap.
5. Simulate the exact intent and require success: true plus wouldRevert: false.
6. Persist an idempotency key before broadcast.
7. Poll according to X-Poll-Interval-Hint.
8. Require completed, the expected chain, and a transaction hash.
9. Redact credentials from the audit trail.

The Turnkey-backed KeeperHub wallet signs inside secure infrastructure; KeeperGuard never receives a private key.

Architecture

AI agent / operator
        |
        v
KeeperGuard intent policy
  allowlist | cap | testnet lock
        |
        v
KeeperHub simulation
        |
        v
KeeperHub sponsored execution
        |
        v
receipt + explorer proof + redacted audit

Verification

Run the dependency-free test suite and verify the committed transaction proof against the public Base Sepolia RPC:

npm test
npm run check
npm run verify-proof

The tests cover mainnet lockout, recipient and cap enforcement, strict decimal parsing, simulation-before-broadcast ordering, idempotency headers, 429 retry hints, terminal proof validation, chain mismatch, and credential redaction.

KeeperHub contribution

Building this starter surfaced a concrete agent onboarding gap: the REST direct execution routes support simulate: true, but the MCP direct execution tools do not expose it. The companion KeeperHub patch adds a strict optional boolean to the EVM paths in all three MCP write tools, forwards it to the existing dry-run paths, rejects unsupported Solana simulation before the API call, and documents a safe first-write sequence. This lets an MCP-native agent preflight without switching surfaces or risking an accidental broadcast. See KeeperHub PR #1858.

See Onboarding findings and the full threat model.

Status

KeeperGuard is a testnet-first hackathon starter. Mainnet is intentionally locked in this release. It is not financial advice and has not been audited.